[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__()}}