std.array

Functions and types that manipulate built-in arrays and associative arrays.

This module provides all kinds of functions to create, manipulate or convert arrays:

Copyright

Copyright Andrei Alexandrescu 2008- and Jonathan M Davis 2011-.

License

Boost License 1.0.

Authors

Andrei Alexandrescu and Jonathan M Davis

Source: std/array.d

var hasCheapIteration
tmpl blockAttribute isCharOrStringOrDcharRange isInputRangeOrConvertible isInputRangeWithLengthOrConvertible nDimensions
struct Appender RefAppender
fn appender appenderNewCapacity array arrayAllocImpl assocArray byPair copyBackwards insertInPlace join minimallyInitializedArray overlap replace replaceFirst replaceInPlace replaceInto replaceLast replaceSlice replicate sameHead sameTail split staticArray uninitializedArray

Types 2

structAppender(A) if (isDynamicArray!A)

Implements an output range that appends data to an array. This is recommended over array ~= data when appending many elements because it is more efficient. Appender maintains its own array metadata locally, so it can avoid the spec/arrays for each append.

Parameters

Athe array type to simulate.

See Also

appender
Fields
private Data * _data
Methods
void reserve(size_t newCapacity)Reserve at least newCapacity elements for appending. Note that more elements may be reserved than requested. If `newCapacity <= capacity`, then nothing is done.
size_t capacity() @property constReturns: the capacity of the array (the maximum number of elements the managed array can accommodate before triggering a reallocation). If any appending will reallocate, `0` will be returned.
size_t length() @property constReturns: The number of elements appended.
inout(T)[] data() @property inoutUse opSlice() from now on. Returns: The managed array.
inout(T)[] opSlice() @property inout @trustedReturns: The managed array.
private void ensureAddable(size_t nelems)
void put(U)(U item) if (canPutItem!U)Appends `item` to the managed array. Performs encoding for `char` types if `A` is a differently typed `char` array.
void put(Range)(Range items) if (canPutConstRange!Range)
void put(Range)(Range items) if (canPutRange!Range)Appends an entire range to the managed array. Performs encoding for `char` elements if `A` is a differently typed `char` array.
string toString()() constGives a string in the form of `Appender!(A)(data)`.
Constructors
this(A arr)Constructs an `Appender` with a given array. Note that this does not copy the data. If the array has a larger capacity as determined by `arr.capacity`, it will be used by the appender. After ini...
Nested Templates
Data
canPutItem(U)
canPutConstRange(Range)
canPutRange(Range)
toString(Writer)ditto
structRefAppender(A) if (isDynamicArray!A)

A version of Appender that can update an array in-place. It forwards all calls to an underlying appender implementation. Any calls made to the appender also update the pointer to the original array passed in.

Tip: Use the arrayPtr overload of appender for construction with type-inference.

Parameters

AThe array type to simulate
Fields
Appender!A impl
A * arr
Methods
void opDispatch(string fn, Args...)(Args args) if (__traits(compiles, (Appender!A a) => mixin("a." ~ fn ~ "(args)")))Wraps remaining `Appender` methods such as put. Params: fn = Method name to call. args = Arguments to pass to the method.
void opOpAssign(string op : "~", U)(U rhs) if (__traits(compiles, (Appender!A a) { a.put(rhs); }))Appends `rhs` to the managed array. Params: rhs = Element or range.
size_t capacity() @property constReturns the capacity of the array (the maximum number of elements the managed array can accommodate before triggering a reallocation). If any appending will reallocate, `capacity` returns `0`.
size_t length() @property constReturns: The number of elements appended.
inout(T)[] data() @property inout
inout(ElementEncodingType!A)[] opSlice() @property inoutReturns: the managed array.
Constructors
this(A * arr)Constructs a `RefAppender` with a given array reference. This does not copy the data. If the array has a larger capacity as determined by `arr.capacity`, it will be used by the appender.

Functions 45

