Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libitertools.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents 9e38f817092f
children 61fa6b55c1de
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
1 \section{\module{itertools} ---
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
2 Functions creating iterators for efficient looping}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
3
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
4 \declaremodule{standard}{itertools}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
5 \modulesynopsis{Functions creating iterators for efficient looping.}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
6 \moduleauthor{Raymond Hettinger}{python@rcn.com}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
7 \sectionauthor{Raymond Hettinger}{python@rcn.com}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
8 \versionadded{2.3}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
9
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
10
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
11 This module implements a number of iterator building blocks inspired
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
12 by constructs from the Haskell and SML programming languages. Each
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
13 has been recast in a form suitable for Python.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
14
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
15 The module standardizes a core set of fast, memory efficient tools
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
16 that are useful by themselves or in combination. Standardization helps
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
17 avoid the readability and reliability problems which arise when many
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
18 different individuals create their own slightly varying implementations,
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
19 each with their own quirks and naming conventions.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
20
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
21 The tools are designed to combine readily with one another. This makes
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
22 it easy to construct more specialized tools succinctly and efficiently
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
23 in pure Python.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
24
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
25 For instance, SML provides a tabulation tool: \code{tabulate(f)}
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
26 which produces a sequence \code{f(0), f(1), ...}. This toolbox
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
27 provides \function{imap()} and \function{count()} which can be combined
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
28 to form \code{imap(f, count())} and produce an equivalent result.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
29
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
30 Whether cast in pure python form or C code, tools that use iterators
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
31 are more memory efficient (and faster) than their list based counterparts.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
32 Adopting the principles of just-in-time manufacturing, they create
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
33 data when and where needed instead of consuming memory with the
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
34 computer equivalent of ``inventory''.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
35
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
36 Some tools were omitted from the module because they offered no
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
37 advantage over their pure python counterparts or because their behavior
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
38 was too surprising.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
39
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
40 For instance, SML provides a tool: \code{cycle(\var{seq})} which
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
41 loops over the sequence elements and then starts again when the
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
42 sequence is exhausted. The surprising behavior is the need for
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
43 significant auxiliary storage (which is unusual for an iterator).
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
44 If needed, the tool is readily constructible using pure Python.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
45
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
46 Other tools are being considered for inclusion in future versions of the
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
47 module. For instance, the function
27809
8d6ee15866b2 Fix so it compiles at least.
Michael W. Hudson <mwh@python.net>
parents: 27769
diff changeset
48 \function{chain(\var{it0}, \var{it1}, ...)} would return elements from
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
49 the first iterator until it was exhausted and then move on to each
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
50 successive iterator. The module author welcomes suggestions for other
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
51 basic building blocks.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
52
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
53 \begin{seealso}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
54 \seetext{The Standard ML Basis Library,
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
55 \citetitle[http://www.standardml.org/Basis/]
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
56 {The Standard ML Basis Library}.}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
57
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
58 \seetext{Haskell, A Purely Functional Language,
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
59 \citetitle[http://www.haskell.org/definition/]
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
60 {Definition of Haskell and the Standard Libraries}.}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
61 \end{seealso}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
62
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
63
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
64 \subsection{Itertool functions \label{itertools-functions}}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
65
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
66 The following module functions all construct and return iterators.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
67 Some provide streams of infinite length, so they should only be accessed
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
68 by functions or loops that truncate the stream.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
69
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
70 \begin{funcdesc}{count}{\optional{n}}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
71 Make an iterator that returns consecutive integers starting with \var{n}.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
72 Does not currently support python long integers. Often used as an
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
73 argument to \function{imap()} to generate consecutive data points.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
74 Also, used in \function{izip()} to add sequence numbers. Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
75
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
76 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
77 def count(n=0):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
78 while True:
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
79 yield n
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
80 n += 1
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
81 \end{verbatim}
27747
941de791b17a SF bug #681003: itertools issues
Raymond Hettinger <python@rcn.com>
parents: 27570
diff changeset
82
941de791b17a SF bug #681003: itertools issues
Raymond Hettinger <python@rcn.com>
parents: 27570
diff changeset
83 Note, \function{count()} does not check for overflow and will return
941de791b17a SF bug #681003: itertools issues
Raymond Hettinger <python@rcn.com>
parents: 27570
diff changeset
84 negative numbers after exceeding \code{sys.maxint}. This behavior
941de791b17a SF bug #681003: itertools issues
Raymond Hettinger <python@rcn.com>
parents: 27570
diff changeset
85 may change in the future.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
86 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
87
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
88 \begin{funcdesc}{dropwhile}{predicate, iterable}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
89 Make an iterator that drops elements from the iterable as long as
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
90 the predicate is true; afterwards, returns every element. Note,
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
91 the iterator does not produce \emph{any} output until the predicate
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
92 is true, so it may have a lengthy start-up time. Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
93
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
94 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
95 def dropwhile(predicate, iterable):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
96 iterable = iter(iterable)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
97 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
98 x = iterable.next()
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
99 if predicate(x): continue # drop when predicate is true
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
100 yield x
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
101 break
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
102 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
103 yield iterable.next()
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
104 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
105 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
106
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
107 \begin{funcdesc}{ifilter}{predicate, iterable}
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
108 Make an iterator that filters elements from iterable returning only
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
109 those for which the predicate is \code{True}.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
110 If \var{predicate} is \code{None}, return the items that are true.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
111 Equivalent to:
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
112
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
113 \begin{verbatim}
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
114 def ifilter(predicate, iterable):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
115 if predicate is None:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
116 def predicate(x):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
117 return x
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
118 for x in iterable:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
119 if predicate(x):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
120 yield x
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
121 \end{verbatim}
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
122 \end{funcdesc}
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
123
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
124 \begin{funcdesc}{ifilterfalse}{predicate, iterable}
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
125 Make an iterator that filters elements from iterable returning only
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
126 those for which the predicate is \code{False}.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
127 If \var{predicate} is \code{None}, return the items that are false.
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
128 Equivalent to:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
129
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
130 \begin{verbatim}
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
131 def ifilterfalse(predicate, iterable):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
132 if predicate is None:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
133 def predicate(x):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
134 return x
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
135 for x in iterable:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
136 if not predicate(x):
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
137 yield x
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
138 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
139 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
140
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
141 \begin{funcdesc}{imap}{function, *iterables}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
142 Make an iterator that computes the function using arguments from
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
143 each of the iterables. If \var{function} is set to \code{None}, then
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
144 \function{imap()} returns the arguments as a tuple. Like
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
145 \function{map()} but stops when the shortest iterable is exhausted
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
146 instead of filling in \code{None} for shorter iterables. The reason
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
147 for the difference is that infinite iterator arguments are typically
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
148 an error for \function{map()} (because the output is fully evaluated)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
149 but represent a common and useful way of supplying arguments to
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
150 \function{imap()}.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
151 Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
152
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
153 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
154 def imap(function, *iterables):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
155 iterables = map(iter, iterables)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
156 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
157 args = [i.next() for i in iterables]
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
158 if function is None:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
159 yield tuple(args)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
160 else:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
161 yield function(*args)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
162 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
163 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
164
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
165 \begin{funcdesc}{islice}{iterable, \optional{start,} stop \optional{, step}}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
166 Make an iterator that returns selected elements from the iterable.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
167 If \var{start} is non-zero, then elements from the iterable are skipped
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
168 until start is reached. Afterward, elements are returned consecutively
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
169 unless \var{step} is set higher than one which results in items being
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
170 skipped. If \var{stop} is specified, then iteration stops at the
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
171 specified element position; otherwise, it continues indefinitely or
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
172 until the iterable is exhausted. Unlike regular slicing,
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
173 \function{islice()} does not support negative values for \var{start},
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
174 \var{stop}, or \var{step}. Can be used to extract related fields
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
175 from data where the internal structure has been flattened (for
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
176 example, a multi-line report may list a name field on every
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
177 third line). Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
178
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
179 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
180 def islice(iterable, *args):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
181 s = slice(*args)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
182 next = s.start or 0
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
183 stop = s.stop
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
184 step = s.step or 1
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
185 for cnt, element in enumerate(iterable):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
186 if cnt < next:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
187 continue
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
188 if cnt >= stop:
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
189 break
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
190 yield element
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
191 next += step
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
192 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
193 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
194
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
195 \begin{funcdesc}{izip}{*iterables}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
196 Make an iterator that aggregates elements from each of the iterables.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
197 Like \function{zip()} except that it returns an iterator instead of
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
198 a list. Used for lock-step iteration over several iterables at a
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
199 time. Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
200
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
201 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
202 def izip(*iterables):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
203 iterables = map(iter, iterables)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
204 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
205 result = [i.next() for i in iterables]
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
206 yield tuple(result)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
207 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
208 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
209
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
210 \begin{funcdesc}{repeat}{object}
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
211 Make an iterator that returns \var{object} over and over again.
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
212 Used as argument to \function{imap()} for invariant parameters
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
213 to the called function. Also used with \function{izip()} to create
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
214 an invariant part of a tuple record. Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
215
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
216 \begin{verbatim}
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
217 def repeat(object):
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
218 while True:
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
219 yield object
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
220 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
221 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
222
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
223 \begin{funcdesc}{starmap}{function, iterable}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
224 Make an iterator that computes the function using arguments tuples
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
225 obtained from the iterable. Used instead of \function{imap()} when
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
226 argument parameters are already grouped in tuples from a single iterable
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
227 (the data has been ``pre-zipped''). The difference between
27997
9e38f817092f Markup and nits.
Raymond Hettinger <python@rcn.com>
parents: 27809
diff changeset
228 \function{imap()} and \function{starmap()} parallels the distinction
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
229 between \code{function(a,b)} and \code{function(*c)}.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
230 Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
231
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
232 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
233 def starmap(function, iterable):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
234 iterable = iter(iterable)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
235 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
236 yield function(*iterable.next())
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
237 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
238 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
239
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
240 \begin{funcdesc}{takewhile}{predicate, iterable}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
241 Make an iterator that returns elements from the iterable as long as
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
242 the predicate is true. Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
243
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
244 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
245 def takewhile(predicate, iterable):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
246 iterable = iter(iterable)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
247 while True:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
248 x = iterable.next()
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
249 if predicate(x):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
250 yield x
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
251 else:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
252 break
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
253 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
254 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
255
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
256 \begin{funcdesc}{times}{n, \optional{object}}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
257 Make an iterator that returns \var{object} \var{n} times.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
258 \var{object} defaults to \code{None}. Used for looping a specific
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
259 number of times without creating a number object on each pass.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
260 Equivalent to:
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
261
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
262 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
263 def times(n, object=None):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
264 if n<0 : raise ValueError
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
265 for i in xrange(n):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
266 yield object
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
267 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
268 \end{funcdesc}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
269
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
270
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
271 \subsection{Examples \label{itertools-example}}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
272
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
273 The following examples show common uses for each tool and
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
274 demonstrate ways they can be combined.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
275
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
276 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
277 >>> for i in times(3):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
278 ... print "Hello"
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
279 ...
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
280 Hello
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
281 Hello
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
282 Hello
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
283
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
284 >>> amounts = [120.15, 764.05, 823.14]
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
285 >>> for checknum, amount in izip(count(1200), amounts):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
286 ... print 'Check %d is for $%.2f' % (checknum, amount)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
287 ...
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
288 Check 1200 is for $120.15
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
289 Check 1201 is for $764.05
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
290 Check 1202 is for $823.14
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
291
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
292 >>> import operator
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
293 >>> for cube in imap(operator.pow, xrange(1,4), repeat(3)):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
294 ... print cube
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
295 ...
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
296 1
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
297 8
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
298 27
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
299
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
300 >>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura',
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
301 '', 'martin', '', 'walter', '', 'samuele']
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
302 >>> for name in islice(reportlines, 3, len(reportlines), 2):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
303 ... print name.title()
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
304 ...
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
305 Alex
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
306 Laura
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
307 Martin
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
308 Walter
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
309 Samuele
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
310
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
311 \end{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
312
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
313 This section has further examples of how itertools can be combined.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
314 Note that \function{enumerate()} and \method{iteritems()} already
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
315 have highly efficient implementations in Python. They are only
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
316 included here to illustrate how higher level tools can be created
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
317 from building blocks.
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
318
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
319 \begin{verbatim}
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
320 >>> def enumerate(iterable):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
321 ... return izip(count(), iterable)
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
322
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
323 >>> def tabulate(function):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
324 ... "Return function(0), function(1), ..."
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
325 ... return imap(function, count())
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
326
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
327 >>> def iteritems(mapping):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
328 ... return izip(mapping.iterkeys(), mapping.itervalues())
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
329
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
330 >>> def nth(iterable, n):
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
331 ... "Returns the nth item"
27769
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
332 ... return list(islice(iterable, n, n+1))
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
333
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
334 >>> def all(pred, seq):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
335 ... "Returns True if pred(x) is True for every element in the iterable"
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
336 ... return not nth(ifilterfalse(pred, seq), 0)
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
337
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
338 >>> def some(pred, seq):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
339 ... "Returns True if pred(x) is True at least one element in the iterable"
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
340 ... return bool(nth(ifilter(pred, seq), 0))
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
341
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
342 >>> def no(pred, seq):
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
343 ... "Returns True if pred(x) is False for every element in the iterable"
dc5e1d918055 C Code:
Raymond Hettinger <python@rcn.com>
parents: 27747
diff changeset
344 ... return not nth(ifilter(pred, seq), 0)
27570
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
345
ba57c3daf6e9 Move itertools module from the sandbox and into production.
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
346 \end{verbatim}