From 73921b0eecb55fe914b60d028cbfefc5c50a52ff Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Mon, 1 Oct 2001 16:32:13 +0000 Subject: [PATCH] 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. --- Doc/ref/ref3.tex | 52 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 4f1e3882960..32b6de4c30b 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -1122,10 +1122,12 @@ is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for \end{methoddesc} -\subsection{Emulating sequence and mapping types\label{sequence-types}} +\subsection{Emulating container 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 +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 \code{0 <= \var{k} < \var{N}} where \var{N} is the length of the @@ -1177,7 +1179,7 @@ values. \ttindex{__contains__()}} \withsubitem{(numeric object method)}{\ttindex{__coerce__()}} -\begin{methoddesc}[mapping object]{__len__}{self} +\begin{methoddesc}[container object]{__len__}{self} Called to implement the built-in function \function{len()}\bifuncindex{len}. Should return the length of the object, an integer \code{>=} 0. Also, an object that doesn't define a @@ -1186,7 +1188,7 @@ returns zero is considered to be false in a Boolean context. \withsubitem{(object method)}{\ttindex{__nonzero__()}} \end{methoddesc} -\begin{methoddesc}[mapping object]{__getitem__}{self, key} +\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 objects.\obindex{slice} Note that @@ -1201,7 +1203,7 @@ raised; if of a value outside the set of indexes for the sequence proper detection of the end of the sequence. \end{methoddesc} -\begin{methoddesc}[mapping object]{__setitem__}{self, key, value} +\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 for mappings if the objects support changes to the values for keys, or @@ -1210,7 +1212,7 @@ replaced. The same exceptions should be raised for improper \var{key} values as for the \method{__getitem__()} method. \end{methoddesc} -\begin{methoddesc}[mapping object]{__delitem__}{self, key} +\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 for mappings if the objects support removal of keys, or for sequences @@ -1219,6 +1221,32 @@ should be raised for improper \var{key} values as for the \method{__getitem__()} method. \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 \label{sequence-methods}} @@ -1310,16 +1338,6 @@ be be constrained to the bounds of the sequence before being passed to 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} - \subsection{Emulating numeric types\label{numeric-types}}