phobos ~master (2023-10-10T16:11:09Z)

- interfacesmodule std.range.interfaces
This module is a submodule of std.range.

- primitivesmodule std.range.primitives
This module is a submodule of std.range.

- std.arraypublic
`import std.array;` - Undocumented in source.

- std.range.interfacespublic
`import std.range.interfaces;` - Undocumented in source.

- std.range.primitivespublic
`import std.range.primitives;` - Undocumented in source.

- SearchPolicyenum SearchPolicy
Policy used with the searching primitives

`lowerBound`,`upperBound`, and`equalRange`of SortedRange below.- SortedRangeOptionsenum SortedRangeOptions
Options for SortedRange ranges (below).

- StoppingPolicyenum StoppingPolicy
- TransverseOptionsenum TransverseOptions
Options for the FrontTransversal and Transversal ranges (below).

- assumeSortedauto assumeSorted(R r)
Assumes

`r`is sorted by predicate`pred`and returns the corresponding`SortedRange!(pred, R)`having`r`as support. To check for sorted-ness at cost*O*(n), use std.algorithm.sorting.isSorted.- bitwiseauto bitwise(R range)
Bitwise adapter over an integral type range. Consumes the range elements bit by bit, from the least significant bit to the most significant bit.

- chainauto chain(Ranges rs)
Spans multiple ranges in sequence. The function

`chain`takes any number of ranges and returns a`Chain!(R1, R2,...)`object. The ranges may be different, but they must have the same element type. The result is a range that offers the`front`,`popFront`, and`empty`primitives. If all input ranges offer random access and`length`,`Chain`offers them as well.- chooseauto choose(bool condition, R1 r1, R2 r2)
Choose one of two ranges at runtime depending on a Boolean condition.

- chooseAmongauto chooseAmong(size_t index, Ranges rs)
Choose one of multiple ranges at runtime.

- chunks
`Chunks!Source`chunks(Source source, size_t chunkSize) This range iterates over fixed-sized chunks of size

`chunkSize`of a`source`range.`Source`must be an input range.`chunkSize`must be greater than zero.- cycleauto cycle(R input)
`Cycle!R`cycle(R input, size_t index)Repeats the given forward range ad infinitum. If the original range is infinite (fact that would make

`Cycle`the identity application),`Cycle`detects that and aliases itself to the range type itself. That works for non-forward ranges too. If the original range has random access,`Cycle`offers random access and also offers a constructor taking an initial position`index`.`Cycle`works with static arrays in addition to ranges, mostly for performance reasons.- drop
`R`drop(R range, size_t n) - dropBack
`R`dropBack(R range, size_t n) Convenience function which calls std.range.primitives.popFrontN

`(range, n)`and returns`range`.`drop`makes it easier to pop elements from a range and then pass it to another function within a single expression, whereas`popFrontN`would require multiple statements.- dropBackExactly
`R`dropBackExactly(R range, size_t n) Similar to drop and

`dropBack`but they call`range.$(LREF popFrontExactly)(n)`and`range.popBackExactly(n)`instead.- dropBackOne
`R`dropBackOne(R range) Convenience function which calls

`range.popFront()`and returns`range`.`dropOne`makes it easier to pop an element from a range and then pass it to another function within a single expression, whereas`popFront`would require multiple statements.- dropExactly
`R`dropExactly(R range, size_t n) Similar to drop and

`dropBack`but they call`range.$(LREF popFrontExactly)(n)`and`range.popBackExactly(n)`instead.- dropOne
`R`dropOne(R range) Convenience function which calls

`range.popFront()`and returns`range`.`dropOne`makes it easier to pop an element from a range and then pass it to another function within a single expression, whereas`popFront`would require multiple statements.- enumerateauto enumerate(Range range, Enumerator start)
Iterate over

`range`with an attached index variable.- evenChunks
`EvenChunks!Source`evenChunks(Source source, size_t chunkCount) This range splits a

`source`range into`chunkCount`chunks of approximately equal length.`Source`must be a forward range with known length.- frontTransversal
`FrontTransversal!(RangeOfRanges, opt)`frontTransversal(RangeOfRanges rr) Given a range of ranges, iterate transversally through the first elements of each of the enclosed ranges.

- generateauto generate(Fun fun)
- auto generate()
Given callable (std.traits.isCallable)

