Raymond Hettinger  committed 30fabb8

Guarantee evaluation order for izip(). Document its creative uses and its limitations.

  • Participants
  • Parent commits 2c1fe76
  • Branches 2.4

Comments (0)

Files changed (1)

File Doc/lib/libitertools.tex

      def izip(*iterables):
          iterables = map(iter, iterables)
          while iterables:
-             result = [ for i in iterables]
+             result = [ for it in iterables]
              yield tuple(result)
   \versionchanged[When no iterables are specified, returns a zero length
-                  iterator instead of raising a TypeError exception]{2.4}  
+                  iterator instead of raising a 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{}.  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.
 \begin{funcdesc}{repeat}{object\optional{, times}}
     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)