Clean-up itertools docs and recipes.

1 files changed, 19 insertions, 46 deletions

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index d8c3331..3cef985 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -35,18 +35,11 @@ equivalent result.
 Likewise, the functional tools are designed to work well with the high-speed
 functions provided by the :mod:`operator` module.
 
-The module author welcomes suggestions for other basic building blocks to be
-added to future versions of the module.
-
 Whether cast in pure python form or compiled code, tools that use iterators are
-more memory efficient (and faster) than their list based counterparts. Adopting
+more memory efficient (and often faster) than their list based counterparts. Adopting
 the principles of just-in-time manufacturing, they create data when and where
 needed instead of consuming memory with the computer equivalent of "inventory".
 
-The performance advantage of iterators becomes more acute as the number of
-elements increases -- at some point, lists grow large enough to severely impact
-memory cache performance and start running slowly.
-
 
 .. seealso::
 
@@ -598,55 +591,35 @@ which incur interpreter overhead.
 
 .. testcode::
 
-   def take(n, seq):
-       return list(islice(seq, n))
+   def take(n, iterable):
+       "Return first n items of the iterable as a list"
+       return list(islice(iterable, n))
 
-   def enumerate(iterable):
-       return izip(count(), iterable)
+   def enumerate(iterable, start=0):
+       return izip(count(start), iterable)
 
-   def tabulate(function):
+   def tabulate(function, start=0):
        "Return function(0), function(1), ..."
-       return imap(function, count())
-
-   def iteritems(mapping):
-       return izip(mapping.iterkeys(), mapping.itervalues())
+       return imap(function, count(start))
 
    def nth(iterable, n):
-       "Returns the nth item or raise StopIteration"
-       return islice(iterable, n, None).next()
-
-   def all(seq, pred=None):
-       "Returns True if pred(x) is true for every element in the iterable"
-       for elem in ifilterfalse(pred, seq):
-           return False
-       return True
-
-   def any(seq, pred=None):
-       "Returns True if pred(x) is true for at least one element in the iterable"
-       for elem in ifilter(pred, seq):
-           return True
-       return False
-
-   def no(seq, pred=None):
-       "Returns True if pred(x) is false for every element in the iterable"
-       for elem in ifilter(pred, seq):
-           return False
-       return True
-
-   def quantify(seq, pred=None):
-       "Count how many times the predicate is true in the sequence"
-       return sum(imap(pred, seq))
-
-   def padnone(seq):
+       "Returns the nth item or empty list"
+       return list(islice(iterable, n, n+1))
+
+   def quantify(iterable, pred=bool):
+       "Count how many times the predicate is true"
+       return sum(imap(pred, iterable))
+
+   def padnone(iterable):
        """Returns the sequence elements and then returns None indefinitely.
 
        Useful for emulating the behavior of the built-in map() function.
        """
-       return chain(seq, repeat(None))
+       return chain(iterable, repeat(None))
 
-   def ncycles(seq, n):
+   def ncycles(iterable, n):
        "Returns the sequence elements n times"
-       return chain.from_iterable(repeat(seq, n))
+       return chain.from_iterable(repeat(iterable, n))
 
    def dotproduct(vec1, vec2):
        return sum(imap(operator.mul, vec1, vec2))