Document operator==/operator!= as undefined if the equality predicates aren't equivalent. Fixes #2237.

[SVN r49925]

doc/changes.qbk

@@ -45,5 +45,9 @@ First official release.
 [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]

doc/hash_equality.qbk

@@ -41,6 +41,16 @@ This is a simplified version of the example at
 [@../../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:

doc/ref.xml

@@ -678,6 +678,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               <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>