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>