`fun`, create as a range whose front is defined by successive calls to`fun()`. This is especially useful to call function with global side effects (random functions), or to create ranges expressed as a single delegate, rather than an entire`front`/`popFront`/`empty`structure.`fun`maybe be passed either a template alias parameter (existing function, delegate, struct type defining`static opCall`) or a run-time value argument (delegate, function object). The result range models an InputRange (std.range.primitives.isInputRange). The resulting range will call`fun()`on construction, and every call to`popFront`, and the cached value will be returned when`front`is called.- indexed
`Indexed!(Source, Indices)`indexed(Source source, Indices indices) This struct takes two ranges,

`source`and`indices`, and creates a view of`source`as if its elements were reordered according to`indices`.`indices`may include only a subset of the elements of`source`and may also repeat elements.- iotaauto iota(B begin, E end, S step)
- auto iota(B begin, E end)
- auto iota(E end)
Creates a range of values that span the given starting and stopping values.

- lockstep
`Lockstep!(Ranges)`lockstep(Ranges ranges) `Lockstep!(Ranges)`lockstep(Ranges ranges, StoppingPolicy s)Iterate multiple ranges in lockstep using a

`foreach`loop. In contrast to zip it allows reference access to its elements. If only a single range is passed in, the`Lockstep`aliases itself away. If the ranges are of different lengths and`s`==`StoppingPolicy.shortest`stop after the shortest range is empty. If the ranges are of different lengths and`s`==`StoppingPolicy.requireSameLength`, throw an exception.`s`may not be`StoppingPolicy.longest`, and passing this will throw an exception.- nullSinkauto ref nullSink()
An OutputRange that discards the data it receives.

- onlyauto only(Values values)
- auto only()
Assemble

`values`into a range that carries all its elements in-situ.- padLeftauto padLeft(R r, E e, size_t n)
Extends the length of the input range

`r`by padding out the start of the range with the element`e`. The element`e`must be of a common type with the element type of the range`r`as defined by std.traits.CommonType. If`n`is less than the length of of`r`, then`r`is returned unmodified.- padRightauto padRight(R r, E e, size_t n)
Extend the length of the input range

`r`by padding out the end of the range with the element`e`. The element`e`must be of a common type with the element type of the range`r`as defined by std.traits.CommonType. If`n`is less than the length of of`r`, then the contents of`r`are returned.- radialauto radial(Range r, I startingIndex)
- auto radial(R r)
Iterates a random-access range starting from a given point and progressively extending left and right from that point. If no initial point is given, iteration starts from the middle of the range. Iteration spans the entire range.

- rebindable (from std.typecons)
`Rebindable!T`rebindable(Rebindable!T obj) via public`import std.typecons : Flag, Yes, No, Rebindable, rebindable;` This function simply returns the

`Rebindable`object passed in. It's useful in generic programming cases when a given object may be either a regular`class`or a`Rebindable`.- recurrence
`Recurrence!(fun, CommonType!(State), State.length)`recurrence(State initial) Creates a mathematical sequence given the initial values and a recurrence function that computes the next value from the existing values. The sequence comes in the form of an infinite forward range. The type

`Recurrence`itself is seldom used directly; most often, recurrences are obtained by calling the function`recurrence`.- refRangeauto refRange(R* range)
Wrapper which effectively makes it possible to pass a range by reference. Both the original range and the RefRange will always have the exact same elements. Any operation done on one will affect the other. So, for instance, if it's passed to a function which would implicitly copy the original range if it were passed to it, the original range is

*not*copied but is consumed as if it were a reference type.- repeat
`Repeat!T`repeat(T value) `Take!(Repeat!T)`repeat(T value, size_t n)Create a range which repeats one value.

- retroauto retro(Range r)
Iterates a bidirectional range backwards. The original range can be accessed by using the

`source`property. Applying retro twice to the same range yields the original range.- roundRobinauto roundRobin(Rs rs)
`roundRobin(r1, r2, r3)`yields`r1.front`, then`r2.front`, then`r3.front`, after which it pops off one element from each and continues again from`r1`. For example, if two ranges are involved, it alternately yields elements off the two ranges.`roundRobin`stops after it has consumed all ranges (skipping over the ones that finish early).- sequenceauto sequence(State args)
`Sequence`is similar to`Recurrence`except that iteration is presented in the so-called closed form. This means that the`n`th element in the series is computable directly from the initial values and`n`itself. This implies that the interface offered by`Sequence`is a random-access range, as opposed to the regular`Recurrence`, which only offers forward iteration.- slideauto slide(Source source, size_t windowSize, size_t stepSize)
A fixed-sized sliding window iteration of size

`windowSize`over a`source`range by a custom`stepSize`.- strideauto stride(Range r, size_t n)
Iterates range

