diff options
author | Raymond Hettinger <python@rcn.com> | 2006-03-26 01:41:25 (GMT) |
---|---|---|
committer | Raymond Hettinger <python@rcn.com> | 2006-03-26 01:41:25 (GMT) |
commit | a531e5b84c62e90ff0eaed1a61caf5d952409397 (patch) | |
tree | df6234863b7a882b77671703869c2376cc54a16f /Doc/lib | |
parent | 1818ed705bcd295fc903d835745d04f2814a8d95 (diff) | |
download | cpython-a531e5b84c62e90ff0eaed1a61caf5d952409397.zip cpython-a531e5b84c62e90ff0eaed1a61caf5d952409397.tar.gz cpython-a531e5b84c62e90ff0eaed1a61caf5d952409397.tar.bz2 |
Guarantee evaluation order for izip(). Document its creative uses and its limitations.
Diffstat (limited to 'Doc/lib')
-rw-r--r-- | Doc/lib/libitertools.tex | 24 |
1 files changed, 23 insertions, 1 deletions
diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex index 904a19a..20bbc8d 100644 --- a/Doc/lib/libitertools.tex +++ b/Doc/lib/libitertools.tex @@ -276,13 +276,30 @@ by functions or loops that truncate the stream. def izip(*iterables): iterables = map(iter, iterables) while iterables: - result = [i.next() for i in iterables] + result = [it.next() for it in iterables] yield tuple(result) \end{verbatim} \versionchanged[When no iterables are specified, returns a zero length iterator instead of raising a \exception{TypeError} exception]{2.4} + + Note, the left-to-right evaluation order of the iterables is guaranteed. + This makes possible an idiom for clustering a data series into n-length + groups using \samp{izip(*[iter(s)]*n)}. For data that doesn't fit + n-length groups exactly, the last tuple can be pre-padded with fill + values using \samp{izip(*[chain(s, [None]*(n-1))]*n)}. + + Note, when \function{izip()} is used with unequal length inputs, subsequent + iteration over the longer iterables cannot reliably be continued after + \function{izip()} terminates. Potentially, up to one entry will be missing + from each of the left-over iterables. This occurs because a value is fetched + from each iterator in-turn, but the process ends when one of the iterators + terminates. This leaves the last fetched values in limbo (they cannot be + returned in a final, incomplete tuple and they are cannot be pushed back + into the iterator for retrieval with \code{it.next()}). In general, + \function{izip()} should only be used with unequal length inputs when you + don't care about trailing, unmatched values from the longer iterables. \end{funcdesc} \begin{funcdesc}{repeat}{object\optional{, times}} @@ -518,4 +535,9 @@ def pairwise(iterable): pass return izip(a, b) +def grouper(n, iterable, padvalue=None): + "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')" + return izip(*[chain(iterable, repeat(padvalue, n-1))]*n) + + \end{verbatim} |