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

Subject: [Boost-commit] svn:boost r49925 - trunk/libs/unordered/doc
From: daniel_james_at_[hidden]
Date: 2008-11-24 17:55:48

Author: danieljames
Date: 2008-11-24 17:55:47 EST (Mon, 24 Nov 2008)
New Revision: 49925
URL: http://svn.boost.org/trac/boost/changeset/49925

Log:
Document operator==/operator!= as undefined if the equality predicates aren't equivalent. Fixes #2237.
Text files modified: 
   trunk/libs/unordered/doc/changes.qbk       |     4 ++++                                    
   trunk/libs/unordered/doc/hash_equality.qbk |    10 ++++++++++                              
   trunk/libs/unordered/doc/ref.xml           |    16 ++++++++++++++++                        
   3 files changed, 30 insertions(+), 0 deletions(-)

Modified: trunk/libs/unordered/doc/changes.qbk
==============================================================================
--- trunk/libs/unordered/doc/changes.qbk	(original)
+++ trunk/libs/unordered/doc/changes.qbk	2008-11-24 17:55:47 EST (Mon, 24 Nov 2008)
@@ -45,5 +45,9 @@
 [h2 Boost 1.38.0]
 
 * Use [@../../libs/utility/swap.html `boost::swap`].
+* [@https://svn.boost.org/trac/boost/ticket/2237 Ticket 2237]:
+  Document that the equality and inequality operators are undefined for two
+  objects if their equality predicates aren't equivalent. Thanks to Daniel
+  Krügler.
 
 [endsect]

Modified: trunk/libs/unordered/doc/hash_equality.qbk
==============================================================================
--- trunk/libs/unordered/doc/hash_equality.qbk	(original)
+++ trunk/libs/unordered/doc/hash_equality.qbk	2008-11-24 17:55:47 EST (Mon, 24 Nov 2008)
@@ -41,6 +41,16 @@
 [@../../libs/unordered/examples/case_insensitive.hpp /libs/unordered/examples/case_insensitive.hpp]
 which supports other locales and string types.
 
+[caution
+Be careful when using the equality (`==`) operator with custom equality
+predicates, especially if you're using a function pointer. If you compare two
+containers with different equality predicates then the result is undefined.
+For most stateless function objects this is impossible - since you can only
+compare objects with the same equality predicate you know the equality
+predicates must be equal. But if you're using function pointers or a stateful
+equality predicate (e.g. boost::function) then you can get into trouble.
+]
+
 [h2 Custom Types]
 
 Similarly, a custom hash function can be used for custom types:

Modified: trunk/libs/unordered/doc/ref.xml
==============================================================================
--- trunk/libs/unordered/doc/ref.xml	(original)
+++ trunk/libs/unordered/doc/ref.xml	2008-11-24 17:55:47 EST (Mon, 24 Nov 2008)
@@ -678,6 +678,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
             <function name="operator!=">
@@ -700,6 +702,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
           </free-function-group>
@@ -1406,6 +1410,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
             <function name="operator!=">
@@ -1428,6 +1434,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
           </free-function-group>
@@ -2185,6 +2193,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
             <function name="operator!=">
@@ -2209,6 +2219,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
           </free-function-group>
@@ -2927,6 +2939,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
             <function name="operator!=">
@@ -2951,6 +2965,8 @@
               <type>bool</type>
               <notes>
                 <para>This is a boost extension.</para>
+                <para>Behavior is undefined if the two containers don't have
+                    equivalent equality predicates.</para>
               </notes>
             </function>
           </free-function-group>