diff options
Diffstat (limited to 'Doc/library/functions.rst')
| -rw-r--r-- | Doc/library/functions.rst | 24 |
1 files changed, 17 insertions, 7 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 62b37c0..6ab85f6 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1104,20 +1104,30 @@ available. They are listed here in alphabetical order. the effects on the corresponding symbol table are undefined. [#]_ -.. function:: zip([iterable, ...]) +.. function:: zip(*iterables) - This function returns an iterator of tuples, where the *i*-th tuple contains + Make an iterator that aggregates elements from each of the iterables. + + Returns an iterator of tuples, where the *i*-th tuple contains the *i*-th element from each of the argument sequences or iterables. The - iterator stops when the shortest argument sequence is exhausted. When there - are multiple arguments which are all of the same length, :func:`zip` is - similar to :func:`map` with an initial argument of ``None``. With a single - sequence argument, it returns an iterator of 1-tuples. With no arguments, it - returns an empty iterator. + iterator stops when the shortest input iterable is exhausted. With a single + iterable argument, it returns an iterator of 1-tuples. With no arguments, + it returns an empty iterator. Equivalent to:: + + def zip(*iterables): + # zip('ABCD', 'xy') --> Ax By + iterables = map(iter, iterables) + while iterables: + result = [it.next() for it in iterables] + yield tuple(result) 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 ``zip(*[iter(s)]*n)``. + :func:`zip` 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:`itertools.zip_longest` instead. .. rubric:: Footnotes |