[oneTBB] Heterogeneous overloads for concurrent_hash_map (#356)

* Add description for heterogeneous overloads in chmap

* Fix PR comments

* More minor changes

* Fix minor comments from PR

* Update source/elements/oneTBB/source/containers/concurrent_hash_map_cls.rst

Co-authored-by: Ivan Kochin <kochin.ivan@intel.com>

* Minor fix

Co-authored-by: Ivan Kochin <kochin.ivan@intel.com>

Author: kboyarinov

source/elements/oneTBB/source/containers/concurrent_hash_map_cls.rst

@@ -112,15 +112,29 @@ Class Template Synopsis
                    bool find( const_accessor& result, const key_type& key ) const;
                    bool find( accessor& result, const key_type& key );
 
+                   template <typename K>
+                   bool find( const_accessor& result, const K& key ) const;
+
+                   template <typename K>
+                   bool find( accessor& result, const K& key );
+
                    size_type count( const key_type& key ) const;
 
+                   template <typename K>
+                   size_type count( const K& key ) const;
+
                    // Modifiers
                    bool insert( const_accessor& result, const key_type& key );
                    bool insert( accessor& result, const key_type& key );
 
+                   template <typename K>
+                   bool insert( const_accessor& result, const K& key );
+
+                   template <typename K>
+                   bool insert( accessor& result, const K& key );
+
                    bool insert( const_accessor& result, const value_type& value );
                    bool insert( accessor& result, const value_type& value );
-
                    bool insert( const_accessor& result, value_type&& value );
                    bool insert( accessor& result, value_type&& value );
 
@@ -143,6 +157,9 @@ Class Template Synopsis
 
                    bool erase( const key_type& key );
 
+                   template <typename K>
+                   bool erase( const K& key );
+
                    bool erase( const_accessor& item_accessor );
                    bool erase( accessor& item_accessor );
 
@@ -158,13 +175,19 @@ Class Template Synopsis
                    std::pair<iterator, iterator> equal_range( const key_type& key );
                    std::pair<const_iterator, const_iterator> equal_range( const key_type& key ) const;
 
+                   template <typename K>
+                   std::pair<iterator, iterator> equal_range( const K& key );
+
+                   template <typename K>
+                   std::pair<const_iterator, const_iterator> equal_range( const K& key ) const;
+
                    // Parallel iteration
                    range_type range( std::size_t grainsize = 1 );
                    const_range_type range( std::size_t grainsize = 1 ) const;
              }; // class concurrent_hash_map
 
           } // namespace tbb
-      } // namespace oneapi      
+      } // namespace oneapi
 
 Requirements:
 

source/elements/oneTBB/source/containers/concurrent_hash_map_cls/iterators.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -48,7 +48,21 @@ equal_range
 
         std::pair<const_iterator, const_iterator> equal_range( const key_type& key ) const;
 
-    If an element with the key that is equivalent to ``key`` exists in the container,
-    a pair of iterators ``{f, l}``, where ``f`` is an iterator to this element,
-    ``l`` is ``std::next(f)``.
-    Otherwise, ``{end(), end()}``.
+    **Returns**: a range containing an element that is equivalent to ``key``.
+    If there is no such element in the container, returns ``{end(), end()}`` .
+
+--------------------------
+
+    .. code:: cpp
+
+        template <typename K>
+        std::pair<iterator, iterator> equal_range( const K& key );
+
+        template <typename K>
+        std::pair<const_iterator, const_iterator> equal_range( const K& key ) const;
+
+    **Returns**: a range containing an element which compares equivalent to the value ``key``.
+    If there is no such element in the container, returns ``{end(), end()}``.
+
+    This overload only participates in the overload resolution if qualified-id
+    ``hash_compare_type::is_transparent`` is valid and denotes a type.

source/elements/oneTBB/source/containers/concurrent_hash_map_cls/lookup.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -18,12 +18,32 @@ find
 
         bool find( accessor& result, const key_type& key );
 
-    If the accessor ``result`` is not empty, releases the ``result``.
+    If the ``result`` accessor is not empty, releases the ``result``.
 
     If an element with the key that is equivalent to ``key`` exists, sets the ``result`` to provide access
     to this element.
 
