Merge branch 'feature/doc-clarification'

Clarify the extract and merge don't work between different compatible containers.
Merge branch 'develop'
2026-08-10 07:31:17 +02:00 · 2017-04-11 23:50:21 +01:00 · 2017-04-11 23:40:13 +01:00 · 2017-04-04 22:22:33 +01:00 · 2017-04-04 22:06:15 +01:00 · 2017-03-15 11:16:53 +00:00
5 changed files with 149 additions and 7 deletions
@@ -301,6 +301,15 @@ C++11 support has resulted in some breaking changes:
  They are removed in C++17.
 * Support 10 constructor arguments in emplace. It was meant to support up to 10
  arguments, but an off by one error in the preprocessor code meant it only
-  supports up to 10.
+  supported up to 9.
+
+[h2 Boost 1.64.0]
+* Initial support for new C++17 member functions:
+  `insert_or_assign` and `try_emplace` in `unordered_map`,
+* Initial support for `merge` and `extract`.
+  Does not include transfering nodes between
+  `unordered_map` and `unordered_multimap` or between `unordered_set` and
+  `unordered_multiset` yet. That will hopefully be in the next version of
+  Boost.

 [endsect]
@@ -925,6 +925,12 @@ EOL;
              <returns>
                <para>A <code>node_type</code> owning the element.</para>
              </returns>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code><?php echo $node_partner; ?></code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="extract">
              <parameter name="k">
@@ -940,6 +946,12 @@ EOL;
              <throws>
                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
              </throws>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code><?php echo $node_partner; ?></code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="insert">
              <parameter name="nh">
@@ -984,6 +996,8 @@ EOL;
              <notes>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code><?php echo $node_partner; ?></code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="insert">
@@ -1028,6 +1042,8 @@ EOL;
                <para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same <?php echo $key_name; ?>. </para>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code><?php echo $node_partner; ?></code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="erase">
@@ -1175,6 +1191,9 @@ EOL;
                <paramtype><?php echo $name; ?>&lt;Value, H2, P2, Alloc&gt;&amp;</paramtype>
 <?php endif; ?>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code><?php echo $node_partner; ?></code> yet.</para>
+              </notes>
            </method>
            <method name="merge">
              <template>
@@ -1190,6 +1209,9 @@ EOL;
                <paramtype><?php echo $name; ?>&lt;Value, H2, P2, Alloc&gt;&amp;&amp;</paramtype>
 <?php endif; ?>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code><?php echo $node_partner; ?></code> yet.</para>
