[Python-checkins] CVS: python/dist/src/Doc/ref ref3.tex,1.58,1.59

[Guido van Rossum]

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory usw-pr-cvs1:/tmp/cvs-serv990

Modified Files:
	ref3.tex 
Log Message:
Document rich comparisons.


Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.58
retrieving revision 1.59
diff -C2 -r1.58 -r1.59
*** ref3.tex	2001/01/04 15:11:48	1.58
--- ref3.tex	2001/01/18 15:17:06	1.59
***************
*** 134,140 ****
  This type has a single value.  There is a single object with this value.
  This object is accessed through the built-in name \code{NotImplemented}.
! Binary number methods may return this value if they do not implement the
! operation for the types of operands provided.  The interpreter will then
! try the reverse operation. Its truth value is true.
  \ttindex{NotImplemented}
  \obindex{NotImplemented@{\texttt{NotImplemented}}}
--- 134,141 ----
  This type has a single value.  There is a single object with this value.
  This object is accessed through the built-in name \code{NotImplemented}.
! Numeric methods and rich comparison methods may return this value if
! they do not implement the operation for the operands provided.  (The
! interpreter will then try the reflected operation, or some other
! fallback, depending on the operator.)  Its truth value is true.
  \ttindex{NotImplemented}
  \obindex{NotImplemented@{\texttt{NotImplemented}}}
***************
*** 944,949 ****
  \end{methoddesc}
  
  \begin{methoddesc}[object]{__cmp__}{self, other}
! Called by all comparison operations.  Should return a negative integer if
  \code{self < other},  zero if \code{self == other}, a positive integer if
  \code{self > other}.  If no \method{__cmp__()} operation is defined, class
--- 945,986 ----
  \end{methoddesc}
  
+ \begin{methoddesc}[object]{__lt__}{self, other}
+ \methodline[object]{__le__}{self, other}
+ \methodline[object]{__eq__}{self, other}
+ \methodline[object]{__ne__}{self, other}
+ \methodline[object]{__gt__}{self, other}
+ \methodline[object]{__ge__}{self, other}
+ \versionadded{2.1}
+ These are the so-called ``rich comparison'' methods, and are called
+ for comparison operators in preference to \method{__cmp__()} below.
+ The correspondence between operator symbols and method names is as
+ follows:
+ \code{\var{x}<\var{y}} calls \code{\var{x}.__lt__(\var{y})},
+ \code{\var{x}<=\var{y}} calls \code{\var{x}.__le__(\var{y})},
+ \code{\var{x}==\var{y}} calls \code{\var{x}.__eq__(\var{y})},
+ \code{\var{x}!=\var{y}} and \code{\var{x}<>\var{y}} call
+ \code{\var{x}.__ne__(\var{y})},
+ \code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and
+ \code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}.
+ These methods can return any value, but if the comparison operator is
+ used in a Boolean context, the return value should be interpretable as
+ a Boolean value, else a \exception{TypeError} will be raised.
+ By convention, \code{0} is used for false and \code{1} for true.
+ 
+ There are no reflected (swapped-argument) versions of these methods
+ (to be used when the left argument does not support the operation but
+ the right argument does); rather, \method{__lt__()} and
+ \method{__gt__()} are each other's reflection, \method{__le__()} and
+ \method{__ge__()} are each other's reflection, and \method{__eq__()}
+ and \method{__ne__()} are their own reflection.
+ 
+ Arguments to rich comparison methods are never coerced.  A rich
+ comparison method may return \code{NotImplemented} if it does not
+ implement the operation for a given pair of arguments.
+ \end{methoddesc}
+ 
  \begin{methoddesc}[object]{__cmp__}{self, other}
! Called by comparison operations if rich comparison (see above) is not
! defined.  Should return a negative integer if
  \code{self < other},  zero if \code{self == other}, a positive integer if
  \code{self > other}.  If no \method{__cmp__()} operation is defined, class
***************
*** 1289,1293 ****
  \function{divmod()}\bifuncindex{divmod},
  \function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
! \code{\&}, \code{\^}, \code{|}) with reversed operands.  These
  functions are only called if the left operand does not support the
  corresponding operation.  For instance, to evaluate the expression
--- 1326,1330 ----
  \function{divmod()}\bifuncindex{divmod},
  \function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>},
! \code{\&}, \code{\^}, \code{|}) with reflected (swapped) operands.  These
  functions are only called if the left operand does not support the
  corresponding operation.  For instance, to evaluate the expression