From 48c6293500ef40104c3046713a2df8e951a7251c Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 22 Jan 2008 19:51:41 +0000 Subject: [PATCH] Document when to use izip_longest(). --- Doc/library/itertools.rst | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index e797aab6ac..419e8e581c 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -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)``. - - 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]) -- 2.50.1