boostorg/unordered
1
0
Fork 1
mirror of https://github.com/boostorg/unordered.git synced 2025-07-30 11:27:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Unordered: updating reference documentation.

Browse Source 
[SVN r74137]
This commit is contained in:
Daniel James
2011-08-29 15:23:32 +00:00
parent f58a3fc3eb
commit 4ec5a0eebd
3 changed files with 206 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/rationale.qbk
View File

@ -92,6 +92,8 @@ So, this implementation uses a prime number for the hash table size.
[h2 Equality operators] [h2 Equality operators]
/TODO/: This is out of date.
`operator==` and `operator!=` are not included in the standard, but I've `operator==` and `operator!=` are not included in the standard, but I've
added them as I think they could be useful and can be implemented added them as I think they could be useful and can be implemented
fairly efficiently. They are specified differently to the other standard fairly efficiently. They are specified differently to the other standard
@ -115,6 +117,8 @@ that their order can be considered part of the container's value.
[h3 C++0x allocators] [h3 C++0x allocators]
/TODO/: This is out of date.
Recent drafts have included an overhaul of the allocators, but this was Recent drafts have included an overhaul of the allocators, but this was
dependent on concepts which are no longer in the standard. dependent on concepts which are no longer in the standard.
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2946.pdf n2946] [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2946.pdf n2946]
@ -124,6 +128,8 @@ a little to accomodate non-C++0x compilers.
[h3 Swapping containers with unequal allocators] [h3 Swapping containers with unequal allocators]
/TODO/: This is out of date.
It isn't clear how to swap containers when their allocators aren't equal. It isn't clear how to swap containers when their allocators aren't equal.
This is This is
[@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#431 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#431

68
doc/ref.php
View File

@ -60,10 +60,6 @@ EOL;
</simpara></purpose> </simpara></purpose>
<description> <description>
<para>Based on chapter 23 of
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">the working draft of the C++ standard [n2960]</ulink>.
But without the updated rules for allocators.
</para>
<para><emphasis role="bold">Template Parameters</emphasis> <para><emphasis role="bold">Template Parameters</emphasis>
<informaltable> <informaltable>
<tgroup cols="2"> <tgroup cols="2">
@ -236,6 +232,9 @@ EOL;
</parameter> </parameter>
<description> <description>
<para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para> <para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para>
<pora>If <code>Allocator::select_on_container_copy_construction</code>
exists and has the right signature, the allocator will be
constructed from its result.</para>
</description> </description>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
@ -249,12 +248,18 @@ EOL;
<para>The move constructor.</para> <para>The move constructor.</para>
</description> </description>
<notes> <notes>
<para>This is emulated on compilers without rvalue references.</para> <para>This is implemented using Boost.Move.</para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation). </para>
<para>
On compilers without rvalue reference support the
emulation does not support moving without calling
<code>boost::move</code> if <code>value_type</code> is
not copyable. So, for example, you can't return the
container from a function.
</para> </para>
</requires> </requires>
</constructor> </constructor>
@ -289,14 +294,12 @@ EOL;
<type><?php echo $name; ?>&amp;</type> <type><?php echo $name; ?>&amp;</type>
<description> <description>
<para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para> <para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para>
<para>If <code>Alloc::propagate_on_container_copy_assignment</code>
exists and <code>Alloc::propagate_on_container_copy_assignment::value
</code> is true, the allocator is overwritten, if not the
copied elements are created using the existing
allocator.</para>
</description> </description>
<notes>
<para>
On compilers without rvalue references, there is a single assignment
operator with the signature <code>operator=(<?php echo $name; ?>)</code>
in order to emulate move semantics.
</para>
</notes>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
</requires> </requires>
@ -308,18 +311,21 @@ EOL;
<type><?php echo $name; ?>&amp;</type> <type><?php echo $name; ?>&amp;</type>
<description> <description>
<para>The move assignment operator.</para> <para>The move assignment operator.</para>
<para>If <code>Alloc::propagate_on_container_move_assignment</code>
exists and <code>Alloc::propagate_on_container_move_assignment::value
</code> is true, the allocator is overwritten, if not the
moved elements are created using the existing
allocator.</para>
</description> </description>
<notes> <notes>
<para> <para>
On compilers without rvalue references, there is a single assignment On compilers without rvalue references, this is emulated using
operator with the signature <code>operator=(<?php echo $name; ?>)</code> Boost.Move.
in order to emulate move semantics.
</para> </para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation).
</para> </para>
</requires> </requires>
</method> </method>
@ -406,6 +412,10 @@ EOL;
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</para>
</notes> </notes>
</method> </method>
<method name="emplace_hint"> <method name="emplace_hint">
@ -444,6 +454,9 @@ EOL;
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</notes> </notes>
</method> </method>
<method name="insert"> <method name="insert">
@ -601,13 +614,10 @@ EOL;
</throws> </throws>
<notes> <notes>
<para> <para>
This method is faster than <methodname>erase</methodname> as This method was implemented because returning an iterator to
it doesn't have to find the next element in the container - the next element from <code>erase</code> was expensive, but
a potentially costly operation. the container has been redesigned so that is no longer the
</para> case. So this method is now deprecated.
<para>
As it hasn't been standardized, it's likely that this may
change in the future.
</para> </para>
</notes> </notes>
</method> </method>
@ -625,10 +635,10 @@ EOL;
</throws> </throws>
<notes> <notes>
<para> <para>
This method is now deprecated, use This method was implemented because returning an iterator to
<methodname>quick_return</methodname> instead. Although be the next element from <code>erase</code> was expensive, but
warned that as that isn't standardized yet, it could also the container has been redesigned so that is no longer the
change. case. So this method is now deprecated.
</para> </para>
</notes> </notes>
</method> </method>
@ -653,6 +663,7 @@ EOL;
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -1006,6 +1017,7 @@ EOL;
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>

