[Python-checkins] r60201 - python/trunk/Doc/library/itertools.rst
raymond.hettinger
python-checkins at python.org
Tue Jan 22 20:51:42 CET 2008
Author: raymond.hettinger
Date: Tue Jan 22 20:51:41 2008
New Revision: 60201
Modified:
python/trunk/Doc/library/itertools.rst
Log:
Document when to use izip_longest().
Modified: python/trunk/Doc/library/itertools.rst
==============================================================================
--- python/trunk/Doc/library/itertools.rst (original)
+++ python/trunk/Doc/library/itertools.rst Tue Jan 22 20:51:41 2008
@@ -269,22 +269,13 @@
When no iterables are specified, returns a zero length iterator instead of
raising a :exc:`TypeError` exception.
- 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
- ``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 ``izip(*[chain(s,
- [None]*(n-1))]*n)``.
-
- Note, when :func:`izip` is used with unequal length inputs, subsequent
- iteration over the longer iterables cannot reliably be continued after
- :func:`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 ``it.next()``). In general, :func:`izip`
- should only be used with unequal length inputs when you don't care about
- trailing, unmatched values from the longer iterables.
+ 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 ``izip(*[iter(s)]*n)``.
+
+ :func:`izip` should only be used with unequal length inputs when you don't
+ care about trailing, unmatched values from the longer iterables. If those
+ values are important, use :func:`izip_longest` instead.
.. function:: izip_longest(*iterables[, fillvalue])
More information about the Python-checkins
mailing list