std.algorithm.iteration

This is a submodule of std.algorithm. It contains generic iteration algorithms.

Cheat Sheet
Function NameDescription
cacheEagerly evaluates and caches another range's front.
cacheBidirectionalAs above, but also provides back and popBack.
chunkBychunkBy!((a,b) => a[1] == b[1])([[1, 1], [1, 2], [2, 2], [2, 1]]) returns a range containing 3 subranges: the first with just [1, 1]; the second with the elements [1, 2] and [2, 2]; and the third with just [2, 1].
cumulativeFoldcumulativeFold!((a, b) => a + b)([1, 2, 3, 4]) returns a lazily-evaluated range containing the successive reduced values 1, 3, 6, 10.
eacheach!writeln([1, 2, 3]) eagerly prints the numbers 1, 2 and 3 on their own lines.
filterfilter!(a => a > 0)([1, -1, 2, 0, -3]) iterates over elements 1 and 2.
filterBidirectionalSimilar to filter, but also provides back and popBack at a small increase in cost.
foldfold!((a, b) => a + b)([1, 2, 3, 4]) returns 10.
groupgroup([5, 2, 2, 3, 3]) returns a range containing the tuples tuple(5, 1), tuple(2, 2), and tuple(3, 2).
joinerjoiner(["hello", "world!"], "; ") returns a range that iterates over the characters "hello; world!". No new string is created - the existing inputs are iterated.
mapmap!(a => a * 2)([1, 2, 3]) lazily returns a range with the numbers 2, 4, 6.
permutationsLazily computes all permutations using Heap's algorithm.
reducereduce!((a, b) => a + b)([1, 2, 3, 4]) returns 10. This is the old implementation of fold.
splitterLazily splits a range by a separator.
sumSame as fold, but specialized for accurate summation.
uniqIterates over the unique elements in a range, which is assumed sorted.

Members

Functions

cache
auto cache(Range range)
cacheBidirectional
auto cacheBidirectional(Range range)

cache eagerly evaluates front of range on each construction or call to popFront, to store the result in a cache. The result is then directly returned when front is called, rather than re-evaluated.

chunkBy
auto chunkBy(Range r)

Chunks an input range into subranges of equivalent adjacent elements. In other languages this is often called partitionBy, groupBy or sliceWhen.

group
Group!(pred, Range) group(Range r)

Groups consecutively equivalent elements into a single tuple of the element and the number of its repetitions.

joiner
auto joiner(RoR r, Separator sep)
auto joiner(RoR r)

Lazily joins a range of ranges with a separator. The separator itself is a range. If a separator is not provided, then the ranges are joined directly without anything in between them (often called flatten in other languages).

permutations
Permutations!Range permutations(Range r)

Lazily computes all permutations of r using Heap's algorithm.

splitter
auto splitter(Range r, Separator s)

Lazily splits a range using an element as a separator. This can be used with any narrow string type or sliceable range type, but is most popular with string types.

splitter
auto splitter(Range r, Separator s)

Similar to the previous overload of splitter, except this one uses another range as a separator. This can be used with any narrow string type or sliceable range type, but is most popular with string types. The predicate is passed to std.functional.binaryFun, and can either accept a string, or any callable that can be executed via pred(r.front, s.front).

splitter
auto splitter(Range input)

Similar to the previous overload of splitter, except this one does not use a separator. Instead, the predicate is an unary function on the input range's element type. The isTerminator predicate is passed to std.functional.unaryFun and can either accept a string, or any callable that can be executed via pred(element, s).

splitter
auto splitter(C[] s)

Lazily splits the string s into words, using whitespace as the delimiter.

sum
auto sum(R r)
auto sum(R r, E seed)

Sums elements of r, which must be a finite input range. Although conceptually sum(r) is equivalent to fold!((a, b) => a + b)(r, 0), sum uses specialized algorithms to maximize accuracy, as follows.

uniq
auto uniq(Range r)

Lazily iterates unique consecutive elements of the given range (functionality akin to the _uniq system utility). Equivalence of elements is assessed by using the predicate pred, by default "a == b". The predicate is passed to std.functional.binaryFun, and can either accept a string, or any callable that can be executed via pred(element, element). If the given range is bidirectional, uniq also yields a bidirectional range.

Structs

Group
struct Group(alias pred, R)

Groups consecutively equivalent elements into a single tuple of the element and the number of its repetitions.

Permutations
struct Permutations(Range)

Lazily computes all permutations of r using Heap's algorithm.

Templates

cumulativeFold
template cumulativeFold(fun...)

Similar to fold, but returns a range containing the successive reduced values. The call cumulativeFold!(fun)(range, seed) first assigns seed to an internal variable result, also called the accumulator. The returned range contains the values result = fun(result, x) lazily evaluated for each element x in range. Finally, the last element has the same value as fold!(fun)(seed, range). The one-argument version cumulativeFold!(fun)(range) works similarly, but it returns the first element unchanged and uses it as seed for the next elements. This function is also known as partial_sum, accumulate, scan, Cumulative Sum.

each
template each(alias pred = "a")

Eagerly iterates over r and calls pred over each element.

filter
template filter(alias predicate)

auto filter(Range)(Range rs) if (isInputRange!(Unqual!Range));

filterBidirectional
template filterBidirectional(alias pred)

auto filterBidirectional(Range)(Range r) if (isBidirectionalRange!(Unqual!Range));

fold
template fold(fun...)

Implements the homonym function (also known as accumulate, compress, inject, or foldl) present in various programming languages of functional flavor. The call fold!(fun)(range, seed) first assigns seed to an internal variable result, also called the accumulator. Then, for each element x in range, result = fun(result, x) gets evaluated. Finally, result is returned. The one-argument version fold!(fun)(range) works similarly, but it uses the first element of the range as the seed (the range must be non-empty).

map
template map(fun...)

auto map(Range)(Range r) if (isInputRange!(Unqual!Range));

reduce
template reduce(fun...)

Implements the homonym function (also known as accumulate, compress, inject, or foldl) present in various programming languages of functional flavor. There is also fold which does the same thing but with the opposite parameter order. The call reduce!(fun)(seed, range) first assigns seed to an internal variable result, also called the accumulator. Then, for each element x in range, result = fun(result, x) gets evaluated. Finally, result is returned. The one-argument version reduce!(fun)(range) works similarly, but it uses the first element of the range as the seed (the range must be non-empty).

Meta