`r`with stride`n`. If the range is a random-access range, moves by indexing into the range; otherwise, moves by successive calls to`popFront`. Applying stride twice to the same range results in a stride with a step that is the product of the two applications. It is an error for`n`to be 0.- tailauto tail(Range range, size_t n)
Return a range advanced to within

`_n`elements of the end of`range`.- take
`Take!R`take(R input, size_t n) Lazily takes only up to

`n`elements of a range. This is particularly useful when using with infinite ranges.- takeExactlyauto takeExactly(R range, size_t n)
Similar to take, but assumes that

`range`has at least`n`elements. Consequently, the result of`takeExactly(range, n)`always defines the`length`property (and initializes it to`n`) even when`range`itself does not define`length`.- takeNoneauto takeNone()
Returns an empty range which is statically known to be empty and is guaranteed to have

`length`and be random access regardless of`R`'s capabilities.- takeNoneauto takeNone(R range)
Creates an empty range from the given range in

*O*(1). If it can, it will return the same range type. If not, it will return`takeExactly(range, 0)`.- takeOneauto takeOne(R source)
Returns a range with at most one element; for example,

`takeOne([42, 43, 44])`returns a range consisting of the integer`42`. Calling`popFront()`off that range renders it empty.- teeauto tee(R1 inputRange, R2 outputRange)
- auto tee(R1 inputRange)
Implements a "tee" style pipe, wrapping an input range so that elements of the range can be passed to a provided function or OutputRange as they are iterated over. This is useful for printing out intermediate values in a long chain of range code, performing some operation with side-effects on each call to

`front`or`popFront`, or diverting the elements of a range into an auxiliary OutputRange.- transposed
`Transposed!(RangeOfRanges, opt)`transposed(RangeOfRanges rr) Given a range of ranges, returns a range of ranges where the

*i*'th subrange contains the*i*'th elements of the original subranges.- transversal
`Transversal!(RangeOfRanges, opt)`transversal(RangeOfRanges rr, size_t n) Given a range of ranges, iterate transversally through the

`n`th element of each of the enclosed ranges. This function is similar to`unzip`in other languages.- zipauto zip(Ranges ranges)
- auto zip(StoppingPolicy sp, Ranges ranges)
Iterate several ranges in lockstep. The element type is a proxy tuple that allows accessing the current element in the

`n`th range by using`e[n]`.

- Chunksstruct Chunks(Source)
This range iterates over fixed-sized chunks of size

`chunkSize`of a`source`range.`Source`must be an input range.`chunkSize`must be greater than zero.- Cyclestruct Cycle(R)
Repeats the given forward range ad infinitum. If the original range is infinite (fact that would make

`Cycle`the identity application),`Cycle`detects that and aliases itself to the range type itself. That works for non-forward ranges too. If the original range has random access,`Cycle`offers random access and also offers a constructor taking an initial position`index`.`Cycle`works with static arrays in addition to ranges, mostly for performance reasons.- EvenChunksstruct EvenChunks(Source)
This range splits a

`source`range into`chunkCount`chunks of approximately equal length.`Source`must be a forward range with known length.- FrontTransversalstruct FrontTransversal(Ror, TransverseOptions opt = TransverseOptions.assumeJagged)
Given a range of ranges, iterate transversally through the first elements of each of the enclosed ranges.

- Indexedstruct Indexed(Source, Indices)
This struct takes two ranges,

`source`and`indices`, and creates a view of`source`as if its elements were reordered according to`indices`.`indices`may include only a subset of the elements of`source`and may also repeat elements.- Lockstepstruct Lockstep(Ranges...)
Iterate multiple ranges in lockstep using a

`foreach`loop. In contrast to zip it allows reference access to its elements. If only a single range is passed in, the`Lockstep`aliases itself away. If the ranges are of different lengths and`s`==`StoppingPolicy.shortest`stop after the shortest range is empty. If the ranges are of different lengths and`s`==`StoppingPolicy.requireSameLength`, throw an exception.`s`may not be`StoppingPolicy.longest`, and passing this will throw an exception.- No (from std.typecons)struct No via public
`import std.typecons : Flag, Yes, No, Rebindable, rebindable;` Convenience names that allow using e.g.

`Yes.encryption`instead of`Flag!"encryption".yes`and`No.encryption`instead of`Flag!"encryption".no`.- NullSinkstruct NullSink
An OutputRange that discards the data it receives.

