Add a prepend() recipe to teach a chain() idiom (pythonGH-6415) (pythonGH-6422)

miss-islington · rhettinger · rhettinger · commit 280a767d02c7 · 2018-04-08T14:37:47.000-07:00
(cherry picked from commit 9265dd7) Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
@@ -688,6 +688,11 @@ which incur interpreter overhead.
        "Return first n items of the iterable as a list"
        return list(islice(iterable, n))
 
+   def prepend(value, iterator):
+       "Prepend a single value in front of an iterator"
+       # prepend(1, [2, 3, 4]) -> 1 2 3 4
+       return chain([value], iterator)
+
    def tabulate(function, start=0):
        "Return function(0), function(1), ..."
        return map(function, count(start))
diff --git a/Lib/test/test_itertools.py b/Lib/test/test_itertools.py
@@ -2165,6 +2165,11 @@ def test_permutations_sizeof(self):
 ...     "Return first n items of the iterable as a list"
 ...     return list(islice(iterable, n))
 
+>>> def prepend(value, iterator):
+...     "Prepend a single value in front of an iterator"
+...     # prepend(1, [2, 3, 4]) -> 1 2 3 4
+...     return chain([value], iterator)
+
 >>> def enumerate(iterable, start=0):
 ...     return zip(count(start), iterable)
 
@@ -2317,6 +2322,9 @@ def test_permutations_sizeof(self):
 >>> take(10, count())
 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
+>>> list(prepend(1, [2, 3, 4]))
+[1, 2, 3, 4]
+
 >>> list(enumerate('abc'))
 [(0, 'a'), (1, 'b'), (2, 'c')]
 