+              </notes>
            </method>
 <?php /*
            <method name="merge">
@@ -1650,13 +1672,20 @@ function echo_node_handle_docs($map)
              <classname>unordered_multi<?php echo $type ?></classname>, that
              can then be inserted into a compatible container type.
            </para>
-            <note>
+            <notes>
              <para>
                The name and template parameters of this type is implementation
                defined, and should be obtained using the <code>node_type</code>
                member typedef from the appropriate container.
              </para>
-            </note>
+              <para>
+                In this version of Boost, <code>node_type</code> is different
+                for <?php echo $map ?
+                  '<code>unordered_map</code> and <code>unordered_multimap</code>,' :
+                  '<code>unordered_set</code> and <code>unordered_multiset</code>,';
+                ?> this will be fixed in a future version of Boost.
+              </para>
+            </notes>
          </purpose>
 <?php if ($map): ?>
          <typedef name="key_type">
@@ -812,6 +812,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <returns>
                <para>A <code>node_type</code> owning the element.</para>
              </returns>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_multiset</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="extract">
              <parameter name="k">
@@ -827,6 +833,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <throws>
                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
              </throws>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_multiset</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="insert">
              <parameter name="nh">
@@ -862,6 +874,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <notes>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_multiset</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="insert">
@@ -895,6 +909,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                <para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. </para>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_multiset</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="erase">
@@ -1038,6 +1054,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_set&lt;Value, H2, P2, Alloc&gt;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_multiset</code> yet.</para>
+              </notes>
            </method>
            <method name="merge">
              <template>
@@ -1049,6 +1068,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_set&lt;Value, H2, P2, Alloc&gt;&amp;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_multiset</code> yet.</para>
+              </notes>
            </method>
          </method-group>
          <method-group name="observers">
@@ -2204,6 +2226,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <returns>
                <para>A <code>node_type</code> owning the element.</para>
              </returns>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_set</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="extract">
              <parameter name="k">
@@ -2219,6 +2247,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <throws>
                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
              </throws>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_set</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="insert">
              <parameter name="nh">
@@ -2242,6 +2276,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <notes>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_set</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="insert">
@@ -2271,6 +2307,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                <para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. </para>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_set</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="erase">
@@ -2414,6 +2452,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_multiset&lt;Value, H2, P2, Alloc&gt;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_set</code> yet.</para>
+              </notes>
            </method>
            <method name="merge">
              <template>
@@ -2425,6 +2466,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_multiset&lt;Value, H2, P2, Alloc&gt;&amp;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_set</code> yet.</para>
+              </notes>
            </method>
          </method-group>
          <method-group name="observers">
@@ -2796,13 +2840,17 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <classname>unordered_multiset</classname>, that
              can then be inserted into a compatible container type.
            </para>
-            <note>
+            <notes>
              <para>
                The name and template parameters of this type is implementation
                defined, and should be obtained using the <code>node_type</code>
                member typedef from the appropriate container.
              </para>
-            </note>
+              <para>
+                In this version of Boost, <code>node_type</code> is different
+                for <code>unordered_set</code> and <code>unordered_multiset</code>, this will be fixed in a future version of Boost.
+              </para>
+            </notes>
          </purpose>
          <typedef name="value_type">
            <type>typename Container::value_type></type>
@@ -3687,6 +3735,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <returns>
                <para>A <code>node_type</code> owning the element.</para>
              </returns>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_multimap</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="extract">
              <parameter name="k">
@@ -3702,6 +3756,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <throws>
                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
              </throws>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_multimap</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="insert">
              <parameter name="nh">
@@ -3737,6 +3797,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <notes>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_multimap</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="insert">
@@ -3770,6 +3832,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                <para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. </para>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_multimap</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="erase">
@@ -3913,6 +3977,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_map&lt;Key, Mapped, H2, P2, Alloc&gt;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_multimap</code> yet.</para>
+              </notes>
            </method>
            <method name="merge">
              <template>
@@ -3924,6 +3991,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_map&lt;Key, Mapped, H2, P2, Alloc&gt;&amp;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_multimap</code> yet.</para>
+              </notes>
            </method>
          </method-group>
          <method-group name="observers">
@@ -5126,6 +5196,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <returns>
                <para>A <code>node_type</code> owning the element.</para>
              </returns>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_map</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="extract">
              <parameter name="k">
@@ -5141,6 +5217,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <throws>
                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
              </throws>
+              <notes>
+                <para>
+                  In C++17 a node extracted using this method can be inserted into a compatible <code>unordered_map</code>,
+                  but that is not supported yet.
+                </para>
+              </notes>
            </method>
            <method name="insert">
              <parameter name="nh">
@@ -5164,6 +5246,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <notes>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_map</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="insert">
@@ -5193,6 +5277,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                <para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. </para>
                <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
                <para>Pointers and references to elements are never invalidated.</para>
+                <para>In C++17 this can be used to insert a node extracted from a compatible <code>unordered_map</code>,
+                    but that is not supported yet.</para>
              </notes>
            </method>
            <method name="erase">
@@ -5336,6 +5422,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_multimap&lt;Key, Mapped, H2, P2, Alloc&gt;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_map</code> yet.</para>
+              </notes>
            </method>
            <method name="merge">
              <template>
@@ -5347,6 +5436,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <parameter name="source">
                <paramtype>unordered_multimap&lt;Key, Mapped, H2, P2, Alloc&gt;&amp;&amp;</paramtype>
              </parameter>
+              <notes>
+                <para>Does not support merging with a compatible <code>unordered_map</code> yet.</para>
+              </notes>
            </method>
          </method-group>
          <method-group name="observers">
@@ -5724,13 +5816,17 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
              <classname>unordered_multimap</classname>, that
              can then be inserted into a compatible container type.
            </para>
-            <note>
+            <notes>
              <para>
                The name and template parameters of this type is implementation
                defined, and should be obtained using the <code>node_type</code>
                member typedef from the appropriate container.
              </para>
-            </note>
+              <para>
+                In this version of Boost, <code>node_type</code> is different
+                for <code>unordered_map</code> and <code>unordered_multimap</code>, this will be fixed in a future version of Boost.
+              </para>
+            </notes>
          </purpose>
          <typedef name="key_type">
            <type>typename Container::key_type</type>
@@ -1,6 +1,9 @@

 // Copyright (C) 2003-2004 Jeremy B. Maitin-Shepard.
 // Copyright (C) 2005-2016 Daniel James
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

 #ifndef BOOST_UNORDERED_DETAIL_IMPLEMENTATION_HPP
 #define BOOST_UNORDERED_DETAIL_IMPLEMENTATION_HPP
@@ -1,3 +1,8 @@
+
+// Copyright 2017 Daniel James.
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 #include <boost/unordered_map.hpp>
 #include <boost/unordered_set.hpp>
Author	SHA1	Message	Date
Daniel James	7aa7d8935c	Merge branch 'feature/doc-clarification'	2017-04-11 23:50:21 +01:00
Daniel James	1bc5d87c5d	Clarify the extract and merge don't work between different compatible containers.	2017-04-11 23:40:13 +01:00
Daniel James	6b32d6bf09	Merge branch 'develop'	2017-04-04 22:22:33 +01:00
Daniel James	c18f57f62b	Add missing copyright/license to a couple of files	2017-04-04 22:06:15 +01:00
Daniel James	e657f75a17	Boost 1.64.0 changelog entry	2017-03-15 11:16:53 +00:00
Daniel James	d060d3a0e5	Fix ironic typo	2017-03-15 11:15:27 +00:00