fnForeachType!Range[] array(Range)(Range r) if (isIterable!Range && !isAutodecodableString!Range && !isInfinite!Range)Allocates an array and initializes it with copies of the elements of range `r`.
fnForeachType!(typeof((* Range).init))[] array(Range)(Range r) if (is(Range == U *, U) && isIterable!U && !isAutodecodableString!Range && !isInfinite!Range)ditto
fnCopyTypeQualifiers!(ElementType!String, dchar)[] array(String)(scope String str) if (isAutodecodableString!String)Convert a narrow autodecoding string to an array type that fully supports random access. This is handled as a special case and always returns an array of `dchar`
fnauto assocArray(Range)(Range r) if (isInputRange!Range)Returns a newly allocated associative array from a range of key/value tuples or from a range of keys and a range of values.
fnauto assocArray(Keys, Values)(Keys keys, Values values) if (isInputRange!Values && isInputRange!Keys)ditto
fnauto byPair(AA)(AA aa) if (isAssociativeArray!AA)Construct a range iterating over an associative array by key/value tuples.
fnauto uninitializedArray(T, I...)(I sizes) if (isDynamicArray!T && allSatisfy!(isIntegral, I) && hasIndirections!(ElementEncodingType!T)) nothrow @systemReturns a new array of type `T` allocated on the garbage collected heap without initializing its elements. This can be a useful optimization if every element will be immediately initialized. `T` ma...
fnauto uninitializedArray(T, I...)(I sizes) if (isDynamicArray!T && allSatisfy!(isIntegral, I) && !hasIndirections!(ElementEncodingType!T)) nothrow @trustedditto
fnauto minimallyInitializedArray(T, I...)(I sizes) if (isDynamicArray!T && allSatisfy!(isIntegral, I)) nothrow @trustedReturns a new array of type `T` allocated on the garbage collected heap.
private fnauto arrayAllocImpl(bool minimallyInitialized, T, I...)(I sizes) nothrow
fnCommonType!(T[], U[]) overlap(T, U)(T[] a, U[] b) if (is(typeof(a.ptr < b.ptr) == bool)) @trustedReturns the overlapping portion, if any, of two arrays. Unlike `equal`, `overlap` only compares the pointers and lengths in the ranges, not the values referred by them. If `r1` and `r2` have an ove...
private fnvoid copyBackwards(T)(T[] src, T[] dest)
fnvoid insertInPlace(T, U...)(ref T[] array, size_t pos, U stuff) if (!isSomeString!(T[]) && allSatisfy!(isInputRangeOrConvertible!T, U) && U.length > 0)Inserts `stuff` (which must be an input range or any number of implicitly convertible items) in `array` at position `pos`.
fnvoid insertInPlace(T, U...)(ref T[] array, size_t pos, U stuff) if (isSomeString!(T[]) && allSatisfy!(isCharOrStringOrDcharRange, U))Ditto
fnbool sameHead(T)(in T[] lhs, in T[] rhs) @safe pure nothrow @nogcReturns whether the `front`s of `lhs` and `rhs` both refer to the same place in memory, making one of the arrays a slice of the other which starts at index `0`.
fnbool sameTail(T)(in T[] lhs, in T[] rhs) @trusted pure nothrow @nogcReturns whether the `back`s of `lhs` and `rhs` both refer to the same place in memory, making one of the arrays a slice of the other which end at index `$`.
fnElementEncodingType!S[] replicate(S)(S s, size_t n) if (isDynamicArray!S)Params: s = an input range or a dynamic array n = number of times to repeat `s`
fnElementType!S[] replicate(S)(S s, size_t n) if (isInputRange!S && !isDynamicArray!S)ditto
fnS[] split(S)(S s) if (isSomeString!S) @safe pureEagerly splits `range` into an array, using `sep` as the delimiter.
fnauto split(Range, Separator)(Range range, Separator sep) if (isForwardRange!Range && ( is(typeof(ElementType!Range.init == Separator.init)) || is(typeof(ElementType!Range.init == ElementType!Separator.init)) && isForwardRange!Separator ))ditto
fnauto split(alias isTerminator, Range)(Range range) if (isForwardRange!Range && is(typeof(unaryFun!isTerminator(range.front))))ditto
fnElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, R sep) if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && isInputRange!R && (is(immutable ElementType!(ElementType!RoR) == immutable ElementType!R) || (isSomeChar!(ElementType!(ElementType!RoR)) && isSomeChar!(ElementType!R)) ))Eagerly concatenates all of the ranges in `ror` together (with the GC) into one array using `sep` as the separator if present.
fnElementEncodingType!(ElementType!RoR)[] join(RoR, E)(RoR ror, scope E sep) if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && ((is(E : ElementType!(ElementType!RoR))) || (!autodecodeStrings && isSomeChar!(ElementType!(ElementType!RoR)) && isSomeChar!E)))Ditto
fnElementEncodingType!(ElementType!RoR)[] join(RoR)(RoR ror) if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)))Ditto
fnE[] replace(E, R1, R2)(E[] subject, R1 from, R2 to) if ((isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2)) || is(Unqual!E : Unqual!R1))Replace occurrences of `from` with `to` in `subject` in a new array.
fnE[] replace(E, R1, R2)(E[] subject, R1 from, R2 to, ref size_t changed) if ((isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2)) || is(Unqual!E : Unqual!R1))Replace occurrences of `from` with `to` in `subject` in a new array. `changed` counts how many replacements took place.
fnvoid replaceInto(E, Sink, R1, R2)(Sink sink, E[] subject, R1 from, R2 to) if (isOutputRange!(Sink, E) && ((isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2)) || is(Unqual!E : Unqual!R1)))Replace occurrences of `from` with `to` in `subject` and output the result into `sink`.
fnvoid replaceInto(E, Sink, R1, R2)(Sink sink, E[] subject, R1 from, R2 to, ref size_t changed) if (isOutputRange!(Sink, E) && ((isForwardRange!R1 && isForwardRange!R2 && (hasLength!R2 || isSomeString!R2)) || is(Unqual!E : Unqual!R1)))Replace occurrences of `from` with `to` in `subject` and output the result into `sink`. `changed` counts how many replacements took place.
fnT[] replace(T, Range)(T[] subject, size_t from, size_t to, Range stuff) if (isInputRange!Range && (is(ElementType!Range : T) || isSomeString!(T[]) && is(ElementType!Range : dchar)))Replaces elements from `array` with indices ranging from `from` (inclusive) to `to` (exclusive) with the range `stuff`.
fnvoid replaceInPlace(T, Range)(ref T[] array, size_t from, size_t to, Range stuff) if (is(typeof(replace(array, from, to, stuff))))Replaces elements from `array` with indices ranging from `from` (inclusive) to `to` (exclusive) with the range `stuff`. Expands or shrinks the array as needed.
fnE[] replaceFirst(E, R1, R2)(E[] subject, R1 from, R2 to) if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(from[0 .. 1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(to[0 .. 1]))))Replaces the first occurrence of `from` with `to` in `subject`.
fnE[] replaceLast(E, R1, R2)(E[] subject, R1 from , R2 to) if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(from[0 .. 1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(to[0 .. 1]))))Replaces the last occurrence of `from` with `to` in `subject`.
fninout(T)[] replaceSlice(T)(inout(T)[] s, in T[] slice, in T[] replacement)Creates a new array such that the items in `slice` are replaced with the items in `replacement`. `slice` and `replacement` do not need to be the same length. The result will grow or shrink based on...
private fnsize_t appenderNewCapacity(size_t TSizeOf)(size_t curLen, size_t reqLen)
fnAppender!A appender(A)() if (isDynamicArray!A)Convenience function that returns an Appender instance, optionally initialized with `array`.
fnAppender!(E[]) appender(A : E[], E)(auto ref A array)ditto
fnRefAppender!(E[]) appender(P : E[] *, E)(P arrayPtr)Convenience function that returns a RefAppender instance initialized with `arrayPtr`. Don't use null for the array pointer, use the other version of `appender` instead.
fnT[n] staticArray(T, size_t n)(auto ref T[n] a)Constructs a static array from a dynamic array whose length is known at compile-time. The element type can be inferred or specified explicitly:
fnU[n] staticArray(U, T, size_t n)(auto ref T[n] a) if (!is(T == U) && is(T : U))ditto
fnauto staticArray(size_t n, T)(scope T a) if (isInputRange!T)Constructs a static array from a range. When `a.length` is not known at compile time, the number of elements must be given as a template argument (e.g. `myrange.staticArray!2`). Size and type can b...
fnauto staticArray(size_t n, T)(scope T a, out size_t rangeLength) if (isInputRange!T)ditto
fnauto staticArray(Un : U[n], U, size_t n, T)(scope T a) if (isInputRange!T && is(ElementType!T : U))ditto
fnauto staticArray(Un : U[n], U, size_t n, T)(scope T a, out size_t rangeLength) if (isInputRange!T && is(ElementType!T : U))ditto
fnauto staticArray(alias a)() if (isInputRange!(typeof(a)))ditto
fnauto staticArray(U, alias a)() if (isInputRange!(typeof(a)))ditto

Variables 1

private enumvarhasCheapIteration = isArray!R

Templates 5

tmplblockAttribute(T)
tmplnDimensions(T)
tmplisInputRangeWithLengthOrConvertible(E)
tmplisCharOrStringOrDcharRange(T)
tmplisInputRangeOrConvertible(E)