diff -r 6f3b360bacf5 Doc/reference/expressions.rst
--- a/Doc/reference/expressions.rst Fri Jul 04 11:45:47 2014 +0200
+++ b/Doc/reference/expressions.rst Fri Jul 04 12:54:41 2014 +0200
@@ -1015,10 +1015,6 @@
.. _comparisons:
-.. _is:
-.. _is not:
-.. _in:
-.. _not in:
Comparisons
===========
@@ -1054,50 +1050,52 @@
*c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not
pretty).
+.. _comparison-operators:
+
+Comparison operators
+--------------------
+
The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the
-values of two objects. The objects need not have the same type. If both are
-numbers, they are converted to a common type. Otherwise, the ``==`` and ``!=``
-operators *always* consider objects of different types to be unequal, while the
-``<``, ``>``, ``>=`` and ``<=`` operators raise a :exc:`TypeError` when
-comparing objects of different types that do not implement these operators for
-the given pair of types. You can control comparison behavior of objects of
-non-built-in types by defining rich comparison methods like :meth:`__gt__`,
-described in section :ref:`customization`.
+values of two objects. The objects need not have the same type.
-Comparison of objects of the same type depends on the type:
+Comparison of objects of the same built-in type depends on the type:
-* Numbers are compared arithmetically.
+* Numbers of built-in types (:ref:`typesnumeric`) and of standard library types
+ (:mod:`fractions` and :mod:`decimal`) compare mathematically correct. Complex
+ numbers are not considered orderable; using order comparisons
+ (``<``, ``<=``, ``>=``, ``>``) on complex numbers raises :exc:`TypeError`.
-* The values :const:`float('NaN')` and :const:`Decimal('NaN')` are special.
- The are identical to themselves, ``x is x`` but are not equal to themselves,
+ The values :const:`float('NaN')` and :const:`Decimal('NaN')` are special.
+ They are identical to themselves, ``x is x`` but are not equal to themselves,
``x != x``. Additionally, comparing any value to a not-a-number value
will return ``False``. For example, both ``3 < float('NaN')`` and
``float('NaN') < 3`` will return ``False``.
* Bytes objects are compared lexicographically using the numeric values of their
- elements.
+ bytes elements.
* Strings are compared lexicographically using the numeric equivalents (the
result of the built-in function :func:`ord`) of their characters. [#]_ String
- and bytes object can't be compared!
+ objects cannot be compared with bytes objects, and vice versa!
* Tuples and lists are compared lexicographically using comparison of
- corresponding elements. This means that to compare equal, each element must
- compare equal and the two sequences must be of the same type and have the same
- length.
+ corresponding elements. This means that for two sequences to compare equal,
+ they must be of the same type, have the same length, and each pair of
+ corresponding elements must compare equal.
If not equal, the sequences are ordered the same as their first differing
- elements. For example, ``[1,2,x] <= [1,2,y]`` has the same value as
- ``x <= y``. If the corresponding element does not exist, the shorter
- sequence is ordered first (for example, ``[1,2] < [1,2,3]``).
+ elements. For example, ``[1, 2, x] <= [1, 2, y]`` has the same value as
+ ``x <= y``. If a corresponding element does not exist, the shorter
+ sequence is ordered first (for example, ``[1, 2] < [1, 2, 3]``).
-* Mappings (dictionaries) compare equal if and only if they have the same
- ``(key, value)`` pairs. Order comparisons ``('<', '<=', '>=', '>')``
- raise :exc:`TypeError`.
+* Mappings (dictionaries) compare equal if and only if the values at matching
+ keys compare equal. Keys match if they compare equal. Using order
+ comparisons (``<``, ``<=``, ``>=``, ``>``) on mappings raises
+ :exc:`TypeError`.
* Sets and frozensets define comparison operators to mean subset and superset
tests. Those relations do not define total orderings (the two sets ``{1,2}``
- and {2,3} are not equal, nor subsets of one another, nor supersets of one
+ and ``{2,3}`` are not equal, nor subsets of one another, nor supersets of one
another). Accordingly, sets are not appropriate arguments for functions
which depend on total ordering. For example, :func:`min`, :func:`max`, and
:func:`sorted` produce undefined results given a list of sets as inputs.
@@ -1107,12 +1105,31 @@
another one is made arbitrarily but consistently within one execution of a
program.
-Comparison of objects of differing types depends on whether either of the
-types provide explicit support for the comparison. Most numeric types can be
-compared with one another. When cross-type comparison is not supported, the
-comparison method returns ``NotImplemented``.
+Comparison of objects of differing built-in types depends on the type:
+* Numbers of built-in types (:ref:`typesnumeric`) and of standard library types
+ (:mod:`fractions` and :mod:`decimal`) compare between objects of different
+ types as described for objects of same types. Any type conversions that are
+ performed will be mathematically correct (i.e. without loosing precision).
+
+* Any other built-in types do not support comparison between objects of
+ different types: Using ``==`` or ``!=`` yields unequal objects; Using order
+ comparisons (``<``, ``<=``, ``>=``, ``>``) raises :exc:`TypeError`.
+
+Comparison of objects involving user-defined classes depends on whether either
+of the participating types supports the comparison operation. Comparison
+operations can be implemented by defining :dfn:`rich comparison methods` like
+:meth:`__lt__`, described in :ref:`customization`.
+
+.. _is:
+.. _is not:
+.. _in:
+.. _not in:
.. _membership-test-details:
+.. _membership-test-operators:
+
+Membership test operators
+-------------------------
The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in
s`` evaluates to true if *x* is a member of *s*, and false otherwise. ``x not
@@ -1381,12 +1398,24 @@
cases, Python returns the latter result, in order to preserve that
``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
-.. [#] While comparisons between strings make sense at the byte level, they may
- be counter-intuitive to users. For example, the strings ``"\u00C7"`` and
- ``"\u0327\u0043"`` compare differently, even though they both represent the
- same unicode character (LATIN CAPITAL LETTER C WITH CEDILLA). To compare
- strings in a human recognizable way, compare using
- :func:`unicodedata.normalize`.
+.. [#] The Unicode standard distinguishes between :dfn:`code points`
+ (e.g. U+0041) and :dfn:`abstract characters` (e.g. "LATIN CAPITAL LETTER A").
+ While most abstract characters in Unicode are represented using exactly one
+ code point, there is a number of abstract characters that can be represented
+ using more than one code point or sequence of code points. For example, the
+ abstract character "LATIN CAPITAL LETTER C WITH CEDILLA" can be represented
+ as a single :dfn:`precomposed character` at code position U+00C7, or as a
+ sequence of a :dfn:`base character` at code position U+0043 (LATIN CAPITAL
+ LETTER C), followed by a :dfn:`combining character` at code position U+0327
+ (COMBINING CEDILLA).
+
+ The comparison operators on strings compare at the level of Unicode code
+ points. This may be counter-intuitive to humans. For example,
+ ``"\u00C7" == "\u0043\u0327"`` is ``False``, even though both strings
+ represent the same abstract character "LATIN CAPITAL LETTER C WITH CEDILLA".
+
+ To compare strings at the level of abstract characters (that is, in a way
+ intuitive to humans), use :func:`unicodedata.normalize`.
.. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of
descriptors, you may notice seemingly unusual behaviour in certain uses of