- Rebindable (from std.typecons)struct Rebindable(T) via public
`import std.typecons : Flag, Yes, No, Rebindable, rebindable;` `Rebindable!(T)`is a simple, efficient wrapper that behaves just like an object of type`T`, except that you can reassign it to refer to another object. For completeness,`Rebindable!(T)`aliases itself away to`T`if`T`is a non-const object type.- Recurrencestruct Recurrence(alias fun, StateType, size_t stateSize)
Creates a mathematical sequence given the initial values and a recurrence function that computes the next value from the existing values. The sequence comes in the form of an infinite forward range. The type

`Recurrence`itself is seldom used directly; most often, recurrences are obtained by calling the function`recurrence`.- RefRangestruct RefRange(R)
Wrapper which effectively makes it possible to pass a range by reference. Both the original range and the RefRange will always have the exact same elements. Any operation done on one will affect the other. So, for instance, if it's passed to a function which would implicitly copy the original range if it were passed to it, the original range is

*not*copied but is consumed as if it were a reference type.- Repeatstruct Repeat(T)
Create a range which repeats one value.

- Sequencestruct Sequence(alias fun, State)
`Sequence`is similar to`Recurrence`except that iteration is presented in the so-called closed form. This means that the`n`th element in the series is computable directly from the initial values and`n`itself. This implies that the interface offered by`Sequence`is a random-access range, as opposed to the regular`Recurrence`, which only offers forward iteration.- SortedRangestruct SortedRange(Range, alias pred = "a < b", SortedRangeOptions opt = SortedRangeOptions.assumeSorted)
Represents a sorted range. In addition to the regular range primitives, supports additional operations that take advantage of the ordering, such as merge and binary search. To obtain a

`SortedRange`from an unsorted range`r`, use std.algorithm.sorting.sort which sorts`r`in place and returns the corresponding`SortedRange`. To construct a`SortedRange`from a range`r`that is known to be already sorted, use assumeSorted.- Takestruct Take(Range)
Lazily takes only up to

`n`elements of a range. This is particularly useful when using with infinite ranges.- Transversalstruct Transversal(Ror, TransverseOptions opt = TransverseOptions.assumeJagged)
Given a range of ranges, iterate transversally through the

`n`th element of each of the enclosed ranges. This function is similar to`unzip`in other languages.- Yes (from std.typecons)struct Yes via public
`import std.typecons : Flag, Yes, No, Rebindable, rebindable;` Convenience names that allow using e.g.

`Yes.encryption`instead of`Flag!"encryption".yes`and`No.encryption`instead of`Flag!"encryption".no`.- Zipstruct Zip(Ranges...)
Iterate several ranges in lockstep. The element type is a proxy tuple that allows accessing the current element in the

`n`th range by using`e[n]`.

- Cycletemplate Cycle(R)
Repeats the given forward range ad infinitum. If the original range is infinite (fact that would make

`Cycle`the identity application),`Cycle`detects that and aliases itself to the range type itself. That works for non-forward ranges too. If the original range has random access,`Cycle`offers random access and also offers a constructor taking an initial position`index`.`Cycle`works with static arrays in addition to ranges, mostly for performance reasons.- Flag (from std.typecons)template Flag(string name) via public
`import std.typecons : Flag, Yes, No, Rebindable, rebindable;` Defines a simple, self-documenting yes/no flag. This makes it easy for APIs to define functions accepting flags without resorting to

`bool`, which is opaque in calls, and without needing to define an enumerated type separately. Using`Flag!"Name"`instead of`bool`makes the flag's meaning visible in calls. Each yes/no flag has its own type, which makes confusions and mix-ups impossible.- SortedRangetemplate SortedRange(Range, alias pred = "a < b", SortedRangeOptions opt = SortedRangeOptions.assumeSorted)
Represents a sorted range. In addition to the regular range primitives, supports additional operations that take advantage of the ordering, such as merge and binary search. To obtain a

`SortedRange`from an unsorted range`r`, use std.algorithm.sorting.sort which sorts`r`in place and returns the corresponding`SortedRange`. To construct a`SortedRange`from a range`r`that is known to be already sorted, use assumeSorted.- Taketemplate Take(R)
Lazily takes only up to

`n`elements of a range. This is particularly useful when using with infinite ranges.- isSomeFiniteCharInputRangetemplate isSomeFiniteCharInputRange(R)
This simplifies a commonly used idiom in phobos for accepting any kind of string parameter. The type

`R`can for example be a simple string, chained string using std.range.chain, std.path.chainPath or any other input range of characters.- isTwoWayCompatibletemplate isTwoWayCompatible(alias fn, T1, T2)
Returns true if

`fn`accepts variables of type T1 and T2 in any order. The following code should compile:

chain | Concatenates several ranges into a single range. |

