Add an example to address a common question of how to split iterators.
diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex
index 7fdd602..453d16e 100644
--- a/Doc/lib/libitertools.tex
+++ b/Doc/lib/libitertools.tex
@@ -321,13 +321,15 @@
\end{verbatim}
-This section has further examples of how itertools can be combined.
-Note that \function{enumerate()} and \method{iteritems()} already
-have highly efficient implementations in Python. They are only
-included here to illustrate how higher level tools can be created
-from building blocks.
+This section shows how itertools can be combined to create other more
+powerful itertools. Note that \function{enumerate()} and \method{iteritems()}
+already have efficient implementations in Python. They are only included here
+to illustrate how higher level tools can be created from building blocks.
\begin{verbatim}
+def take(n, seq):
+ return list(islice(seq, n))
+
def enumerate(iterable):
return izip(count(), iterable)
@@ -380,7 +382,18 @@
result = result[1:] + (elem,)
yield result
-def take(n, seq):
- return list(islice(seq, n))
+def tee(iterable):
+ "Return two independent iterators from a single iterable"
+ def gen(next, data={}, cnt=[0]):
+ dpop = data.pop
+ for i in count():
+ if i == cnt[0]:
+ item = data[i] = next()
+ cnt[0] += 1
+ else:
+ item = dpop(i)
+ yield item
+ next = iter(iterable).next
+ return (gen(next), gen(next))
\end{verbatim}
diff --git a/Lib/test/test_itertools.py b/Lib/test/test_itertools.py
index 057b576..8ab4cea 100644
--- a/Lib/test/test_itertools.py
+++ b/Lib/test/test_itertools.py
@@ -487,6 +487,9 @@
Walter
Samuele
+>>> def take(n, seq):
+... return list(islice(seq, n))
+
>>> def enumerate(iterable):
... return izip(count(), iterable)
@@ -539,12 +542,26 @@
... result = result[1:] + (elem,)
... yield result
->>> def take(n, seq):
-... return list(islice(seq, n))
+>>> def tee(iterable):
+... "Return two independent iterators from a single iterable"
+... def gen(next, data={}, cnt=[0]):
+... dpop = data.pop
+... for i in count():
+... if i == cnt[0]:
+... item = data[i] = next()
+... cnt[0] += 1
+... else:
+... item = dpop(i)
+... yield item
+... next = iter(iterable).next
+... return (gen(next), gen(next))
This is not part of the examples but it tests to make sure the definitions
perform as purported.
+>>> take(10, count())
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
>>> list(enumerate('abc'))
[(0, 'a'), (1, 'b'), (2, 'c')]
@@ -590,8 +607,17 @@
>>> dotproduct([1,2,3], [4,5,6])
32
->>> take(10, count())
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+>>> def irange(start, stop):
+... for i in range(start, stop):
+... yield i
+
+>>> x, y = tee(irange(2,10))
+>>> list(x), list(y)
+([2, 3, 4, 5, 6, 7, 8, 9], [2, 3, 4, 5, 6, 7, 8, 9])
+
+>>> x, y = tee(irange(2,10))
+>>> zip(x, y)
+[(2, 2), (3, 3), (4, 4), (5, 5), (6, 6), (7, 7), (8, 8), (9, 9)]
"""