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

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

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

Log:
Unordered: Update equality documentation.
Text files modified: 
   trunk/libs/unordered/doc/changes.qbk   |     3                                         
   trunk/libs/unordered/doc/rationale.qbk |    23 --------                                
   trunk/libs/unordered/doc/ref.php       |    46 +++++++++++++++-                        
   trunk/libs/unordered/doc/ref.xml       |   112 ++++++++++++++++++++++++++++++++++----- 
   4 files changed, 140 insertions(+), 44 deletions(-)

Modified: trunk/libs/unordered/doc/changes.qbk
==============================================================================
--- trunk/libs/unordered/doc/changes.qbk	(original)
+++ trunk/libs/unordered/doc/changes.qbk	2011-09-14 17:05:13 EDT (Wed, 14 Sep 2011)
@@ -143,7 +143,8 @@
 * Equality comparison has been changed to the C++11 specification.
   In a container with equivalent keys, elements in a group with equal
   keys used to have to be in the same order to be considered equal,
-  now they can be a permutation of each other.
+  now they can be a permutation of each other. To keep the old
+  behavior define the macro `BOOST_UNORDERED_DEPRECATED_EQUALITY`.
 
 * The behaviour of swap is different when the two containers to be
   swapped has unequal allocators. It used to allocate new nodes using

Modified: trunk/libs/unordered/doc/rationale.qbk
==============================================================================
--- trunk/libs/unordered/doc/rationale.qbk	(original)
+++ trunk/libs/unordered/doc/rationale.qbk	2011-09-14 17:05:13 EDT (Wed, 14 Sep 2011)
@@ -90,29 +90,6 @@
 
 So, this implementation uses a prime number for the hash table size.
 
-[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
-containers, comparing keys using the equality predicate rather than
-`operator==`.
-
-It's also different to the proposal
-[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2944.pdf n2944].
-which uses the equality operators for the whole of `value_type`. This
-implementation just uses the key equality function for the key,
-and `mapped_type`'s equality operator in `unordered_map` and
-`unordered_multimap` for the mapped part of the element.
-
-Also, in `unordered_multimap`, the mapped values for a group of elements with
-equivalent keys are only considered equal if they are in the same order,
-in n2944 they just need to be a permutation of each other. Since the
-order of elements with equal keys is now defined to be stable, it seems to me
-that their order can be considered part of the container's value.
-
 [h2 Active Issues and Proposals]
 
 [h3 C++0x allocators]

Modified: trunk/libs/unordered/doc/ref.php
==============================================================================
--- trunk/libs/unordered/doc/ref.php	(original)
+++ trunk/libs/unordered/doc/ref.php	2011-09-14 17:05:13 EDT (Wed, 14 Sep 2011)
@@ -967,9 +967,28 @@
                 <paramtype><?php echo $full_type; ?> const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+<?php if($equivalent_keys): ?>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+<?php else: ?>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+<?php endif; ?>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -991,9 +1010,28 @@
                 <paramtype><?php echo $full_type; ?> const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+<?php if($equivalent_keys): ?>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+<?php else: ?>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+<?php endif; ?>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>

Modified: trunk/libs/unordered/doc/ref.xml
==============================================================================
--- trunk/libs/unordered/doc/ref.xml	(original)
+++ trunk/libs/unordered/doc/ref.xml	2011-09-14 17:05:13 EDT (Wed, 14 Sep 2011)
@@ -847,9 +847,19 @@
                 <paramtype>unordered_set&lt;Value, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -872,9 +882,19 @@
                 <paramtype>unordered_set&lt;Value, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -1759,9 +1779,19 @@
                 <paramtype>unordered_multiset&lt;Value, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -1784,9 +1814,19 @@
                 <paramtype>unordered_multiset&lt;Value, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -2722,9 +2762,19 @@
                 <paramtype>unordered_map&lt;Key, Mapped, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -2749,9 +2799,19 @@
                 <paramtype>unordered_map&lt;Key, Mapped, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every element in <code>x</code>,
+                there is an element in <code>y</code> with the same
+                for the same key, with an equal value (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -3648,9 +3708,19 @@
                 <paramtype>unordered_multimap&lt;Key, Mapped, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>true</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>
@@ -3675,9 +3745,19 @@
                 <paramtype>unordered_multimap&lt;Key, Mapped, Hash, Pred, Alloc&gt; const&amp;</paramtype>
               </parameter>
               <type>bool</type>
+              <description>
+                <para>Return <code>false</code> if <code>x.size() ==
+                y.size</code> and for every equivalent key group in
+                <code>x</code>, there is a group in <code>y</code>
+                for the same key, which is a permutation (using
+                <code>operator==</code> to compare the value types).
+                </para>
+              </description>
               <notes>
-                <para><emphasis>TODO</emphasis>: Documentation outdated.</para>
-                <para>This is a boost extension.</para>
+                <para>The behavior of this function was changed to match
+                  the C++11 standard in Boost 1.48. If you wish to use
+                  the old behaviour, define the macro
+                  <code>BOOST_UNORDERED_DEPRECATED_EQUALITY</code>.</para>
                 <para>Behavior is undefined if the two containers don't have
                     equivalent equality predicates.</para>
               </notes>