Forward port r68394 for issue 4816.

1 files changed, 12 insertions, 1 deletions

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 67646c6..aef3f6a 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -108,6 +108,8 @@ loops that truncate the stream.
             # combinations(range(4), 3) --> 012 013 023 123
             pool = tuple(iterable)
             n = len(pool)
+            if r > n:
+                return
             indices = range(r)
             yield tuple(pool[i] for i in indices)
             while 1:
@@ -132,6 +134,9 @@ loops that truncate the stream.
                 if sorted(indices) == list(indices):
                     yield tuple(pool[i] for i in indices)
 
+   The number of items returned is ``n! / r! / (n-r)!`` when ``0 <= r <= n``
+   or zero when ``r > n``.
+
    .. versionadded:: 2.6
 
 .. function:: count([n])
@@ -399,6 +404,8 @@ loops that truncate the stream.
             pool = tuple(iterable)
             n = len(pool)
             r = n if r is None else r
+            if r > n:
+                return
             indices = range(n)
             cycles = range(n, n-r, -1)
             yield tuple(pool[i] for i in indices[:r])
@@ -428,6 +435,9 @@ loops that truncate the stream.
                 if len(set(indices)) == r:
                     yield tuple(pool[i] for i in indices)
 
+   The number of items returned is ``n! / (n-r)!`` when ``0 <= r <= n``
+   or zero when ``r > n``.
+
    .. versionadded:: 2.6
 
 .. function:: product(*iterables[, repeat])
@@ -674,7 +684,8 @@ which incur interpreter overhead.
        return (d for d, s in izip(data, selectors) if s)
 
    def combinations_with_replacement(iterable, r):
-       "combinations_with_replacement('ABC', 3) --> AA AB AC BB BC CC"
+       "combinations_with_replacement('ABC', 2) --> AA AB AC BB BC CC"
+       # number items returned:  (n+r-1)! / r! / (n-1)!
        pool = tuple(iterable)
        n = len(pool)
        indices = [0] * r