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

Fred L. Drake fdrake@users.sourceforge.net
Mon, 01 Oct 2001 09:32:15 -0700


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

Modified Files:
	ref3.tex 
Log Message:
Refer to the objects which define __len__(), __*item__(), and __iter__()
as container objects rather than as mapping objects (in the index entries).
Change the section heading and intro sentence to be a little more general,
since that's how things have actually evolved.


Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.74
retrieving revision 1.75
diff -C2 -d -r1.74 -r1.75
*** ref3.tex	2001/09/18 17:58:20	1.74
--- ref3.tex	2001/10/01 16:32:13	1.75
***************
*** 1123,1130 ****
  
  
! \subsection{Emulating sequence and mapping types\label{sequence-types}}
  
! The following methods can be defined to emulate sequence or mapping
! objects.  The first set of methods is used either to emulate a
  sequence or to emulate a mapping; the difference is that for a
  sequence, the allowable keys should be the integers \var{k} for which
--- 1123,1132 ----
  
  
! \subsection{Emulating container types\label{sequence-types}}
  
! The following methods can be defined to implement container
! objects.  Containers usually are sequences (such as lists or tuples)
! or mappings (like dictionaries), but can represent other containers as
! well.  The first set of methods is used either to emulate a
  sequence or to emulate a mapping; the difference is that for a
  sequence, the allowable keys should be the integers \var{k} for which
***************
*** 1178,1182 ****
  \withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
  
! \begin{methoddesc}[mapping object]{__len__}{self}
  Called to implement the built-in function
  \function{len()}\bifuncindex{len}.  Should return the length of the
--- 1180,1184 ----
  \withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
  
! \begin{methoddesc}[container object]{__len__}{self}
  Called to implement the built-in function
  \function{len()}\bifuncindex{len}.  Should return the length of the
***************
*** 1187,1191 ****
  \end{methoddesc}
  
! \begin{methoddesc}[mapping object]{__getitem__}{self, key}
  Called to implement evaluation of \code{\var{self}[\var{key}]}.
  For sequence types, the accepted keys should be integers and slice
--- 1189,1193 ----
  \end{methoddesc}
  
! \begin{methoddesc}[container object]{__getitem__}{self, key}
  Called to implement evaluation of \code{\var{self}[\var{key}]}.
  For sequence types, the accepted keys should be integers and slice
***************
*** 1202,1206 ****
  \end{methoddesc}
  
! \begin{methoddesc}[mapping object]{__setitem__}{self, key, value}
  Called to implement assignment to \code{\var{self}[\var{key}]}.  Same
  note as for \method{__getitem__()}.  This should only be implemented
--- 1204,1208 ----
  \end{methoddesc}
  
! \begin{methoddesc}[container object]{__setitem__}{self, key, value}
  Called to implement assignment to \code{\var{self}[\var{key}]}.  Same
  note as for \method{__getitem__()}.  This should only be implemented
***************
*** 1211,1215 ****
  \end{methoddesc}
  
! \begin{methoddesc}[mapping object]{__delitem__}{self, key}
  Called to implement deletion of \code{\var{self}[\var{key}]}.  Same
  note as for \method{__getitem__()}.  This should only be implemented
--- 1213,1217 ----
  \end{methoddesc}
  
! \begin{methoddesc}[container object]{__delitem__}{self, key}
  Called to implement deletion of \code{\var{self}[\var{key}]}.  Same
  note as for \method{__getitem__()}.  This should only be implemented
***************
*** 1220,1223 ****
--- 1222,1251 ----
  \end{methoddesc}
  
+ \begin{methoddesc}[container object]{__iter__}{self}
+ This method is called when an iterator is required for a container.
+ This method should return a new iterator object that can iterate over
+ all the objects in the container.  For mappings, it should iterate
+ over the keys of the container, and should also be made available as
+ the method \method{iterkeys()}.
+ 
+ Iterator objects also need to implement this method; they are required
+ to return themselves.  For more information on iterator objects, see
+ ``\ulink{Iterator Types}{../lib/typeiter.html}'' in the
+ \citetitle[../lib/lib.html]{Python Library Reference}.
+ \end{methoddesc}
+ 
+ The membership test operators (\keyword{in} and \keyword{not in}) are
+ normally implemented as an iteration through a sequence.  However,
+ container objects can supply the following special method with a more
+ efficient implementation, which also does not require the object be a
+ sequence.
+ 
+ \begin{methoddesc}[container object]{__contains__}{self, item}
+ Called to implement membership test operators.  Should return true if
+ \var{item} is in \var{self}, false otherwise.  For mapping objects,
+ this should consider the keys of the mapping rather than the values or
+ the key-item pairs.
+ \end{methoddesc}
+ 
  
  \subsection{Additional methods for emulation of sequence types
***************
*** 1310,1323 ****
  the \method{__*item__()} methods.
  Calling \code{max(0, i)} conveniently returns the proper value.
- 
- The membership test operators (\keyword{in} and \keyword{not in}) are
- normally implemented as an iteration through the sequence.  However,
- sequence objects can supply the following special method with a more
- efficient implementation:
- 
- \begin{methoddesc}[sequence object]{__contains__}{self, item}
- Called to implement membership test operators.  Should return true if
- \var{item} is in \var{self}, false otherwise.
- \end{methoddesc}
  
  
--- 1338,1341 ----