-    **Returns**: ``true`` if an element with the key equivalent to  ``key`` is found; ``false``, otherwise.
+    **Returns**: ``true`` if an element with the key equivalent to  ``key`` is found; ``false`` otherwise.
+
+--------------------------
+
+    .. code:: cpp
+
+        template <typename K>
+        bool find( const_accessor& result, const K& key ) const;
+
+        template <typename K>
+        bool find( accessor& result, const K& key );
+
+    If the ``result`` accessor is not empty, releases the ``result``.
+
+    If an element with the key that compares equivalent to the value ``key`` exists, sets the ``result`` to provide access
+    to this element.
+
+    **Returns**: ``true`` if an element with the key that compares equivalent to the value ``key`` is found; ``false`` otherwise.
+
+    This overload only participates in the overload resolution if qualified-id
+    ``hash_compare_type::is_transparent`` is valid and denotes a type.
 
 count
 -----
@@ -32,4 +52,17 @@ count
 
         size_type count( const key_type& key ) const;
 
-    **Returns**: ``1`` if an element with the equivalent to ``key`` exists; ``0``, otherwise.
+    **Returns**: ``1`` if an element with the key equivalent to ``key`` exists; ``0`` otherwise.
+
+--------------------------
+
+    .. code:: cpp
+
+        template <typename K>
+        size_type count( const K& key ) const;
+
+    **Returns**: ``1`` if an element with the key that compares equivalent to the value ``key`` exists;
+    ``0`` otherwise.
+
+    This overload only participates in the overload resolution if qualified-id
+    ``hash_compare_type::is_transparent`` is valid and denotes a type.

source/elements/oneTBB/source/containers/concurrent_hash_map_cls/modifiers.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -18,18 +18,44 @@ Inserting values
 
         bool insert( accessor& result, const key_type& key );
 
-    If the accessor ``result`` is not empty, releases the ``result`` and
+    If the ``result`` accessor is not empty, releases the ``result`` and
     attempts to insert the value constructed from ``key, mapped_type()`` into the container.
 
-    Sets the ``result`` to provide access to the inserted element or to the element with equal key
-    that was already presented in the container.
+    Sets the ``result`` to provide access to the inserted element or to the element with equal key,
+    which was already presented in the container.
 
     **Requirements**:
 
-    * the type ``value_type`` must meet the ``EmplaceConstructible`` requirements the from [container.requirements] ISO C++ Standard section.
-    * the type ``mapped_type`` must meet the ``DefaultConstructible`` requirements from the [defaultconstructible] ISO C++ Standard section.
+    * the ``value_type`` type must meet the ``EmplaceConstructible`` requirements described in the [container.requirements] section of the ISO C++ Standard.
+    * the ``mapped_type`` type must meet the ``DefaultConstructible`` requirements described in the [defaultconstructible] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise.
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
+
+--------------------------
+
+    .. code:: cpp
+
+        template <typename K>
+        bool insert( const_accessor& result, const K& key );
+
+        template <typename K>
+        bool insert( accessor& result, const K& key );
+
+    If the ``result`` accessor is not empty, releases the ``result`` and
+    attempts to insert the value constructed from ``key, mapped_type()`` into the container.
+
+    Sets the ``result`` to provide access to the inserted element or to the element with the key,
+    that compares equivalent to the value ``key``, which was already presented in the container.
+
+    This overload only participates in the overload resolution if:
+
+    * qualified-id ``hash_compare_type::is_transparent`` is valid and denotes a type
+    * ``std::is_constructible<key_type, const K&>::value`` is ``true``
+
+    **Requirements**: the ``mapped_type`` type must meet the ``DefaultConstructible`` requirements
+    described in the [defaultconstructible] section of the ISO C++ Standard.
+
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
 
 --------------------------
 
@@ -39,16 +65,16 @@ Inserting values
 
         bool insert( accessor& result, const value_type& value );
 
-    If the accessor ``result`` is not empty, releases the ``result`` and
+    If the ``result`` accessor is not empty, releases the ``result`` and
     attempts to insert the value ``value`` into the container.
 
-    Sets the ``result`` to provide access to the inserted element or to the element with equal key
-    that was already presented in the container.
+    Sets the ``result`` to provide access to the inserted element or to the element with equal key,
+    which was already presented in the container.
 
-    **Requirements**: the type ``value_type`` must meet the ``CopyInsertable`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the ``value_type`` type must meet the ``CopyInsertable`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise.
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
 
 --------------------------
 