choose | Chooses one of two ranges at runtime based on a boolean condition. |

chooseAmong | Chooses one of several ranges at runtime based on an index. |

chunks | Creates a range that returns fixed-size chunks of the original range. |

cycle | Creates an infinite range that repeats the given forward range indefinitely. Good for implementing circular buffers. |

drop | Creates the range that results from discarding the first n
elements from the given range. |

dropBack | Creates the range that results from discarding the last n
elements from the given range. |

dropExactly | Creates the range that results from discarding exactly n
of the first elements from the given range. |

dropBackExactly | Creates the range that results from discarding exactly n
of the last elements from the given range. |

dropOne | Creates the range that results from discarding the first element from the given range. |

$(LREF dropBackOne) | Creates the range that results from discarding the last element from the given range. |

enumerate | Iterates a range with an attached index variable. |

evenChunks | Creates a range that returns a number of chunks of approximately equal length from the original range. |

frontTransversal | Creates a range that iterates over the first elements of the given ranges. |

generate | Creates a range by successive calls to a given function. This allows to create ranges as a single delegate. |

indexed | Creates a range that offers a view of a given range as though its elements were reordered according to a given range of indices. |

iota | Creates a range consisting of numbers between a starting point and ending point, spaced apart by a given interval. |

lockstep | Iterates n ranges in lockstep, for use in a foreach
loop. Similar to zip, except that lockstep is designed
especially for foreach loops. |

nullSink | An output range that discards the data it receives. |

only | Creates a range that iterates over the given arguments. |

padLeft | Pads a range to a specified length by adding a given element to the front of the range. Is lazy if the range has a known length. |

padRight | Lazily pads a range to a specified length by adding a given element to the back of the range. |

radial | Given a random-access range and a starting point, creates a range that alternately returns the next left and next right element to the starting point. |

recurrence | Creates a forward range whose values are defined by a mathematical recurrence relation. |

refRange | Pass a range by reference. Both the original range and the RefRange will always have the exact same elements. Any operation done on one will affect the other. |

repeat | Creates a range that consists of a single element repeated n
times, or an infinite range repeating that element indefinitely. |

retro | Iterates a bidirectional range backwards. |

roundRobin | Given n ranges, creates a new range that return the n
first elements of each range, in turn, then the second element of each
range, and so on, in a round-robin fashion. |

sequence | Similar to recurrence, except that a random-access range is
created. |

$(LREF slide) | Creates a range that returns a fixed-size sliding window over the original range. Unlike chunks, it advances a configurable number of items at a time, not one chunk at a time. |

stride | Iterates a range with stride n. |

tail | Return a range advanced to within n elements of the end of
the given range. |

take | Creates a sub-range consisting of only up to the first n
elements of the given range. |

takeExactly | Like take, but assumes the given range actually has n
elements, and therefore also defines the length property. |

takeNone | Creates a random-access range consisting of zero elements of the given range. |

takeOne | Creates a random-access range consisting of exactly the first element of the given range. |

tee | Creates a range that wraps a given range, forwarding along its elements while also calling a provided function with each element. |

transposed | Transposes a range of ranges. |

transversal | Creates a range that iterates over the n'th elements of the
given random-access ranges. |

zip | Given n ranges, creates a range that successively returns a
tuple of all the first elements, a tuple of all the second elements,
etc. |

Sortedness:

Ranges whose elements are sorted afford better efficiency with certain operations. For this, the assumeSorted function can be used to construct a SortedRange from a pre-sorted range. The std.algorithm.sorting.sort function also conveniently returns a SortedRange. SortedRange objects provide some additional range operations that take advantage of the fact that the range is sorted.

This module defines the notion of a range. Ranges generalize the concept of arrays, lists, or anything that involves sequential access. This abstraction enables the same set of algorithms (see std.algorithm) to be used with a vast variety of different concrete types. For example, a linear search algorithm such as std.algorithm.searching.find works not just for arrays, but for linked-lists, input files, incoming network data, etc.

Guides:

There are many articles available that can bolster understanding ranges:

Introduction to Rangestalk at DConf 2015 a vivid introduction from its core constructs to practical advice.On Iterationfor conceptual aspect of ranges and the motivationSubmodules:

This module has two submodules:

The std.range.primitives submodule provides basic range functionality. It defines several templates for testing whether a given object is a range, what kind of range it is, and provides some common range operations.

The std.range.interfaces submodule provides object-based interfaces for working with ranges via runtime polymorphism.

The remainder of this module provides a rich set of range creation and composition templates that let you construct new ranges out of existing ranges: