summaryrefslogtreecommitdiffstats
path: root/Doc/ref
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2001-10-01 16:32:13 (GMT)
committerFred Drake <fdrake@acm.org>2001-10-01 16:32:13 (GMT)
commit73921b0eecb55fe914b60d028cbfefc5c50a52ff (patch)
treea2c35e89b13b9adbdb5d67393dcb4522984cf679 /Doc/ref
parent25d1807d23fb89213664274c2dada83fd12dee7d (diff)
downloadcpython-73921b0eecb55fe914b60d028cbfefc5c50a52ff.zip
cpython-73921b0eecb55fe914b60d028cbfefc5c50a52ff.tar.gz
cpython-73921b0eecb55fe914b60d028cbfefc5c50a52ff.tar.bz2
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.
Diffstat (limited to 'Doc/ref')
-rw-r--r--Doc/ref/ref3.tex52
1 files changed, 35 insertions, 17 deletions
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 4f1e388..32b6de4 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}}