View source code
Display the source code in std/range/primitives.d from which this
page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a
Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
local clone.
Module std.range.primitives
This module is a submodule of std
.
It defines the bidirectional and forward range primitives for arrays:
empty
, front
, back
, popFront
, popBack
and save
.
It provides basic range functionality by defining several templates for testing whether a given object is a range, and what kind of range it is:
isInputRange |
Tests if something is an input range, defined to be
something from which one can sequentially read data using the
primitives front , popFront , and empty .
|
isOutputRange |
Tests if something is an output range, defined to be
something to which one can sequentially write data using the
put primitive.
|
isForwardRange |
Tests if something is a forward range, defined to be an
input range with the additional capability that one can save one's
current position with the save primitive, thus allowing one to
iterate over the same range multiple times.
|
isBidirectionalRange |
Tests if something is a bidirectional range, that is, a
forward range that allows reverse traversal using the primitives back and popBack .
|
isRandomAccessRange |
Tests if something is a random access range, which is a
bidirectional range that also supports the array subscripting
operation via the primitive opIndex .
|
It also provides number of templates that test for various range capabilities:
hasMobileElements |
Tests if a given range's elements can be moved around using the
primitives moveFront , moveBack , or moveAt .
|
ElementType |
Returns the element type of a given range. |
ElementEncodingType |
Returns the encoding element type of a given range. |
hasSwappableElements |
Tests if a range is a forward range with swappable elements. |
hasAssignableElements |
Tests if a range is a forward range with mutable elements. |
hasLvalueElements |
Tests if a range is a forward range with elements that can be passed by reference and have their address taken. |
hasLength |
Tests if a given range has the length attribute.
|
isInfinite |
Tests if a given range is an infinite range. |
hasSlicing |
Tests if a given range supports the array slicing operation R[x .. y] .
|
Finally, it includes some convenience functions for manipulating ranges:
popFrontN |
Advances a given range by up to n elements. |
popBackN |
Advances a given bidirectional range from the right by up to n elements. |
popFrontExactly |
Advances a given range by up exactly n elements. |
popBackExactly |
Advances a given bidirectional range from the right by exactly n elements. |
moveFront |
Removes the front element of a range. |
moveBack |
Removes the back element of a bidirectional range. |
moveAt |
Removes the i'th element of a random-access range. |
walkLength |
Computes the length of any range in O(n) time. |
put |
Outputs element e to a range.
|
Functions
Name | Description |
---|---|
back(a)
|
Implements the range interface primitive back for built-in
arrays. Due to the fact that nonmember functions can be called with
the first argument using the dot notation, array is
equivalent to back(array) . For narrow strings, back automatically returns the last code point as a dchar .
|
empty(a)
|
Implements the range interface primitive empty for types that
obey hasLength property and for narrow strings. Due to the
fact that nonmember functions can be called with the first argument
using the dot notation, a is equivalent to empty(a) .
|
front(a)
|
Implements the range interface primitive front for built-in
arrays. Due to the fact that nonmember functions can be called with
the first argument using the dot notation, array is
equivalent to front(array) . For narrow strings, front automatically returns the first code point as a dchar .
|
moveAt(r, i)
|
Moves element at index i of r out and returns it. Leaves r[i] in a destroyable state that does not allocate any resources
(usually equal to its value).
|
moveBack(r)
|
Moves the back of r out and returns it. Leaves r in a
destroyable state that does not allocate any resources (usually equal
to its value).
|
moveFront(r)
|
Moves the front of r out and returns it. Leaves r in a
destroyable state that does not allocate any resources (usually equal
to its value).
|
popBack(a)
|
Implements the range interface primitive popBack for built-in
arrays. Due to the fact that nonmember functions can be called with
the first argument using the dot notation, array is
equivalent to popBack(array) . For narrow strings, popFront automatically eliminates the last code point.
|
popBackExactly(r, n)
|
Eagerly advances r itself (not a copy) exactly n times (by
calling r ). popFrontExactly takes r by ref ,
so it mutates the original range. Completes in Ο(1 ) steps for ranges
that support slicing, and have either length or are infinite.
Completes in Ο(n ) time for all other ranges.
|
popBackN(r, n)
|
popFrontN eagerly advances r itself (not a copy) up to n times
(by calling r ). popFrontN takes r by ref ,
so it mutates the original range. Completes in Ο(1 ) steps for ranges
that support slicing and have length.
Completes in Ο(n ) time for all other ranges.
|
popFront(a)
|
Implements the range interface primitive popFront for built-in
arrays. Due to the fact that nonmember functions can be called with
the first argument using the dot notation, array is
equivalent to popFront(array) . For narrow strings,
popFront automatically advances to the next code
point.
|
popFrontExactly(r, n)
|
Eagerly advances r itself (not a copy) exactly n times (by
calling r ). popFrontExactly takes r by ref ,
so it mutates the original range. Completes in Ο(1 ) steps for ranges
that support slicing, and have either length or are infinite.
Completes in Ο(n ) time for all other ranges.
|
popFrontN(r, n)
|
popFrontN eagerly advances r itself (not a copy) up to n times
(by calling r ). popFrontN takes r by ref ,
so it mutates the original range. Completes in Ο(1 ) steps for ranges
that support slicing and have length.
Completes in Ο(n ) time for all other ranges.
|
put(r, e)
|
Outputs e to r . The exact effect is dependent upon the two
types. Several cases are accepted, as described below. The code snippets
are attempted in order, and the first to compile "wins" and gets
evaluated.
|
save(a)
|
Implements the range interface primitive save for built-in
arrays. Due to the fact that nonmember functions can be called with
the first argument using the dot notation, array is
equivalent to save(array) . The function does not duplicate the
content of the array, it simply returns its argument.
|
walkLength(range)
|
This is a best-effort implementation of length for any kind of
range.
|
Manifest constants
Name | Type | Description |
---|---|---|
autodecodeStrings
|
||
hasAssignableElements
|
Returns true if R is an input range and has mutable
elements. The following code should compile for any range
with assignable elements.
|
|
hasLength
|
Yields true if R has a length member that returns a value of size_t
type. R does not have to be a range. If R is a range, algorithms in the
standard library are only guaranteed to support length with type size_t .
|
|
hasLvalueElements
|
Tests whether the range R has lvalue elements. These are defined as
elements that can be passed by reference and have their address taken.
The following code should compile for any range with lvalue elements.
|
|
hasMobileElements
|
Returns true iff R is an input range that supports the
moveFront primitive, as well as moveBack and moveAt if it's a
bidirectional or random access range. These may be explicitly implemented, or
may work via the default behavior of the module level functions moveFront
and friends. The following code should compile for any range
with mobile elements.
|
|
hasSlicing
|
Returns true if R offers a slicing operator with integral boundaries
that returns a forward range type.
|
|
hasSwappableElements
|
Returns true if R is an input range and has swappable
elements. The following code should compile for any range
with swappable elements.
|
|
isBidirectionalRange
|
Returns true if R is a bidirectional range. A bidirectional
range is a forward range that also offers the primitives back and
popBack . The following code should compile for any bidirectional
range.
|
|
isForwardRange
|
Returns true if R is a forward range. A forward range is an
input range r that can save "checkpoints" by saving r
to another value of type R . Notable examples of input ranges that
are not forward ranges are file/socket ranges; copying such a
range will not save the position in the stream, and they most likely
reuse an internal buffer as the entire stream does not sit in
memory. Subsequently, advancing either the original or the copy will
advance the stream, so the copies are not independent.
|
|
isInfinite
|
Returns true if R is an infinite input range. An
infinite input range is an input range that has a statically-defined
enumerated member called empty that is always false ,
for example:
|
|
isInputRange
|
Returns true if R is an input range. An input range must
define the primitives empty , popFront , and front . The
following code should compile for any input range.
|
|
isOutputRange
|
Returns true if R is an output range for elements of type
E . An output range is defined functionally as a range that
supports the operation put(r, e) as defined above.
|
|
isRandomAccessRange
|
Returns true if R is a random-access range. A random-access
range is a bidirectional range that also offers the primitive opIndex , OR an infinite forward range that offers opIndex . In
either case, the range must either offer length or be
infinite. The following code should compile for any random-access
range.
|
Aliases
Name | Type | Description |
---|---|---|
ElementEncodingType
|
E
|
The encoding element type of R . For narrow strings (char[] ,
wchar[] and their qualified variants including string and
wstring ), ElementEncodingType is the character type of the
string. For all other types, ElementEncodingType is the same as
ElementType .
|
ElementType
|
T
|
The element type of R . R does not have to be a range. The
element type is determined as the type yielded by r for an
object r of type R . For example, ElementType!(T[]) is
T if T[] isn't a narrow string; if it is, the element type is
dchar . If R doesn't have front , ElementType!R is
void .
|
Authors
Andrei Alexandrescu, David Simcha, and Jonathan M Davis. Credit for some of the ideas in building this module goes to Leonardo Maffi.
License
Copyright © 1999-2022 by the D Language Foundation | Page generated by ddox.