[Boost-commit] svn:boost r74376 - trunk/libs/unordered/doc

Subject: [Boost-commit] svn:boost r74376 - trunk/libs/unordered/doc
From: dnljms_at_[hidden]
Date: 2011-09-14 17:04:24

Author: danieljames
Date: 2011-09-14 17:04:23 EDT (Wed, 14 Sep 2011)
New Revision: 74376
URL: http://svn.boost.org/trac/boost/changeset/74376

Log:
Unordered: fix swap documentation.
Text files modified: 
   trunk/libs/unordered/doc/rationale.qbk |    11 ---                                     
   trunk/libs/unordered/doc/ref.php       |    28 +++++++--                               
   trunk/libs/unordered/doc/ref.xml       |   112 ++++++++++++++++++++++++++++----------- 
   3 files changed, 100 insertions(+), 51 deletions(-)

Modified: trunk/libs/unordered/doc/rationale.qbk
==============================================================================
--- trunk/libs/unordered/doc/rationale.qbk	(original)
+++ trunk/libs/unordered/doc/rationale.qbk	2011-09-14 17:04:23 EDT (Wed, 14 Sep 2011)
@@ -126,17 +126,6 @@
 an appropriate later version) in a future version of boost, possibly changed
 a little to accomodate non-C++0x compilers.
 
-[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
-Issue 431: Swapping containers with unequal allocators]. This has been resolved
-with the new allocator specification, so this should be fixed when
-support is added.
-
 [h3 Are insert and erase stable for unordered_multiset and unordered_multimap?]
 
 It wan't specified if `unordered_multiset` and `unordered_multimap` preserve the order

Modified: trunk/libs/unordered/doc/ref.php
==============================================================================
--- trunk/libs/unordered/doc/ref.php	(original)
+++ trunk/libs/unordered/doc/ref.php	2011-09-14 17:04:23 EDT (Wed, 14 Sep 2011)
@@ -658,13 +658,19 @@
                 <paramtype><?php echo $name; ?>&amp;</paramtype>
               </parameter>
               <type>void</type>
+              <description>
+                <para>Swaps the contents of the container with the parameter.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </method>
           </method-group>
@@ -1014,13 +1020,19 @@
               <effects>
                 <para><code>x.swap(y)</code></para>
               </effects>
+              <description>
+                <para>Swaps the contents of <code>x</code> and <code>y</code>.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </function>
           </free-function-group>

Modified: trunk/libs/unordered/doc/ref.xml
==============================================================================
--- trunk/libs/unordered/doc/ref.xml	(original)
+++ trunk/libs/unordered/doc/ref.xml	2011-09-14 17:04:23 EDT (Wed, 14 Sep 2011)
@@ -574,13 +574,19 @@
                 <paramtype>unordered_set&amp;</paramtype>
               </parameter>
               <type>void</type>
+              <description>
+                <para>Swaps the contents of the container with the parameter.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </method>
           </method-group>
@@ -896,13 +902,19 @@
               <effects>
                 <para><code>x.swap(y)</code></para>
               </effects>
+              <description>
+                <para>Swaps the contents of <code>x</code> and <code>y</code>.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </function>
           </free-function-group>
@@ -1474,13 +1486,19 @@
                 <paramtype>unordered_multiset&amp;</paramtype>
               </parameter>
               <type>void</type>
+              <description>
+                <para>Swaps the contents of the container with the parameter.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </method>
           </method-group>
@@ -1796,13 +1814,19 @@
               <effects>
                 <para><code>x.swap(y)</code></para>
               </effects>
+              <description>
+                <para>Swaps the contents of <code>x</code> and <code>y</code>.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </function>
           </free-function-group>
@@ -2388,13 +2412,19 @@
                 <paramtype>unordered_map&amp;</paramtype>
               </parameter>
               <type>void</type>
+              <description>
+                <para>Swaps the contents of the container with the parameter.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </method>
           </method-group>
@@ -2751,13 +2781,19 @@
               <effects>
                 <para><code>x.swap(y)</code></para>
               </effects>
+              <description>
+                <para>Swaps the contents of <code>x</code> and <code>y</code>.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </function>
           </free-function-group>
@@ -3337,13 +3373,19 @@
                 <paramtype>unordered_multimap&amp;</paramtype>
               </parameter>
               <type>void</type>
+              <description>
+                <para>Swaps the contents of the container with the parameter.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </method>
           </method-group>
@@ -3665,13 +3707,19 @@
               <effects>
                 <para><code>x.swap(y)</code></para>
               </effects>
+              <description>
+                <para>Swaps the contents of <code>x</code> and <code>y</code>.</para>
+                <para>If <code>Allocator::propagate_on_container_swap</code> is declared and
+                  <code>Allocator::propagate_on_container_swap::value</code> is true then the
+                  containers' allocators are swapped. Otherwise, swapping with unequal allocators
+                  results in undefined behavior.</para>
+              </description>
               <throws>
-                <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>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>
-                <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>
+                <para>The exception specifications aren't quite the same as the C++11 standard, as
+                  the equality predieate and hash function are swapped using their copy constructors.</para>
               </notes>
             </function>
           </free-function-group>