@@ -58,10 +84,10 @@ Inserting values
 
     Attempts to insert the value ``value`` into the container.
 
-    **Requirements**: the type ``value_type`` must meet the ``CopyInsertable`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the ``value_type`` type must meet the ``CopyInsertable`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise.
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
 
 --------------------------
 
@@ -71,18 +97,18 @@ Inserting values
 
         bool insert( accessor& result, value_type&& value );
 
-    If the accessor ``result`` is not empty, releases the ``result`` and
+    If the ``result`` accessor is not empty, releases the ``result`` and
     attempts to insert the value ``value`` into the container using move semantics.
 
-    Sets the ``result`` to provide access to the inserted element or to the element with equal key
-    that was already presented in the container.
+    Sets the ``result`` to provide access to the inserted element or to the element with equal key,
+    which was already presented in the container.
 
     ``value`` is left in a valid, but unspecified state.
 
-    **Requirements**: the type ``value_type`` must meet the ``MoveInsertable`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the ``value_type`` type must meet the ``MoveInsertable`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise.
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
 
 --------------------------
 
@@ -92,10 +118,10 @@ Inserting values
 
     Attempts to insert the value ``value`` into the container using move semantics.
 
-    **Requirements**: the type ``value_type`` must meet the ``MoveInsertable`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the ``value_type`` type must meet the ``MoveInsertable`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise.
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise.
 
 Inserting sequences of elements
 -------------------------------
@@ -111,8 +137,8 @@ Inserting sequences of elements
     If the interval ``[first, last)`` contains multiple elements with equal keys,
     it is unspecified which element should be inserted.
 
-    **Requirements**: the type ``InputIterator`` must meet the requirements of `InputIterator`
-    from the ``[input.iterators]`` ISO C++ Standard section.
+    **Requirements**: the ``InputIterator`` type must meet the requirements of `InputIterator`
+    described in the ``[input.iterators]`` section of the ISO C++ Standard.
 
 --------------------------
 
@@ -133,16 +159,16 @@ Emplacing elements
         template <typename... Args>
         bool emplace( accessor& result, Args&&... args );
 
-    If the accessor ``result`` is not empty, releases the ``result`` and
+    If the ``result`` accessor is not empty, releases the ``result`` and
     attempts to insert an element constructed in-place from ``args`` into the container.
 
-    Sets the ``result`` to provide access to the inserted element or to the element with equal key
-    that was already presented in the container.
+    Sets the ``result`` to provide access to the inserted element or to the element with equal key,
+    which was already presented in the container.
 
-    **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise
 
 --------------------------
 
@@ -153,10 +179,10 @@ Emplacing elements
 
     Attempts to insert an element constructed in-place from ``args`` into the container.
 
-    **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements from the
-    [container.requirements] ISO C++ Standard section.
+    **Requirements**: the type ``value_type`` must meet the ``EmplaceConstructible`` requirements described in the
+    [container.requirements] section of the ISO C++ Standard.
 
-    **Returns**: ``true`` if an element was inserted; ``false``, otherwise
+    **Returns**: ``true`` if an element is inserted; ``false`` otherwise
 
 Erasing elements
 ----------------
@@ -167,7 +193,21 @@ Erasing elements
 
     If an element with the key equivalent to  ``key`` exists, removes it from the container.
 
-    **Returns**: ``true`` if an element was removed; ``false``, otherwise.
+    **Returns**: ``true`` if an element is removed; ``false`` otherwise.
+
+--------------------------
+
+    .. code:: cpp
+
+        template <typename K>
+        bool erase( const K& key );
+
+    If an element with the key that compares equivalent to the value ``key`` exists, removes it from the container.
+
+    This overload only participates in the overload resolution if qualified-id
+    ``hash_compare_type::is_transparent`` is valid and denotes a type.
+
+    **Returns**: ``true`` if an element is removed; ``false`` otherwise.
 
 --------------------------
 
@@ -180,5 +220,5 @@ Erasing elements
 
     **Requirements**: ``item_accessor`` should not be empty.
 
-    **Returns**: ``true`` if an element was removed by the current thread; ``false``
-    if it was removed by another thread.
+    **Returns**: ``true`` if an element is removed by the current thread; ``false``
+    if it is removed by another thread.