Document when to use izip_longest().
This commit is contained in:
parent
74b8e76ec1
commit
48c6293500
|
@ -269,22 +269,13 @@ loops that truncate the stream.
|
|||
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)``.
|
||||
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)``.
|
||||
|
||||
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.
|
||||
: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])
|
||||
|
|
Loading…
Reference in New Issue