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:


Function Name	Description
array	Returns a copy of the input in a newly allocated dynamic array.
appender	Returns a new Appender or RefAppender initialized with a given array.
assocArray	Returns a newly allocated associative array from a range of key/value tuples.
byPair	Construct a range iterating over an associative array by key/value tuples.
insertInPlace	Inserts into an existing array at a given position.
join	Concatenates a range of ranges into one array.
minimallyInitializedArray	Returns a new array of type `T`.
replace	Returns a new array with all occurrences of a certain subrange replaced.
replaceFirst	Returns a new array with the first occurrence of a certain subrange replaced.
replaceInPlace	Replaces all occurrences of a certain subrange and puts the result into a given array.
replaceInto	Replaces all occurrences of a certain subrange and puts the result into an output range.
replaceLast	Returns a new array with the last occurrence of a certain subrange replaced.
replaceSlice	Returns a new array with a given slice replaced.
replicate	Creates a new array out of several copies of an input array or range.
sameHead	Checks if the initial segments of two arrays refer to the same place in memory.
sameTail	Checks if the final segments of two arrays refer to the same place in memory.
split	Eagerly split a range or string into an array.
staticArray	Creates a new static array from given data.
uninitializedArray	Returns a new array of type `T` without initializing its elements.

Copyright

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

`A`	the array type to simulate.

Parameters

`A`	The 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`.

ForeachType!(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.

auto 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...

auto 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)

void 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`.

void 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.

auto 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

auto split(alias  isTerminator,  Range)(Range range) if (isForwardRange!Range &&  is(typeof(unaryFun!isTerminator(range.front))))

ditto

ElementEncodingType!(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.

ElementEncodingType!(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

ElementEncodingType!(ElementType!RoR)[] join(RoR)(RoR ror) if (isInputRange!RoR &&
     isInputRange!(Unqual!(ElementType!RoR)))

Ditto

E[] 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.

E[] 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.

void 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`.

void 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.

T[] 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`.

void 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.

E[] 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`.

E[] 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

auto 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)

std.array

Copyright

License

Authors

Types 2

Parameters

See Also

Parameters

Functions 45

Variables 1

Templates 5