[DEV] add v1.76.0

libs/multi_index/doc/tutorial/basics.html

@@ -62,6 +62,7 @@ Index types
     </ul>
   </li>
   <li><a href="#projection">Projection of iterators</a></li>
+  <li><a href="#node_handling">Node handling operations</a></li>
   <li><a href="#complexity">Complexity and exception safety</a></li>
 </ul>
 
@@ -505,11 +506,9 @@ Currently, Boost.MultiIndex provides the following index types:
     <code>std::list</code>: they arrange the elements as if in a bidirectional
     list.</li>
   <li>Hashed indices provide fast access to the elements through hashing
-    techniques, in a similar way as non-standard <code>hash_set</code>s provided
-    by some vendors. Recently, <i>unordered associative containers</i> have been
-    proposed as part of an extension of the C++ standard library known
-    in the standardization commitee as TR1. Hashed indices closely model this
-    proposal.</li>
+    techniques, in a similar way as unordered associative containers
+    <code>std::unordered_set</code> (if duplicates are not allowed) and
+    <code>std::unordered_multiset</code> (if they are).</li>
   <li>Random access indices provide an interface similar to that of
     sequenced indices, and additionally feature random access iterators
     and positional access to the elements.</li>
@@ -1218,6 +1217,72 @@ When provided, <code>project</code> can also be used with
 <a href="#tagging">tags</a>.
 </p>
 
+<h2><a name="node_handling">Node handling operations</a></h2>
+
+<p>
+Using direct node manipulation, elements can be passed between
+<code>multi_index_container</code>s without actually copying them:
+</p>
+
+<blockquote><pre>
+<span class=comment>// move an employee to the retiree archive</span>
+<span class=keyword>void</span> <span class=identifier>move_to_retirement</span><span class=special>(</span><span class=keyword>int</span> <span class=identifier>ssnumber</span><span class=special>,</span><span class=identifier>employee_set</span><span class=special>&amp;</span> <span class=identifier>es</span><span class=special>,</span><span class=identifier>employee_set</span><span class=special>&amp;</span> <span class=identifier>archive</span><span class=special>)</span>
+<span class=special>{</span>
+  <span class=comment>// extract the employee with given SS number to a node handle</span>
+  <span class=identifier>employee_set_by_ssn</span><span class=special>::</span><span class=identifier>node_type</span> <span class=identifier>node</span><span class=special>=</span><span class=identifier>es</span><span class=special>.</span><span class=identifier>get</span><span class=special>&lt;</span><span class=identifier>ssn</span><span class=special>&gt;().</span><span class=identifier>extract</span><span class=special>(</span><span class=identifier>ssnumber</span><span class=special>);</span>
+
+  <span class=keyword>if</span><span class=special>(!</span><span class=identifier>node</span><span class=special>.</span><span class=identifier>empty</span><span class=special>()){</span> <span class=comment>// employee found
+    // re-insert into archive (note the use of std::move)</span>
+    <span class=identifier>archive</span><span class=special>.</span><span class=identifier>insert</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>move</span><span class=special>(</span><span class=identifier>node</span><span class=special>));</span>
+  <span class=special>}</span>
+<span class=special>}</span>
+</pre></blockquote>
+
+<p>
+In the example, the internal node is transferred as-is from <code>es</code> to <code>archive</code>,
+which is more efficient than erasing from the source and recreating in destination.
+<code>node_type</code> is a move-only class used to pass nodes around, and its interface follows
+that of the <a href="https://en.cppreference.com/w/cpp/container/node_handle">homonym type</a>
+for C++ associative containers (set containers version). Boost.MultiIndex provides node extraction
+and insertion operations for all index types, including sequenced ones (by contrast,
+<code>std::list</code> does not have such features):
+</p>
+
+<blockquote><pre>
+<span class=identifier>multi_index_container</span><span class=special>&lt;</span>
+  <span class=keyword>int</span><span class=special>,</span>
+  <span class=identifier>indexed_by</span><span class=special>&lt;</span>
+    <span class=identifier>sequenced</span><span class=special>&lt;&gt;,</span>
+    <span class=identifier>ordered_unique</span><span class=special>&lt;</span><span class=identifier>identity</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;</span> <span class=special>&gt;</span>
+  <span class=special>&gt;</span>
+<span class=special>&gt;</span> <span class=identifier>src</span><span class=special>;</span>
+
+<span class=identifier>multi_index_container</span><span class=special>&lt;</span>
+  <span class=keyword>int</span><span class=special>,</span>
+  <span class=identifier>indexed_by</span><span class=special>&lt;</span>
+    <span class=identifier>sequenced</span><span class=special>&lt;&gt;,</span>
+    <span class=identifier>ordered_non_unique</span><span class=special>&lt;</span><span class=identifier>identity</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;,</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>greater</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;</span> <span class=special>&gt;</span>
+  <span class=special>&gt;</span>
+<span class=special>&gt;</span> <span class=identifier>dst</span><span class=special>;</span>
+
+<span class=special>...</span>
+
+<span class=comment>// transfer even numbers from src to dst</span>
+<span class=keyword>for</span><span class=special>(</span><span class=keyword>auto</span> <span class=identifier>first</span><span class=special>=</span><span class=identifier>src</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span><span class=identifier>last</span><span class=special>=</span><span class=identifier>src</span><span class=special>.</span><span class=identifier>end</span><span class=special>();</span><span class=identifier>first</span><span class=special>!=</span><span class=identifier>last</span><span class=special>;){</span>
+  <span class=keyword>if</span><span class=special>(*</span><span class=identifier>first</span><span class=special>%</span><span class=number>2</span><span class=special>==</span><span class=number>0</span><span class=special>)</span> <span class=identifier>dst</span><span class=special>.</span><span class=identifier>insert</span><span class=special>(</span><span class=identifier>dst</span><span class=special>.</span><span class=identifier>end</span><span class=special>(),</span><span class=identifier>src</span><span class=special>.</span><span class=identifier>extract</span><span class=special>(</span><span class=identifier>first</span><span class=special>++));</span>
+  <span class=keyword>else</span>            <span class=special>++</span><span class=identifier>first</span><span class=special>;</span>
+<span class=special>}</span>
+</pre></blockquote>
+
+<p>
+Note that <code>src</code> and <code>dst</code> are of different types,
+yet transfer is possible. Two <code>multi_index_container</code>s are
+node-compatible (that is, they use the same <code>node_type</code>) if
+they have the same element and allocator types and their respective indices match
+one by one without regard to whether they are unique or non-unique or to
+their particular configuration parameters: they are both ordered, or
+both sequenced, etc.
+</p>
 <h2><a name="complexity">Complexity and exception safety</a></h2>
 
 <p>
@@ -1252,9 +1317,9 @@ Index types
 
 <br>
 
-<p>Revised November 24th 2015</p>
+<p>Revised May 9th 2020</p>
 
-<p>&copy; Copyright 2003-2015 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
+<p>&copy; Copyright 2003-2020 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
 Distributed under the Boost Software 
 License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">