272
doc/ref.xml
View File

@ -23,10 +23,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
An unordered associative container that stores unique values. An unordered associative container that stores unique values.
</simpara></purpose> </simpara></purpose>
<description> <description>
<para>Based on chapter 23 of
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">the working draft of the C++ standard [n2960]</ulink>.
But without the updated rules for allocators.
</para>
<para><emphasis role="bold">Template Parameters</emphasis> <para><emphasis role="bold">Template Parameters</emphasis>
<informaltable> <informaltable>
<tgroup cols="2"> <tgroup cols="2">
@ -181,6 +177,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</parameter> </parameter>
<description> <description>
<para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para> <para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para>
<pora>If <code>Allocator::select_on_container_copy_construction</code>
exists and has the right signature, the allocator will be
constructed from its result.</para>
</description> </description>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
@ -194,12 +193,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>The move constructor.</para> <para>The move constructor.</para>
</description> </description>
<notes> <notes>
<para>This is emulated on compilers without rvalue references.</para> <para>This is implemented using Boost.Move.</para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation). </para>
<para>
On compilers without rvalue reference support the
emulation does not support moving without calling
<code>boost::move</code> if <code>value_type</code> is
not copyable. So, for example, you can't return the
container from a function.
</para> </para>
</requires> </requires>
</constructor> </constructor>
@ -234,14 +239,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_set&amp;</type> <type>unordered_set&amp;</type>
<description> <description>
<para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para> <para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para>
<para>If <code>Alloc::propagate_on_container_copy_assignment</code>
exists and <code>Alloc::propagate_on_container_copy_assignment::value
</code> is true, the allocator is overwritten, if not the
copied elements are created using the existing
allocator.</para>
</description> </description>
<notes>
<para>
On compilers without rvalue references, there is a single assignment
operator with the signature <code>operator=(unordered_set)</code>
in order to emulate move semantics.
</para>
</notes>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
</requires> </requires>
@ -253,18 +256,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_set&amp;</type> <type>unordered_set&amp;</type>
<description> <description>
<para>The move assignment operator.</para> <para>The move assignment operator.</para>
<para>If <code>Alloc::propagate_on_container_move_assignment</code>
exists and <code>Alloc::propagate_on_container_move_assignment::value
</code> is true, the allocator is overwritten, if not the
moved elements are created using the existing
allocator.</para>
</description> </description>
<notes> <notes>
<para> <para>
On compilers without rvalue references, there is a single assignment On compilers without rvalue references, this is emulated using
operator with the signature <code>operator=(unordered_set)</code> Boost.Move.
in order to emulate move semantics.
</para> </para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation).
</para> </para>
</requires> </requires>
</method> </method>
@ -344,6 +350,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</para>
</notes> </notes>
</method> </method>
<method name="emplace_hint"> <method name="emplace_hint">
@ -375,6 +385,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</notes> </notes>
</method> </method>
<method name="insert"> <method name="insert">
@ -517,13 +530,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is faster than <methodname>erase</methodname> as This method was implemented because returning an iterator to
it doesn't have to find the next element in the container - the next element from <code>erase</code> was expensive, but
a potentially costly operation. the container has been redesigned so that is no longer the
</para> case. So this method is now deprecated.
<para>
As it hasn't been standardized, it's likely that this may
change in the future.
</para> </para>
</notes> </notes>
</method> </method>
@ -541,10 +551,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is now deprecated, use This method was implemented because returning an iterator to
<methodname>quick_return</methodname> instead. Although be the next element from <code>erase</code> was expensive, but
warned that as that isn't standardized yet, it could also the container has been redesigned so that is no longer the
change. case. So this method is now deprecated.
</para> </para>
</notes> </notes>
</method> </method>
@ -569,6 +579,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -888,6 +899,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -912,10 +924,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
An unordered associative container that stores values. The same key can be stored multiple times. An unordered associative container that stores values. The same key can be stored multiple times.
</simpara></purpose> </simpara></purpose>
<description> <description>
<para>Based on chapter 23 of
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">the working draft of the C++ standard [n2960]</ulink>.
But without the updated rules for allocators.
</para>
<para><emphasis role="bold">Template Parameters</emphasis> <para><emphasis role="bold">Template Parameters</emphasis>
<informaltable> <informaltable>
<tgroup cols="2"> <tgroup cols="2">
@ -1070,6 +1078,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</parameter> </parameter>
<description> <description>
<para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para> <para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para>
<pora>If <code>Allocator::select_on_container_copy_construction</code>
exists and has the right signature, the allocator will be
constructed from its result.</para>
</description> </description>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
@ -1083,12 +1094,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>The move constructor.</para> <para>The move constructor.</para>
</description> </description>
<notes> <notes>
<para>This is emulated on compilers without rvalue references.</para> <para>This is implemented using Boost.Move.</para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation). </para>
<para>
On compilers without rvalue reference support the
emulation does not support moving without calling
<code>boost::move</code> if <code>value_type</code> is
not copyable. So, for example, you can't return the
container from a function.
</para> </para>
</requires> </requires>
</constructor> </constructor>
@ -1123,14 +1140,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_multiset&amp;</type> <type>unordered_multiset&amp;</type>
<description> <description>
<para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para> <para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para>
<para>If <code>Alloc::propagate_on_container_copy_assignment</code>
exists and <code>Alloc::propagate_on_container_copy_assignment::value
</code> is true, the allocator is overwritten, if not the
copied elements are created using the existing
allocator.</para>
</description> </description>
<notes>
<para>
On compilers without rvalue references, there is a single assignment
operator with the signature <code>operator=(unordered_multiset)</code>
in order to emulate move semantics.
</para>
</notes>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
</requires> </requires>
@ -1142,18 +1157,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_multiset&amp;</type> <type>unordered_multiset&amp;</type>
<description> <description>
<para>The move assignment operator.</para> <para>The move assignment operator.</para>
<para>If <code>Alloc::propagate_on_container_move_assignment</code>
exists and <code>Alloc::propagate_on_container_move_assignment::value
</code> is true, the allocator is overwritten, if not the
moved elements are created using the existing
allocator.</para>
</description> </description>
<notes> <notes>
<para> <para>
On compilers without rvalue references, there is a single assignment On compilers without rvalue references, this is emulated using
operator with the signature <code>operator=(unordered_multiset)</code> Boost.Move.
in order to emulate move semantics.
</para> </para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation).
</para> </para>
</requires> </requires>
</method> </method>
@ -1232,6 +1250,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</para>
</notes> </notes>
</method> </method>
<method name="emplace_hint"> <method name="emplace_hint">
@ -1263,6 +1285,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</notes> </notes>
</method> </method>
<method name="insert"> <method name="insert">
@ -1404,13 +1429,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is faster than <methodname>erase</methodname> as This method was implemented because returning an iterator to
it doesn't have to find the next element in the container - the next element from <code>erase</code> was expensive, but
a potentially costly operation. the container has been redesigned so that is no longer the
</para> case. So this method is now deprecated.
<para>
As it hasn't been standardized, it's likely that this may
change in the future.
</para> </para>
</notes> </notes>
</method> </method>
@ -1428,10 +1450,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is now deprecated, use This method was implemented because returning an iterator to
<methodname>quick_return</methodname> instead. Although be the next element from <code>erase</code> was expensive, but
warned that as that isn't standardized yet, it could also the container has been redesigned so that is no longer the
change. case. So this method is now deprecated.
</para> </para>
</notes> </notes>
</method> </method>
@ -1456,6 +1478,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -1775,6 +1798,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -1805,10 +1829,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
An unordered associative container that associates unique keys with another value. An unordered associative container that associates unique keys with another value.
</simpara></purpose> </simpara></purpose>
<description> <description>
<para>Based on chapter 23 of
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">the working draft of the C++ standard [n2960]</ulink>.
But without the updated rules for allocators.
</para>
<para><emphasis role="bold">Template Parameters</emphasis> <para><emphasis role="bold">Template Parameters</emphasis>
<informaltable> <informaltable>
<tgroup cols="2"> <tgroup cols="2">
@ -1969,6 +1989,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</parameter> </parameter>
<description> <description>
<para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para> <para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para>
<pora>If <code>Allocator::select_on_container_copy_construction</code>
exists and has the right signature, the allocator will be
constructed from its result.</para>
</description> </description>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
@ -1982,12 +2005,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>The move constructor.</para> <para>The move constructor.</para>
</description> </description>
<notes> <notes>
<para>This is emulated on compilers without rvalue references.</para> <para>This is implemented using Boost.Move.</para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation). </para>
<para>
On compilers without rvalue reference support the
emulation does not support moving without calling
<code>boost::move</code> if <code>value_type</code> is
not copyable. So, for example, you can't return the
container from a function.
</para> </para>
</requires> </requires>
</constructor> </constructor>
@ -2022,14 +2051,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_map&amp;</type> <type>unordered_map&amp;</type>
<description> <description>
<para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para> <para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para>
<para>If <code>Alloc::propagate_on_container_copy_assignment</code>
exists and <code>Alloc::propagate_on_container_copy_assignment::value
</code> is true, the allocator is overwritten, if not the
copied elements are created using the existing
allocator.</para>
</description> </description>
<notes>
<para>
On compilers without rvalue references, there is a single assignment
operator with the signature <code>operator=(unordered_map)</code>
in order to emulate move semantics.
</para>
</notes>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
</requires> </requires>
@ -2041,18 +2068,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_map&amp;</type> <type>unordered_map&amp;</type>
<description> <description>
<para>The move assignment operator.</para> <para>The move assignment operator.</para>
<para>If <code>Alloc::propagate_on_container_move_assignment</code>
exists and <code>Alloc::propagate_on_container_move_assignment::value
</code> is true, the allocator is overwritten, if not the
moved elements are created using the existing
allocator.</para>
</description> </description>
<notes> <notes>
<para> <para>
On compilers without rvalue references, there is a single assignment On compilers without rvalue references, this is emulated using
operator with the signature <code>operator=(unordered_map)</code> Boost.Move.
in order to emulate move semantics.
</para> </para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation).
</para> </para>
</requires> </requires>
</method> </method>
@ -2132,6 +2162,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</para>
</notes> </notes>
</method> </method>
<method name="emplace_hint"> <method name="emplace_hint">
@ -2163,6 +2197,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</notes> </notes>
</method> </method>
<method name="insert"> <method name="insert">
@ -2305,13 +2342,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is faster than <methodname>erase</methodname> as This method was implemented because returning an iterator to
it doesn't have to find the next element in the container - the next element from <code>erase</code> was expensive, but
a potentially costly operation. the container has been redesigned so that is no longer the
</para> case. So this method is now deprecated.
<para>
As it hasn't been standardized, it's likely that this may
change in the future.
</para> </para>
</notes> </notes>
</method> </method>
@ -2329,10 +2363,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is now deprecated, use This method was implemented because returning an iterator to
<methodname>quick_return</methodname> instead. Although be the next element from <code>erase</code> was expensive, but
warned that as that isn't standardized yet, it could also the container has been redesigned so that is no longer the
change. case. So this method is now deprecated.
</para> </para>
</notes> </notes>
</method> </method>
@ -2357,6 +2391,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -2717,6 +2752,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -2743,10 +2779,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
An unordered associative container that associates keys with another value. The same key can be stored multiple times. An unordered associative container that associates keys with another value. The same key can be stored multiple times.
</simpara></purpose> </simpara></purpose>
<description> <description>
<para>Based on chapter 23 of
<ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">the working draft of the C++ standard [n2960]</ulink>.
But without the updated rules for allocators.
</para>
<para><emphasis role="bold">Template Parameters</emphasis> <para><emphasis role="bold">Template Parameters</emphasis>
<informaltable> <informaltable>
<tgroup cols="2"> <tgroup cols="2">
@ -2907,6 +2939,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</parameter> </parameter>
<description> <description>
<para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para> <para>The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.</para>
<pora>If <code>Allocator::select_on_container_copy_construction</code>
exists and has the right signature, the allocator will be
constructed from its result.</para>
</description> </description>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
@ -2920,12 +2955,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>The move constructor.</para> <para>The move constructor.</para>
</description> </description>
<notes> <notes>
<para>This is emulated on compilers without rvalue references.</para> <para>This is implemented using Boost.Move.</para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation). </para>
<para>
On compilers without rvalue reference support the
emulation does not support moving without calling
<code>boost::move</code> if <code>value_type</code> is
not copyable. So, for example, you can't return the
container from a function.
</para> </para>
</requires> </requires>
</constructor> </constructor>
@ -2960,14 +3001,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_multimap&amp;</type> <type>unordered_multimap&amp;</type>
<description> <description>
<para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para> <para>The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.</para>
<para>If <code>Alloc::propagate_on_container_copy_assignment</code>
exists and <code>Alloc::propagate_on_container_copy_assignment::value
</code> is true, the allocator is overwritten, if not the
copied elements are created using the existing
allocator.</para>
</description> </description>
<notes>
<para>
On compilers without rvalue references, there is a single assignment
operator with the signature <code>operator=(unordered_multimap)</code>
in order to emulate move semantics.
</para>
</notes>
<requires> <requires>
<para><code>value_type</code> is copy constructible</para> <para><code>value_type</code> is copy constructible</para>
</requires> </requires>
@ -2979,18 +3018,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<type>unordered_multimap&amp;</type> <type>unordered_multimap&amp;</type>
<description> <description>
<para>The move assignment operator.</para> <para>The move assignment operator.</para>
<para>If <code>Alloc::propagate_on_container_move_assignment</code>
exists and <code>Alloc::propagate_on_container_move_assignment::value
</code> is true, the allocator is overwritten, if not the
moved elements are created using the existing
allocator.</para>
</description> </description>
<notes> <notes>
<para> <para>
On compilers without rvalue references, there is a single assignment On compilers without rvalue references, this is emulated using
operator with the signature <code>operator=(unordered_multimap)</code> Boost.Move.
in order to emulate move semantics.
</para> </para>
</notes> </notes>
<requires> <requires>
<para> <para>
<code>value_type</code> is move constructible. <code>value_type</code> is move constructible.
(TODO: This is not actually required in this implementation).
</para> </para>
</requires> </requires>
</method> </method>
@ -3069,6 +3111,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</para>
</notes> </notes>
</method> </method>
<method name="emplace_hint"> <method name="emplace_hint">
@ -3100,6 +3146,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the compiler doesn't support variadic template arguments or rvalue <para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support references, this is emulated for up to 10 arguments, with no support
for rvalue references or move semantics.</para> for rvalue references or move semantics.</para>
<para>Since existing `std::pair` implementations don't support
<code>std::piecewise_construct</code> this emulates it,
but using <code>boost::unordered::piecewise_construct</code>.
</notes> </notes>
</method> </method>
<method name="insert"> <method name="insert">
@ -3241,13 +3290,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is faster than <methodname>erase</methodname> as This method was implemented because returning an iterator to
it doesn't have to find the next element in the container - the next element from <code>erase</code> was expensive, but
a potentially costly operation. the container has been redesigned so that is no longer the
</para> case. So this method is now deprecated.
<para>
As it hasn't been standardized, it's likely that this may
change in the future.
</para> </para>
</notes> </notes>
</method> </method>
@ -3265,10 +3311,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</throws> </throws>
<notes> <notes>
<para> <para>
This method is now deprecated, use This method was implemented because returning an iterator to
<methodname>quick_return</methodname> instead. Although be the next element from <code>erase</code> was expensive, but
warned that as that isn't standardized yet, it could also the container has been redesigned so that is no longer the
change. case. So this method is now deprecated.
</para> </para>
</notes> </notes>
</method> </method>
@ -3293,6 +3339,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>key_equal</code> or <code>hasher</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>
@ -3618,6 +3665,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
<para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para> <para>If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of <code>Hash</code> or <code>Pred</code>.</para>
</throws> </throws>
<notes> <notes>
<para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<para>For a discussion of the behavior when allocators aren't equal see <para>For a discussion of the behavior when allocators aren't equal see
<link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para> <link linkend="unordered.rationale.swapping_containers_with_unequal_allocators">the implementation details</link>.</para>
</notes> </notes>