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

Fred L. Drake fdrake@users.sourceforge.net
Tue, 29 May 2001 09:02:38 -0700


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

Modified Files:
	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.


Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.66
retrieving revision 1.67
diff -C2 -r1.66 -r1.67
*** ref3.tex	2001/05/14 16:04:22	1.66
--- ref3.tex	2001/05/29 16:02:35	1.67
***************
*** 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}