diff -r 0c5a1835af91 Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst Thu Jul 03 10:58:06 2014 -0500 +++ b/Doc/reference/expressions.rst Fri Jul 04 13:25:34 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