std.algorithm.iteration: Add permutations (fix issue 13596)

std/algorithm/iteration.d

@@ -35,6 +35,8 @@ $(T2 joiner,
 $(T2 map,
         $(D map!"2 * a"([1, 2, 3])) lazily returns a range with the numbers
         $(D 2), $(D 4), $(D 6).)
+$(T2 permutations,
+        Lazily computes all permutations using Heap's algorithm.)
 $(T2 reduce,
         $(D reduce!"a + b"([1, 2, 3, 4])) returns $(D 10).)
 $(T2 splitter,
@@ -4193,3 +4195,88 @@ private struct UniqResult(alias pred, Range)
         }
     }
 }
+
+// permutations
+struct Permutations(Range)
+    if (isRandomAccessRange!Range && hasLength!Range)
+{
+    size_t[] indices, state;
+    Range r;
+
+    this(Range r)
+    {
+        import std.range : iota;
+        import std.array : array;
+
+        this.r = r;
+        state = r.length ? new size_t[r.length-1] : null;
+        indices = iota(size_t(r.length)).array;
+        empty = r.length == 0;
+    }
+
+    bool empty;
+
+    @property auto front()
+    {
+        import std.range : indexed;
+        return r.indexed(indices);
+    }
+
+    void popFront()
+    {
+        void next(int n)
+        {
+            import std.algorithm.mutation : swap;
+
+            if (n > indices.length)
+            {
+                empty = true;
+                return;
+            }
+
+            if (n % 2 == 1)
+                swap(indices[0], indices[n-1]);
+            else
+                swap(indices[state[n-2]], indices[n-1]);
+
+            if (++state[n-2] == n)
+            {
+                state[n-2] = 0;
+                next(n+1);
+            }
+        }
+
+        next(2);
+    }
+}
+
+/**
+Lazily computes all _permutations of $(D r) using $(WEB
+en.wikipedia.org/wiki/Heap%27s_algorithm, Heap's algorithm).
+
+Returns:
+A forward range the elements of which are an $(XREF range,
+indexed) view into $(D r).
+
+See_Also:
+$(XREF_PACK algorithm,sorting,nextPermutation).
+*/
+Permutations!Range permutations(Range)(Range r)
+    if (isRandomAccessRange!Range && hasLength!Range)
+{
+    return typeof(return)(r);
+}
+
+///
+unittest
+{
+    import std.algorithm.comparison : equal;
+    import std.range : iota;
+    assert(equal!equal(iota(3).permutations,
+        [[0, 1, 2],
+         [1, 0, 2],
+         [2, 0, 1],
+         [0, 2, 1],
+         [1, 2, 0],
+         [2, 1, 0]]));
+}

std/algorithm/package.d

@@ -68,6 +68,7 @@ $(TR $(TDNW Iteration)
         $(SUBREF iteration, group)
         $(SUBREF iteration, joiner)
         $(SUBREF iteration, map)
+        $(SUBREF iteration, permutations)
         $(SUBREF iteration, reduce)
         $(SUBREF iteration, splitter)
         $(SUBREF iteration, sum)

std/algorithm/sorting.d

@@ -2432,6 +2432,8 @@ do
  * Returns: false if the range was lexicographically the greatest, in which
  * case the range is reversed back to the lexicographically smallest
  * permutation; otherwise returns true.
+ * See_Also:
+ * $(XREF_PACK algorithm,iteration,permutations).
  */
 bool nextPermutation(alias less="a < b", BidirectionalRange)
                     (BidirectionalRange range)