|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r74137 - trunk/libs/unordered/doc
From: dnljms_at_[hidden]
Date: 2011-08-29 11:23:33
Author: danieljames
Date: 2011-08-29 11:23:32 EDT (Mon, 29 Aug 2011)
New Revision: 74137
URL: http://svn.boost.org/trac/boost/changeset/74137
Log:
Unordered: updating reference documentation.
Text files modified:
trunk/libs/unordered/doc/rationale.qbk | 6
trunk/libs/unordered/doc/ref.php | 68 +++++----
trunk/libs/unordered/doc/ref.xml | 272 +++++++++++++++++++++++----------------
3 files changed, 206 insertions(+), 140 deletions(-)
Modified: trunk/libs/unordered/doc/rationale.qbk
==============================================================================
--- trunk/libs/unordered/doc/rationale.qbk (original)
+++ trunk/libs/unordered/doc/rationale.qbk 2011-08-29 11:23:32 EDT (Mon, 29 Aug 2011)
@@ -92,6 +92,8 @@
[h2 Equality operators]
+/TODO/: This is out of date.
+
`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
fairly efficiently. They are specified differently to the other standard
@@ -115,6 +117,8 @@
[h3 C++0x allocators]
+/TODO/: This is out of date.
+
Recent drafts have included an overhaul of the allocators, but this was
dependent on concepts which are no longer in the standard.
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2946.pdf n2946]
@@ -124,6 +128,8 @@
[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.
This is
[@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#431
Modified: trunk/libs/unordered/doc/ref.php
==============================================================================
--- trunk/libs/unordered/doc/ref.php (original)
+++ trunk/libs/unordered/doc/ref.php 2011-08-29 11:23:32 EDT (Mon, 29 Aug 2011)
@@ -60,10 +60,6 @@
</simpara></purpose>
<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>
<informaltable>
<tgroup cols="2">
@@ -236,6 +232,9 @@
</parameter>
<description>
<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>
<requires>
<para><code>value_type</code> is copy constructible</para>
@@ -249,12 +248,18 @@
<para>The move constructor.</para>
</description>
<notes>
- <para>This is emulated on compilers without rvalue references.</para>
+ <para>This is implemented using Boost.Move.</para>
</notes>
<requires>
<para>
<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>
</requires>
</constructor>
@@ -289,14 +294,12 @@
<type><?php echo $name; ?>&</type>
<description>
<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>
- <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>
<para><code>value_type</code> is copy constructible</para>
</requires>
@@ -308,18 +311,21 @@
<type><?php echo $name; ?>&</type>
<description>
<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>
<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.
+ On compilers without rvalue references, this is emulated using
+ Boost.Move.
</para>
</notes>
<requires>
<para>
<code>value_type</code> is move constructible.
- (TODO: This is not actually required in this implementation).
</para>
</requires>
</method>
@@ -406,6 +412,10 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="emplace_hint">
@@ -444,6 +454,9 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="insert">
@@ -601,13 +614,10 @@
</throws>
<notes>
<para>
- This method is faster than <methodname>erase</methodname> as
- it doesn't have to find the next element in the container -
- a potentially costly operation.
- </para>
- <para>
- As it hasn't been standardized, it's likely that this may
- change in the future.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -625,10 +635,10 @@
</throws>
<notes>
<para>
- This method is now deprecated, use
- <methodname>quick_return</methodname> instead. Although be
- warned that as that isn't standardized yet, it could also
- change.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -653,6 +663,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -1006,6 +1017,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
Modified: trunk/libs/unordered/doc/ref.xml
==============================================================================
--- trunk/libs/unordered/doc/ref.xml (original)
+++ trunk/libs/unordered/doc/ref.xml 2011-08-29 11:23:32 EDT (Mon, 29 Aug 2011)
@@ -23,10 +23,6 @@
An unordered associative container that stores unique values.
</simpara></purpose>
<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>
<informaltable>
<tgroup cols="2">
@@ -181,6 +177,9 @@
</parameter>
<description>
<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>
<requires>
<para><code>value_type</code> is copy constructible</para>
@@ -194,12 +193,18 @@
<para>The move constructor.</para>
</description>
<notes>
- <para>This is emulated on compilers without rvalue references.</para>
+ <para>This is implemented using Boost.Move.</para>
</notes>
<requires>
<para>
<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>
</requires>
</constructor>
@@ -234,14 +239,12 @@
<type>unordered_set&</type>
<description>
<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>
- <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>
<para><code>value_type</code> is copy constructible</para>
</requires>
@@ -253,18 +256,21 @@
<type>unordered_set&</type>
<description>
<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>
<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.
+ On compilers without rvalue references, this is emulated using
+ Boost.Move.
</para>
</notes>
<requires>
<para>
<code>value_type</code> is move constructible.
- (TODO: This is not actually required in this implementation).
</para>
</requires>
</method>
@@ -344,6 +350,10 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="emplace_hint">
@@ -375,6 +385,9 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="insert">
@@ -517,13 +530,10 @@
</throws>
<notes>
<para>
- This method is faster than <methodname>erase</methodname> as
- it doesn't have to find the next element in the container -
- a potentially costly operation.
- </para>
- <para>
- As it hasn't been standardized, it's likely that this may
- change in the future.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -541,10 +551,10 @@
</throws>
<notes>
<para>
- This method is now deprecated, use
- <methodname>quick_return</methodname> instead. Although be
- warned that as that isn't standardized yet, it could also
- change.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -569,6 +579,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -888,6 +899,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -912,10 +924,6 @@
An unordered associative container that stores values. The same key can be stored multiple times.
</simpara></purpose>
<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>
<informaltable>
<tgroup cols="2">
@@ -1070,6 +1078,9 @@
</parameter>
<description>
<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>
<requires>
<para><code>value_type</code> is copy constructible</para>
@@ -1083,12 +1094,18 @@
<para>The move constructor.</para>
</description>
<notes>
- <para>This is emulated on compilers without rvalue references.</para>
+ <para>This is implemented using Boost.Move.</para>
</notes>
<requires>
<para>
<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>
</requires>
</constructor>
@@ -1123,14 +1140,12 @@
<type>unordered_multiset&</type>
<description>
<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>
- <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>
<para><code>value_type</code> is copy constructible</para>
</requires>
@@ -1142,18 +1157,21 @@
<type>unordered_multiset&</type>
<description>
<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>
<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.
+ On compilers without rvalue references, this is emulated using
+ Boost.Move.
</para>
</notes>
<requires>
<para>
<code>value_type</code> is move constructible.
- (TODO: This is not actually required in this implementation).
</para>
</requires>
</method>
@@ -1232,6 +1250,10 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="emplace_hint">
@@ -1263,6 +1285,9 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="insert">
@@ -1404,13 +1429,10 @@
</throws>
<notes>
<para>
- This method is faster than <methodname>erase</methodname> as
- it doesn't have to find the next element in the container -
- a potentially costly operation.
- </para>
- <para>
- As it hasn't been standardized, it's likely that this may
- change in the future.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -1428,10 +1450,10 @@
</throws>
<notes>
<para>
- This method is now deprecated, use
- <methodname>quick_return</methodname> instead. Although be
- warned that as that isn't standardized yet, it could also
- change.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -1456,6 +1478,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -1775,6 +1798,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -1805,10 +1829,6 @@
An unordered associative container that associates unique keys with another value.
</simpara></purpose>
<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>
<informaltable>
<tgroup cols="2">
@@ -1969,6 +1989,9 @@
</parameter>
<description>
<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>
<requires>
<para><code>value_type</code> is copy constructible</para>
@@ -1982,12 +2005,18 @@
<para>The move constructor.</para>
</description>
<notes>
- <para>This is emulated on compilers without rvalue references.</para>
+ <para>This is implemented using Boost.Move.</para>
</notes>
<requires>
<para>
<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>
</requires>
</constructor>
@@ -2022,14 +2051,12 @@
<type>unordered_map&</type>
<description>
<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>
- <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>
<para><code>value_type</code> is copy constructible</para>
</requires>
@@ -2041,18 +2068,21 @@
<type>unordered_map&</type>
<description>
<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>
<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.
+ On compilers without rvalue references, this is emulated using
+ Boost.Move.
</para>
</notes>
<requires>
<para>
<code>value_type</code> is move constructible.
- (TODO: This is not actually required in this implementation).
</para>
</requires>
</method>
@@ -2132,6 +2162,10 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="emplace_hint">
@@ -2163,6 +2197,9 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="insert">
@@ -2305,13 +2342,10 @@
</throws>
<notes>
<para>
- This method is faster than <methodname>erase</methodname> as
- it doesn't have to find the next element in the container -
- a potentially costly operation.
- </para>
- <para>
- As it hasn't been standardized, it's likely that this may
- change in the future.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -2329,10 +2363,10 @@
</throws>
<notes>
<para>
- This method is now deprecated, use
- <methodname>quick_return</methodname> instead. Although be
- warned that as that isn't standardized yet, it could also
- change.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -2357,6 +2391,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -2717,6 +2752,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -2743,10 +2779,6 @@
An unordered associative container that associates keys with another value. The same key can be stored multiple times.
</simpara></purpose>
<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>
<informaltable>
<tgroup cols="2">
@@ -2907,6 +2939,9 @@
</parameter>
<description>
<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>
<requires>
<para><code>value_type</code> is copy constructible</para>
@@ -2920,12 +2955,18 @@
<para>The move constructor.</para>
</description>
<notes>
- <para>This is emulated on compilers without rvalue references.</para>
+ <para>This is implemented using Boost.Move.</para>
</notes>
<requires>
<para>
<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>
</requires>
</constructor>
@@ -2960,14 +3001,12 @@
<type>unordered_multimap&</type>
<description>
<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>
- <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>
<para><code>value_type</code> is copy constructible</para>
</requires>
@@ -2979,18 +3018,21 @@
<type>unordered_multimap&</type>
<description>
<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>
<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.
+ On compilers without rvalue references, this is emulated using
+ Boost.Move.
</para>
</notes>
<requires>
<para>
<code>value_type</code> is move constructible.
- (TODO: This is not actually required in this implementation).
</para>
</requires>
</method>
@@ -3069,6 +3111,10 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="emplace_hint">
@@ -3100,6 +3146,9 @@
<para>If the compiler doesn't support variadic template arguments or rvalue
references, this is emulated for up to 10 arguments, with no support
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>
</method>
<method name="insert">
@@ -3241,13 +3290,10 @@
</throws>
<notes>
<para>
- This method is faster than <methodname>erase</methodname> as
- it doesn't have to find the next element in the container -
- a potentially costly operation.
- </para>
- <para>
- As it hasn't been standardized, it's likely that this may
- change in the future.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -3265,10 +3311,10 @@
</throws>
<notes>
<para>
- This method is now deprecated, use
- <methodname>quick_return</methodname> instead. Although be
- warned that as that isn't standardized yet, it could also
- change.
+ This method was implemented because returning an iterator to
+ the next element from <code>erase</code> was expensive, but
+ the container has been redesigned so that is no longer the
+ case. So this method is now deprecated.
</para>
</notes>
</method>
@@ -3293,6 +3339,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
@@ -3618,6 +3665,7 @@
<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>
<notes>
+ <para><emphasis>TODO</emphasis>: Update swap documentation, no longer correct.
<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>
</notes>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk