GeezerVison is showing dlang.org — std.container.array - D Programming Language
Library Reference
version 2.113.0
overview
Report a bug
If you spot a problem with this page, click here to create a GitHub 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
a local clone.
std.container.array
This module provides an Array type with deterministic memory usage not
reliant on the GC, as an alternative to the built-in arrays.
License: Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at boost.org/LICENSE_1_0.txt).
Examples: auto arr = Array!int(0, 2, 3);
writeln(arr[0]); // 0
writeln(arr.front); // 0
writeln(arr.back); // 3
// reserve space
arr.reserve(1000);
writeln(arr.length); // 3
assert(arr.capacity >= 1000);
// insertion
arr.insertBefore(arr[1..$], 1);
writeln(arr.front); // 0
writeln(arr.length); // 4
arr.insertBack(4);
writeln(arr.back); // 4
writeln(arr.length); // 5
// set elements
arr[1] *= 42;
writeln(arr[1]); // 42
Examples: import std.algorithm.comparison : equal;
auto arr = Array!int(1, 2, 3);
// concat
auto b = Array!int(11, 12, 13);
arr ~= b;
writeln(arr.length); // 6
// slicing
assert(arr[1 .. 3].equal([2, 3]));
// remove
arr.linearRemove(arr[1 .. 3]);
assert(arr[0 .. 2].equal([1, 11]));
Examples: Array!bool packs together values efficiently by allocating one bit per element
auto arr = Array!bool([true, true, false, true, false]);
writeln(arr.length); // 5
struct Array(T) if (!is(immutable(T) == immutable(bool)));
Array type with deterministic control of memory. The memory allocated
for the array is reclaimed as soon as possible; there is no reliance
on the garbage collector. Array uses malloc, realloc and free
for managing its own memory.
This means that pointers to elements of an Array will become
dangling as soon as the element is removed from the Array. On the other hand
the memory allocated by an Array will be scanned by the GC and
GC managed objects referenced from an Array will be kept alive.
Note
When using Array with range-based functions like those in std.algorithm,
Array must be sliced to get a range (for example, use array[].map!
instead of array.map!). The container itself is not a range. this (U)(U[] values...) if (isImplicitlyConvertible!(U, T));
this(T single);
Constructor taking a number of items.
this (Range)(Range r) if (isInputRange!Range && isImplicitlyConvertible!(ElementType!Range, T) && !is(Range == T[]));
-
bool opEquals(const Array rhs) const;
bool opEquals(ref const Array rhs) const;
Comparison for equality.
alias Range = RangeT!Array;
alias ConstRange = RangeT!(const(Array));
alias ImmutableRange = RangeT!(immutable(Array));
Defines the array's primary range, which is a random-access range.
ConstRange is a variant with const elements.
ImmutableRange is a variant with immutable elements.
Duplicates the array. The elements themselves are not transitively
duplicated.
@property bool empty() const;
Returns: true if and only if the array has no elements.
@property size_t length() const;
size_t opDollar() const;
Returns: The number of elements in the array.
@property size_t capacity();
Returns: The maximum number of elements the array can store without
reallocating memory and invalidating iterators upon insertion.
@system inout(T)[] data() inout;
Returns: the internal representation of the array.
void reserve(size_t elements);
Ensures sufficient capacity to accommodate e elements.
If e < capacity, this method does nothing.
Postcondition
capacity >= e
Note
If the capacity is increased, one should assume that all
iterators to the elements are invalidated.
Complexity
at most Ο(length) if e > capacity, otherwise Ο(1). Returns: A range that iterates over elements of the array in
forward order.
Range opSlice(size_t i, size_t j);
Returns: A range that iterates over elements of the array from
index i up to (excluding) index j.
Precondition
i <= j && j <= length
@property ref inout(T) front() inout;
Returns: The first element of the array.
Precondition
empty == false
@property ref inout(T) back() inout;
Returns: The last element of the array.
Precondition
empty == false
ref inout(T) opIndex(size_t i) inout;
Returns: The element or a reference to the element at the specified index.
void opSliceAssign(T value);
void opSliceAssign(T value, size_t i, size_t j);
void opSliceUnary(string op)() if (op == "++" || op == "--");
void opSliceUnary(string op)(size_t i, size_t j) if (op == "++" || op == "--");
void opSliceOpAssign(string op)(T value);
void opSliceOpAssign(string op)(T value, size_t i, size_t j);
Slicing operators executing the specified operation on the entire slice.
Precondition
i < j && j < length
Complexity
Ο(slice.length) Array opBinary(string op, Stuff)(Stuff stuff) if (op == "~");
Returns: A new array which is a concatenation of this and its argument.
Complexity
Ο(length + m), where m is the number of elements in stuff. void opOpAssign(string op, Stuff)(auto ref Stuff stuff) if (op == "~");
Forwards to insertBack.
Removes all the elements from the array and releases allocated memory.
Postcondition
empty == true && capacity == 0
@property void length(size_t newLength);
Sets the number of elements in the array to newLength. If newLength
is greater than length, the new elements are added to the end of the
array and initialized with T.init. If T is a struct whose default
constructor is annotated with @disable, newLength must be lower than
or equal to length.
Complexity
Guaranteed Ο(abs(length - newLength)) if capacity >= newLength.
If capacity < newLength the worst case is Ο(newLength).
Precondition
__traits(compiles, { static T _; }) || newLength <= length
Postcondition
length == newLength T removeAny();
alias stableRemoveAny = removeAny;
Removes the last element from the array and returns it.
Both stable and non-stable versions behave the same and guarantee
that ranges iterating over the array are never invalidated.
Precondition
empty == false
Returns: The element removed.
Throws: Exception if the array is empty.
size_t insertBack(Stuff)(Stuff stuff) if (isImplicitlyConvertible!(Stuff, T) || isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));
alias insert = insertBack;
Inserts the specified elements at the back of the array. stuff can be
a value convertible to T or a range of objects convertible to T.
Returns: The number of elements inserted.
Complexity
Ο(length + m) if reallocation takes place, otherwise Ο(m),
where m is the number of elements in stuff. void removeBack();
alias stableRemoveBack = removeBack;
Removes the value from the back of the array. Both stable and non-stable
versions behave the same and guarantee that ranges iterating over the
array are never invalidated.
Precondition
empty == false
Throws: Exception if the array is empty.
size_t removeBack(size_t howMany);
alias stableRemoveBack = removeBack;
Removes howMany values from the back of the array.
Unlike the unparameterized versions above, these functions
do not throw if they could not remove howMany elements. Instead,
if howMany > n, all elements are removed. The returned value is
the effective number of elements removed. Both stable and non-stable
versions behave the same and guarantee that ranges iterating over
the array are never invalidated.
Returns: The number of elements removed.
size_t insertBefore(Stuff)(Range r, Stuff stuff) if (isImplicitlyConvertible!(Stuff, T));
size_t insertBefore(Stuff)(Range r, Stuff stuff) if (isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));
alias stableInsertBefore = insertBefore;
size_t insertAfter(Stuff)(Range r, Stuff stuff) if (isImplicitlyConvertible!(Stuff, T) || isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));
size_t replace(Stuff)(Range r, Stuff stuff) if (isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));
size_t replace(Stuff)(Range r, Stuff stuff) if (isImplicitlyConvertible!(Stuff, T));
Inserts stuff before, after, or instead range r, which must
be a valid range previously extracted from this array. stuff
can be a value convertible to T or a range of objects convertible
to T. Both stable and non-stable version behave the same and
guarantee that ranges iterating over the array are never invalidated.
Returns: The number of values inserted.
Complexity
Ο(length + m), where m is the length of stuff.
Throws: Exception if r is not a range extracted from this array.
Range linearRemove(Range r);
Removes all elements belonging to r, which must be a range
obtained originally from this array.
Returns: A range spanning the remaining elements in the array that
initially were right after r.
Throws: Exception if r is not a valid range extracted from this array.
struct Array(T) if (is(immutable(T) == immutable(bool)));
Array specialized for bool. Packs together values efficiently by
allocating one bit per element.
Defines the array's primary range.
@property Range save();
@property bool empty();
@property T front();
@property void front(bool value);
T moveFront();
void popFront();
@property T back();
@property void back(bool value);
T moveBack();
void popBack();
T opIndex(size_t i);
void opIndexAssign(T value, size_t i);
T moveAt(size_t i);
@property size_t length() const;
Range opSlice(size_t low, size_t high);
Range primitives
this (U)(U[] values...) if (isImplicitlyConvertible!(U, T));
Constructor taking a number of items.
this (Range)(Range r) if (isInputRange!Range && isImplicitlyConvertible!(ElementType!Range, T) && !is(Range == T[]));
-
Property returning true if and only if the array has
no elements.
Returns: A duplicate of the array.
@property size_t length() const;
Returns the number of elements in the array.
@property size_t capacity();
Returns: The maximum number of elements the array can store without
reallocating memory and invalidating iterators upon insertion.
Ensures sufficient capacity to accommodate e elements.
If e < capacity, this method does nothing.
Postcondition
capacity >= e
Note
If the capacity is increased, one should assume that all
iterators to the elements are invalidated.
Complexity
at most Ο(length) if e > capacity, otherwise Ο(1). Returns: A range that iterates over all elements of the array in forward order.
Range opSlice(size_t a, size_t b);
Returns: A range that iterates the array between two specified positions.
@property bool front();
@property void front(bool value);
Returns: The first element of the array.
Precondition
empty == false
Throws: Exception if the array is empty.
@property bool back();
@property void back(bool value);
Returns: The last element of the array.
Precondition
empty == false
Throws: Exception if the array is empty.
bool opIndex(size_t i);
void opIndexAssign(bool value, size_t i);
void opIndexOpAssign(string op)(bool value, size_t i);
T moveAt(size_t i);
Indexing operators yielding or modifyng the value at the specified index.
Array!bool opBinary(string op, Stuff)(Stuff rhs) if (op == "~");
Returns: A new array which is a concatenation of this and its argument.
Complexity
Ο(length + m), where m is the number of elements in stuff. Array!bool opOpAssign(string op, Stuff)(Stuff stuff) if (op == "~");
Forwards to insertBack.
Removes all the elements from the array and releases allocated memory.
Postcondition
empty == true && capacity == 0
@property void length(size_t newLength);
Sets the number of elements in the array to newLength. If newLength
is greater than length, the new elements are added to the end of the
array and initialized with false.
Complexity
Guaranteed Ο(abs(length - newLength)) if capacity >= newLength.
If capacity < newLength the worst case is Ο(newLength).
Postcondition
length == newLength T removeAny();
alias stableRemoveAny = removeAny;
Removes the last element from the array and returns it.
Both stable and non-stable versions behave the same and guarantee
that ranges iterating over the array are never invalidated.
Precondition
empty == false
Returns: The element removed.
Throws: Exception if the array is empty.
size_t insertBack(Stuff)(Stuff stuff) if (is(Stuff : bool));
size_t insertBack(Stuff)(Stuff stuff) if (isInputRange!Stuff && is(ElementType!Stuff : bool));
alias stableInsertBack = insertBack;
alias insert = insertBack;
alias stableInsert = insertBack;
alias linearInsert = insertBack;
alias stableLinearInsert = insertBack;
Inserts the specified elements at the back of the array. stuff can be
a value convertible to bool or a range of objects convertible to bool.
Returns: The number of elements inserted.
Complexity
Ο(length + m) if reallocation takes place, otherwise Ο(m),
where m is the number of elements in stuff. void removeBack();
alias stableRemoveBack = removeBack;
Removes the value from the back of the array. Both stable and non-stable
versions behave the same and guarantee that ranges iterating over the
array are never invalidated.
Precondition
empty == false
Throws: Exception if the array is empty.
size_t removeBack(size_t howMany);
alias stableRemoveBack = removeBack;
Removes howMany values from the back of the array. Unlike the
unparameterized versions above, these functions do not throw if
they could not remove howMany elements. Instead, if howMany > n,
all elements are removed. The returned value is the effective number
of elements removed. Both stable and non-stable versions behave the same
and guarantee that ranges iterating over the array are never invalidated.
Returns: The number of elements removed.
size_t insertBefore(Stuff)(Range r, Stuff stuff);
alias stableInsertBefore = insertBefore;
size_t insertAfter(Stuff)(Range r, Stuff stuff) if (isImplicitlyConvertible!(Stuff, T) || isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));
alias stableInsertAfter = insertAfter;
size_t replace(Stuff)(Range r, Stuff stuff) if (is(Stuff : bool));
alias stableReplace = replace;
Inserts stuff before, after, or instead range r, which must
be a valid range previously extracted from this array. stuff
can be a value convertible to bool or a range of objects convertible
to bool. Both stable and non-stable version behave the same and
guarantee that ranges iterating over the array are never invalidated.
Returns: The number of values inserted.
Complexity
Ο(length + m), where m is the length of stuff. Range linearRemove(Range r);
Removes all elements belonging to r, which must be a range
obtained originally from this array.
Returns: A range spanning the remaining elements in the array that
initially were right after r.
|
