[oneTBB] Changing description for containers deduction guides (#355)

* Add deduction guides rework

* Apply multiple comments from the PR

* Minor rephrase

* Adding default arguments for Allocator for unordered_map

* Update copyright year

Author: kboyarinov

source/elements/oneTBB/source/containers/concurrent_bounded_queue_cls/deduction_guides.rst

@@ -1,20 +1,24 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
 ================
 Deduction guides
 ================
 
-Where possible, constructors of ``tbb::concurrent_bounded_queue`` support class template argument
-deduction (since C++17):
+If possible, ``concurrent_bounded_queue`` constructors support class template argument deduction (since C++17).
+Copy and move constructors, including constructors with an explicit ``allocator_type`` argument,
+provide implicitly-generated deduction guides.
+In addition, the following explicit deduction guide is provided:
 
 .. code:: cpp
 
     template <typename InputIterator,
-              typename Allocator = cache_aligned_allocator<iterator_value_t<InputIterator>>
-    concurrent_bounded_queue( InputIterator, InputIterator, const Allocator& = Allocator() )
-    -> concurrent_bounded_queue<iterator_value_t<InputIterator>, Allocator>;
+              typename Allocator = tbb::cache_aligned_allocator<iterator_value_t<InputIterator>>
+    concurrent_bounded_queue( InputIterator, InputIterator,
+                              Allocator = Allocator() )
+    -> concurrent_bounded_queue<iterator_value_t<InputIterator>,
+                                Allocator>;
 
 Where the type alias ``iterator_value_t`` is defined as follows:
 
@@ -23,6 +27,11 @@ Where the type alias ``iterator_value_t`` is defined as follows:
     template <typename InputIterator>
     using iterator_value_t = typename std::iterator_traits<InputIterator>::value_type;
 
+This deduction guides only participate in the overload resolution if the following requirements are met:
+
+* The ``InputIterator`` type meets the ``InputIterator`` requirements described in the [input.iterators] section of the ISO C++ Standard.
+* The ``Allocator`` type meets the ``Allocator`` requirements described in the [allocator.requirements] section of the ISO C++ Standard.
+
 **Example**
 
 .. code:: cpp

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

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -33,6 +33,7 @@ Class Template Synopsis
                using pointer = typename std::allocator_traits<Allocator>::pointer;
                using const_pointer = typename std::allocator_traits<Allocator>::const_pointer;
 
+               using hash_compare_type = HashCompare;
                using allocator_type = Allocator;
 
                using size_type = <implementation-defined unsigned integer type>;
@@ -50,31 +51,31 @@ Class Template Synopsis
                // Construction, destruction, copying
                concurrent_hash_map();
 
-               explicit concurrent_hash_map( const HashCompare& compare,
+               explicit concurrent_hash_map( const hash_compare_type& compare,
                                              const allocator_type& alloc = allocator_type() );
 
                explicit concurrent_hash_map( const allocator_type& alloc );
 
-               concurrent_hash_map( size_type n, const HashCompare& compare,
+               concurrent_hash_map( size_type n, const hash_compare_type& compare,
                                     const allocator_type& alloc = allocator_type() );
 
                concurrent_hash_map( size_type n, const allocator_type& alloc = allocator_type() );
 
                template <typename InputIterator>
                concurrent_hash_map( InputIterator first, InputIterator last,
-                                    const HashCompare& compare,
+                                    const hash_compare_type& compare,
                                     const allocator_type& alloc = allocator_type() );
 
                template <typename InputIterator>
                concurrent_hash_map( InputIterator first, InputIterator last,
                                     const allocator_type& alloc = allocator_type() );
 
                concurrent_hash_map( std::initializer_list<value_type> init,
-                                    const HashCompare& compare,
+                                    const hash_compare_type& compare = hash_compare_type(),
                                     const allocator_type& alloc = allocator_type() );
 
                concurrent_hash_map( std::initializer_list<value_type> init,
-                                    const allocator_type& alloc = allocator_type() );
+                                    const allocator_type& alloc );
 
                concurrent_hash_map( const concurrent_hash_map& other );
                concurrent_hash_map( const concurrent_hash_map& other,

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

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -13,7 +13,7 @@ Empty container constructors
 
         concurrent_hash_map();
 
-        explicit concurrent_hash_map( const HashCompare& compare,
+        explicit concurrent_hash_map( const hash_compare_type& compare,
                                       const allocator_type& alloc = allocator_type() );
 
         explicit concurrent_hash_map( const allocator_type& alloc );
@@ -28,7 +28,7 @@ Empty container constructors
 
     .. code:: cpp
 
-        concurrent_hash_map( size_type n, const HashCompare& compare,
+        concurrent_hash_map( size_type n, const hash_compare_type& compare,
                              const allocator_type& alloc = allocator_type() );
 
         concurrent_hash_map( size_type n, const allocator_type& alloc = allocator_type() );
@@ -45,7 +45,7 @@ Constructors from the sequence of elements
 
         template <typename InputIterator>
         concurrent_hash_map( InputIterator first, InputIterator last,
-                             const HashCompare& compare,
+                             const hash_compare_type& compare,
                              const allocator_type& alloc = allocator_type() );
 
         template <typename InputIterator>
@@ -70,7 +70,7 @@ Constructors from the sequence of elements
     .. code:: cpp
 
         concurrent_hash_map( std::initializer_list<value_type> init,
-                             const HashCompare& compare,
+                             const hash_compare_type& compare = hash_compare_type(),
                              const allocator_type& alloc = allocator_type() );
 
     Equivalent to ``concurrent_hash_map(init.begin(), init.end(), compare, alloc)``.
@@ -80,7 +80,7 @@ Constructors from the sequence of elements
     .. code:: cpp
 
         concurrent_hash_map( std::initializer_list<value_type> init,
-                             const allocator_type& alloc = allocator_type() );
+                             const allocator_type& alloc );
 
     Equivalent to ``concurrent_hash_map(init.begin(), init.end(), alloc)``.
 

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

@@ -1,56 +1,55 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
 ================
 Deduction guides
 ================
 
-Where possible, constructors of ``concurrent_hash_map`` support
-class template argument deduction (since C++17):
+If possible, ``concurrent_hash_map`` constructors support class template argument deduction (since C++17).
+Copy and move constructors, including constructors with an explicit ``allocator_type`` argument,
+provide implicitly-generated deduction guides.
+In addition, the following explicit deduction guides are provided:
 
 .. code:: cpp
 
     template <typename InputIterator,
-              typename HashCompare,
+              typename HashCompare = tbb_hash_compare<iterator_key_t<InputIterator>>,
               typename Allocator = tbb_allocator<iterator_alloc_value_t<InputIterator>>>
     concurrent_hash_map( InputIterator, InputIterator,
-                         const HashCompare&,
-                         const Allocator& = Allocator() )
+                         HashCompare = HashCompare(),
+                         Allocator = Allocator() )
     -> concurrent_hash_map<iterator_key_t<InputIterator>,
                            iterator_mapped_t<InputIterator>,
                            HashCompare,
                            Allocator>;
 
     template <typename InputIterator,
-              typename Allocator = tbb_allocator<iterator_alloc_value_t<InputIterator>>>
-    concurrent_hash_map( InputIterator, InputIterator,
-                         const Allocator& = Allocator() )
+              typename Allocator>
+    concurrent_hash_map( InputIterator, InputIterator, Allocator )
     -> concurrent_hash_map<iterator_key_t<InputIterator>,
                            iterator_mapped_t<InputIterator>,
                            tbb_hash_compare<iterator_key_t<InputIterator>>,
                            Allocator>;
 
-    template <typename Key,
-              typename T,
-              typename HashCompare,
+    template <typename Key, typename T,
+              typename HashCompare = tbb_hash_compare<std::remove_const_t<Key>>,
               typename Allocator = tbb_allocator<std::pair<const Key, T>>>
-    concurrent_hash_map( std::initializer_list<std::pair<const Key, T>>,
-                         const HashCompare&,
-                         const Allocator& = Allocator() )
-    -> concurrent_hash_map<Key,
+    concurrent_hash_map( std::initializer_list<std::pair<Key, T>>,
+                         HashCompare = HashCompare(),
+                         Allocator = Allocator() )
+    -> concurrent_hash_map<std::remove_const_t<Key>,
                            T,
                            HashCompare,
                            Allocator>;
 
-    template <typename Key,
-              typename T,
-              typename Allocator = tbb_allocator<std::pair<const Key, T>>>
-    concurrent_hash_map( std::initializer_list<std::pair<const Key, T>>,
-                         const Allocator& = Allocator() )
-    -> concurrent_hash_map<Key,
+    template <typename Key, typename T,
+              typename Allocator>
+    concurrent_hash_map( std::initializer_list<std::pair<Key, T>>,
+                         Allocator )
+    -> concurrent_hash_map<std::remove_const_t<Key>,
                            T,
-                           tbb_hash_compare<Key>,
+                           tbb_hash_compare<std::remove_const_t<Key>>,
                            Allocator>;
 
 Where the type aliases ``iterator_key_t``, ``iterator_mapped_t``, and ``iterator_alloc_value_t``
@@ -68,6 +67,12 @@ are defined as follows:
     using iterator_alloc_value_t = std::pair<std::add_const_t<iterator_key_t<InputIterator>,
                                              iterator_mapped_t<InputIterator>>>;
 
+These deduction guides only participate in the overload resolution if the following requirements are met:
+
+* The ``InputIterator`` type meets the ``InputIterator`` requirements described in the [input.iterators] section of the ISO C++ Standard.
+* The ``Allocator`` type meets the ``Allocator`` requirements described in the [allocator.requirements] section of the ISO C++ Standard.
+* The ``HashCompare`` type does not meet the ``Allocator`` requirements.
+
 **Example**
 
 .. code:: cpp

source/elements/oneTBB/source/containers/concurrent_map_cls/deduction_guides.rst

@@ -1,45 +1,56 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
 ================
 Deduction guides
 ================
 
-Where possible, constructors of ``concurrent_map`` support class template argument
-deduction (since C++17):
+If possible, ``concurrent_map`` constructors support class template argument deduction (since C++17).
+Copy and move constructors, including constructors with an explicit ``allocator_type`` argument,
+provide implicitly-generated deduction guides.
+In addition, the following explicit deduction guides are provided:
 
 .. code:: cpp
 
     template <typename InputIterator,
               typename Compare = std::less<iterator_key_t<InputIterator>>,
               typename Allocator = tbb_allocator<iterator_alloc_value_t<InputIterator>>>
-    concurrent_map( InputIterator, InputIterator, Compare = Compare(), Allocator = Allocator() )
+    concurrent_map( InputIterator, InputIterator,
+                    Compare = Compare(),
+                    Allocator = Allocator() )
     -> concurrent_map<iterator_key_t<InputIterator>,
                       iterator_mapped_t<InputIterator>,
                       Compare,
                       Allocator>;
 
     template <typename InputIterator,
               typename Allocator>
-    concurrent_map( InputIterator, InputIterator, Allocator )
+    concurrent_map( InputIterator, InputIterator,
+                    Allocator )
     -> concurrent_map<iterator_key_t<InputIterator>,
                       iterator_mapped_t<InputIterator>,
                       std::less<iterator_key_t<InputIterator>>,
                       Allocator>;
 
-    template <typename Key,
-              typename T,
-              typename Compare = std::less<Key>,
+    template <typename Key, typename T,
+              typename Compare = std::less<std::remove_const_t<Key>>,
               typename Allocator = tbb_allocator<std::pair<const Key, T>>>
-    concurrent_map( std::initializer_list<std::pair<Key, T>>, Compare = Compare(), Allocator = Allocator() )
-    -> concurrent_map<Key, T, Compare, Allocator>;
+    concurrent_map( std::initializer_list<std::pair<Key, T>>,
+                    Compare = Compare(),
+                    Allocator = Allocator() )
+    -> concurrent_map<std::remove_const_t<Key>,
+                      T,
+                      Compare,
+                      Allocator>;
 
-    template <typename Key,
-              typename T,
+    template <typename Key, typename T,
               typename Allocator>
     concurrent_map( std::initializer_list<std::pair<Key, T>>, Allocator )
-    -> concurrent_map<Key, T, std::less<Key>, Allocator>;
+    -> concurrent_map<std::remove_const_t<Key>,
+                      T,
+                      std::less<std::remove_const_t<Key>>,
+                      Allocator>;
 
 where the type aliases ``iterator_key_t``, ``iterator_mapped_t``, ``iterator_alloc_value_t`` are defined as follows:
 
@@ -55,6 +66,12 @@ where the type aliases ``iterator_key_t``, ``iterator_mapped_t``, ``iterator_all
     using iterator_alloc_value_t = std::pair<std::add_const_t<iterator_key_t<InputIterator>>,
                                              iterator_mapped_t<InputIterator>>;
 
+These deduction guides only participate in the overload resolution if the following requirements are met:
+
+* The ``InputIterator`` type meets the ``InputIterator`` requirements described in the [input.iterators] section of the ISO C++ Standard.
+* The ``Allocator`` type meets the ``Allocator`` requirements described in the [allocator.requirements] section of the ISO C++ Standard.
+* The ``Compare`` type does not meet the ``Allocator`` requirements.
+
 **Example**
 
 .. code:: cpp