[Python-checkins] CVS: python/dist/src/Doc/ref ref3.tex,1.64.2.1,1.64.2.2
Fred L. Drake
fdrake@users.sourceforge.net
Tue, 29 May 2001 09:06:23 -0700
Update of /cvsroot/python/python/dist/src/Doc/ref
In directory usw-pr-cvs1:/tmp/cvs-serv24667/ref
Modified Files:
Tag: release21-maint
ref3.tex
Log Message:
Bring the notes on the relationship between __cmp__(), __eq__(), and
__hash__() up to date (re: use of objects which define these methods
as dictionary keys).
This closes SF bug #427698.
Migrated comments about supporting __contains__() and the use of the "in"
operator from the development branch.
Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.64.2.1
retrieving revision 1.64.2.2
diff -C2 -r1.64.2.1 -r1.64.2.2
*** ref3.tex 2001/05/14 16:04:57 1.64.2.1
--- ref3.tex 2001/05/29 16:06:21 1.64.2.2
***************
*** 1011,1018 ****
\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
! instances are compared by object identity (``address'').
(Note: the restriction that exceptions are not propagated by
\method{__cmp__()} has been removed in Python 1.5.)
--- 1011,1022 ----
\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__()}, \method{__eq__()} or
! \method{__ne__()} operation is defined, class instances are compared
! by object identity (``address''). See also the description of
! \method{__hash__()} for some important notes on creating objects which
! support custom comparison operations and are usable as dictionary
! keys.
(Note: the restriction that exceptions are not propagated by
\method{__cmp__()} has been removed in Python 1.5.)
***************
*** 1036,1045 ****
objects. If a class does not define a \method{__cmp__()} method it should
not define a \method{__hash__()} operation either; if it defines
! \method{__cmp__()} but not \method{__hash__()} its instances will not be
! usable as dictionary keys. If a class defines mutable objects and
! implements a \method{__cmp__()} method it should not implement
! \method{__hash__()}, since the dictionary implementation requires that
! a key's hash value is immutable (if the object's hash value changes, it
! will be in the wrong hash bucket).
\withsubitem{(object method)}{\ttindex{__cmp__()}}
\end{methoddesc}
--- 1040,1050 ----
objects. If a class does not define a \method{__cmp__()} method it should
not define a \method{__hash__()} operation either; if it defines
! \method{__cmp__()} or \method{__eq__()} but not \method{__hash__()},
! its instances will not be usable as dictionary keys. If a class
! defines mutable objects and implements a \method{__cmp__()} or
! \method{__eq__()} method, it should not implement \method{__hash__()},
! since the dictionary implementation requires that a key's hash value
! is immutable (if the object's hash value changes, it will be in the
! wrong hash bucket).
\withsubitem{(object method)}{\ttindex{__cmp__()}}
\end{methoddesc}
***************
*** 1136,1140 ****
\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
below; they should not define \method{__coerce__()} or other numerical
! operators.
\withsubitem{(mapping object method)}{
\ttindex{keys()}
--- 1141,1148 ----
\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
below; they should not define \method{__coerce__()} or other numerical
! operators. It is recommended that both mappings and sequences
! implement the \method{__contains__}, to allow efficient use of the
! \code{in} operator; for mappings, \code{in} should be equivalent of
! \method{has_key()}; for sequences, it should search through the values.
\withsubitem{(mapping object method)}{
\ttindex{keys()}
***************
*** 1145,1149 ****
\ttindex{clear()}
\ttindex{copy()}
! \ttindex{update()}}
\withsubitem{(sequence object method)}{
\ttindex{append()}
--- 1153,1158 ----
\ttindex{clear()}
\ttindex{copy()}
! \ttindex{update()}
! \ttindex{__contains__()}}
\withsubitem{(sequence object method)}{
\ttindex{append()}
***************
*** 1160,1164 ****
\ttindex{__mul__()}
\ttindex{__rmul__()}
! \ttindex{__imul__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
--- 1169,1174 ----
\ttindex{__mul__()}
\ttindex{__rmul__()}
! \ttindex{__imul__()}
! \ttindex{__contains__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}