stdx.collections.array

struct Array(T);

this(A, this Q)(A allocator)
if (!is(Q == shared) && (is(A == RCISharedAllocator) || !is(Q == immutable)) && (is(A == RCIAllocator) || is(A == RCISharedAllocator)));

Constructs a qualified array that will use the provided allocator object. For immutable objects, a RCISharedAllocator must be supplied.

Parameters:

A allocator

a allocator.html#.RCIAllocator">std.experimental.allocator.RCIAllocator or allocator.html#.RCISharedAllocator">std.experimental.allocator.RCISharedAllocator allocator object

Complexity Ο(1)

Examples:

import std.experimental.allocator : theAllocator, processAllocator;

auto a = Array!int(theAllocator);
auto ca = const Array!int(processAllocator);
auto ia = immutable Array!int(processAllocator);

this(U, this Q)(U[] values...)
if (isImplicitlyConvertible!(U, T));

Constructs a qualified array out of a number of items. Because no allocator was provided, the array will use the GCAllocator.std.experimental.allocator.gc_allocator.

Parameters:

U[] values

a variable number of items, either in the form of a list or as a built-in array

Complexity Ο(m), where m is the number of items.

Examples:

import std.algorithm.comparison : equal;

// Create a list from a list of ints
{
    auto a = Array!int(1, 2, 3);
    assert(equal(a, [1, 2, 3]));
}
// Create a list from an array of ints
{
    auto a = Array!int([1, 2, 3]);
    assert(equal(a, [1, 2, 3]));
}
// Create a list from a list from an input range
{
    auto a = Array!int(1, 2, 3);
    auto a2 = Array!int(a);
    assert(equal(a2, [1, 2, 3]));
}

this(A, U, this Q)(A allocator, U[] values...)
if (!is(Q == shared) && (is(A == RCISharedAllocator) || !is(Q == immutable)) && (is(A == RCIAllocator) || is(A == RCISharedAllocator)) && isImplicitlyConvertible!(U, T));

Constructs a qualified array out of a number of items that will use the provided allocator object. For immutable objects, a RCISharedAllocator must be supplied.

Parameters:

A allocator	a allocator.html#.RCIAllocator">std.experimental.allocator.RCIAllocator or allocator.html#.RCISharedAllocator">std.experimental.allocator.RCISharedAllocator allocator object
U[] values	a variable number of items, either in the form of a list or as a built-in array

Complexity Ο(m), where m is the number of items.

this(Stuff, this Q)(Stuff stuff)
if (isInputRange!Stuff && !isInfinite!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T) && !is(Stuff == T[]));

Constructs a qualified array out of an input range. Because no allocator was provided, the array will use the GCAllocator.std.experimental.allocator.gc_allocator. If Stuff defines length, Array will use it to reserve the necessary amount of memory.

Parameters:

Stuff stuff

an input range of elements that are implitictly convertible to T

Complexity Ο(m), where m is the number of elements in the range.

this(A, Stuff, this Q)(A allocator, Stuff stuff)
if (!is(Q == shared) && (is(A == RCISharedAllocator) || !is(Q == immutable)) && (is(A == RCIAllocator) || is(A == RCISharedAllocator)) && isInputRange!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T) && !is(Stuff == T[]));

Constructs a qualified array out of an input range that will use the provided allocator object. For immutable objects, a RCISharedAllocator must be supplied. If Stuff defines length, Array will use it to reserve the necessary amount of memory.

Parameters:

A allocator	a allocator.html#.RCIAllocator">std.experimental.allocator.RCIAllocator or allocator.html#.RCISharedAllocator">std.experimental.allocator.RCISharedAllocator allocator object
Stuff stuff	an input range of elements that are implitictly convertible to T

Complexity Ο(m), where m is the number of elements in the range.

const pure nothrow @nogc @safe size_t length();

alias opDollar = length;

Return the number of elements in the array..

Returns:

the length of the array.

Complexity Ο(1).

Examples:

auto a = Array!int(1, 2, 3);
assert(a.length == 3);
assert(a[$ - 1] == 3);

pure nothrow @nogc @trusted void forceLength(size_t len);

Set the length of the array to len. len must be less than or equal to the capacity of the array.

Parameters:

size_t len

a positive integer

Complexity Ο(1).

const pure nothrow @nogc @safe size_t capacity();

Get the available capacity of the array; this is equal to length of the array plus the available pre-allocated, free, space.

Returns:

a positive integer denoting the capacity.

Complexity Ο(1).

void reserve(size_t n);

Reserve enough memory from the allocator to store n elements. If the current capacity exceeds n nothing will happen. If n exceeds the current capacity, an attempt to expand the current array is made. If expand is successful, all the expanded elements are default initialized to T.init. If the expand fails a new buffer will be allocated, the old elements of the array will be copied and the new elements will be default initialized to T.init.

Parameters:

size_t n

a positive integer

Complexity Ο(max(length, n)).

Examples:

import std.algorithm.comparison : equal;

auto stuff = [1, 2, 3];
Array!int a;
a.reserve(stuff.length);
a ~= stuff;
assert(equal(a, stuff));

size_t insert(Stuff)(size_t pos, Stuff stuff)
if (!isArray!(typeof(stuff)) && isInputRange!Stuff && !isInfinite!Stuff && isImplicitlyConvertible!(ElementType!Stuff, T));

size_t insert(Stuff)(size_t pos, Stuff[] stuff...)
if (isImplicitlyConvertible!(Stuff, T));

Inserts the elements of an input range, or a variable number of items, at the given pos.

If no allocator was provided when the array was created, the GCAllocator.std.experimental.allocator.gc_allocator will be used. If Stuff defines length, Array will use it to reserve the necessary amount of memory.

Parameters:

size_t pos	a positive integer
Stuff stuff	an input range of elements that are implitictly convertible to T; a variable number of items either in the form of a list or as a built-in array

Returns:

the number of elements inserted

Complexity Ο(max(length, pos + m)), where m is the number of elements in the range.

Examples:

import std.algorithm.comparison : equal;

Array!int a;
assert(a.empty);

size_t pos = 0;
pos += a.insert(pos, 1);
pos += a.insert(pos, [2, 3]);
assert(equal(a, [1, 2, 3]));

pure nothrow @nogc @safe bool isUnique(this _)();

Check whether there are no more references to this array instance.

Returns:

true if this is the only reference to this array instance; false otherwise.

Complexity Ο(1).

Examples:

auto a = Array!int(24, 42);
assert(a.isUnique);
{
    auto a2 = a;
    assert(!a.isUnique);
    a2.front = 0;
    assert(a.front == 0);
} // a2 goes out of scope
assert(a.isUnique);

const pure nothrow @nogc @safe bool empty();

Check if the array is empty.

Returns:

true if there are no elements in the array; false otherwise.

Complexity Ο(1).

Examples:

Array!int a;
assert(a.empty);
size_t pos = 0;
a.insert(pos, 1);
assert(!a.empty);

ref auto front(this _)();

Provide access to the first element in the array. The user must check that the array isn't empty, prior to calling this function.

Returns:

a reference to the first element.

Complexity Ο(1).

Examples:

auto a = Array!int(1, 2, 3);
assert(a.front == 1);
a.front = 0;
assert(a.front == 0);

pure nothrow @nogc @safe void popFront();

Advance to the next element in the array. The user must check that the array isn't empty, prior to calling this function.

Complexity Ο(1).

Examples:

auto stuff = [1, 2, 3];
auto a = Array!int(stuff);
size_t i = 0;
while (!a.empty)
{
    assert(a.front == stuff[i++]);
    a.popFront;
}
assert(a.empty);

Qualified tail(this Qualified)();

Advance to the next element in the array. The user must check that the array isn't empty, prior to calling this function.

This must be used in order to iterate through a const or immutable array For a mutable array this is equivalent to calling popFront.

Returns:

an array that starts with the next element in the original array.

Complexity Ο(1).

Examples:

auto ia = immutable Array!int([1, 2, 3]);
assert(ia.tail.front == 2);

template each(alias fun)

Eagerly iterate over each element in the array and call fun over each element. This should be used to iterate through const and immutable arrays.

Normally, the entire array is iterated. If partial iteration (early stopping) is desired, fun needs to return a value of type std.typecons.Flag!"each" (Yes.each to continue iteration, or No.each to stop).

Parameters:

fun	unary function to apply on each element of the array.

Returns:

Yes.each if it has iterated through all the elements in the array, or No.each otherwise.

Complexity Ο(n).

Examples:

import std.typecons : Flag, Yes, No;

auto ia = immutable Array!int([1, 2, 3]);

static bool foo(int x) { return x > 0; }
static Flag!"each" bar(int x) { return x > 1 ? Yes.each : No.each; }

assert(ia.each!foo == Yes.each);
assert(ia.each!bar == No.each);

ref auto save(this _)();

Perform a shallow copy of the array.

Returns:

a new reference to the current array.

Complexity Ο(1).

Examples:

auto stuff = [1, 2, 3];
auto a = Array!int(stuff);
size_t i = 0;

auto tmp = a.save;
while (!tmp.empty)
{
    assert(tmp.front == stuff[i++]);
    tmp.popFront;
}
assert(tmp.empty);
assert(!a.empty);

Array!T dup(this Q)();

Perform a copy of the array. This will create a new array that will copy the elements of the current array. This will NOT call dup on the elements of the array, regardless if T defines it or not.

Returns:

a new mutable array.

Complexity Ο(n).

Examples:

import std.algorithm.comparison : equal;

auto stuff = [1, 2, 3];
auto a = immutable Array!int(stuff);
auto aDup = a.dup;
assert(equal(aDup, stuff));
aDup.front = 0;
assert(aDup.front == 0);
assert(a.front == 1);

Qualified opSlice(this Qualified)();

Return a slice to the current array. This is equivalent to calling save.

Returns:

an array that references the current array.

Complexity Ο(1)

Qualified opSlice(this Qualified)(size_t start, size_t end);

Return a slice to the current array that is bounded by start and end. start must be less than or equal to end and end must be less than or equal to length.

Returns:

an array that references the current array.

Parameters:

size_t start	a positive integer
size_t end	a positive integer

Complexity Ο(1)

Examples:

import std.algorithm.comparison : equal;

auto stuff = [1, 2, 3];
auto a = Array!int(stuff);
assert(equal(a[], stuff));
assert(equal(a[1 .. $], stuff[1 .. $]));

ref auto opIndex(this _)(size_t idx);

Provide access to the element at idx in the array. idx must be less than length.

Returns:

a reference to the element found at idx.

Parameters:

size_t idx

a positive integer

Complexity Ο(1).

Examples:

auto a = Array!int([1, 2, 3]);
assert(a[2] == 3);

ref auto opIndexUnary(string op)(size_t idx);

Apply an unary operation to the element at idx in the array. idx must be less than length.

Returns:

a reference to the element found at idx.

Parameters:

size_t idx

a positive integer

Complexity Ο(1).

Examples:

auto a = Array!int([1, 2, 3]);
int x = --a[2];
assert(a[2] == 2);
assert(x == 2);

ref auto opIndexAssign(U)(U elem, size_t idx)
if (isImplicitlyConvertible!(U, T));

Assign elem to the element at idx in the array. idx must be less than length.

Returns:

a reference to the element found at idx.

Parameters:

U elem	an element that is implicitly convertible to T
size_t idx	a positive integer

Complexity Ο(1).

Examples:

auto a = Array!int([1, 2, 3]);
a[2] = 2;
assert(a[2] == 2);
(a[2] = 3)++;
assert(a[2] == 4);

ref auto opIndexOpAssign(string op, U)(U elem, size_t idx)
if (isImplicitlyConvertible!(U, T));

Assign to the element at idx in the array the result of a[idx] op elem. idx must be less than length.

Returns:

a reference to the element found at idx.

Parameters:

U elem	an element that is implicitly convertible to T
size_t idx	a positive integer

Complexity Ο(1).

Examples:

auto a = Array!int([1, 2, 3]);
a[2] += 2;
assert(a[2] == 5);
(a[2] += 3)++;
assert(a[2] == 9);

ref auto opBinary(string op, U)(auto ref U rhs)
if (op == "~" && (is(U : const(typeof(this))) || is(U : T) || isInputRange!U && isImplicitlyConvertible!(ElementType!U, T)));

Create a new array that results from the concatenation of this array with rhs.

Parameters:

U rhs

can be an element that is implicitly convertible to T, an input range of such elements, or another Array

Returns:

the newly created array

Complexity Ο(n + m), where m is the number of elements in rhs.

Examples:

import std.algorithm.comparison : equal;

auto a = Array!int(1);
auto a2 = a ~ 2;

assert(equal(a2, [1, 2]));
a.front = 0;
assert(equal(a2, [1, 2]));

ref auto opAssign()(auto ref typeof(this) rhs);

Assign rhs to this array. The current array will now become another reference to rhs, unless rhs is null, in which case the current array will become empty. If rhs refers to the current array nothing will happen.

If there are no more references to the previous array, the previous array will be destroyed; this leads to a Ο(n) complexity.

Parameters:

typeof(this) rhs

a reference to an array

Returns:

a reference to this array

Complexity Ο(n).

Examples:

import std.algorithm.comparison : equal;

auto a = Array!int(1);
auto a2 = Array!int(1, 2);

a = a2; // this will free the old a
assert(equal(a, [1, 2]));
a.front = 0;
assert(equal(a2, [0, 2]));

ref auto opOpAssign(string op, U)(auto ref U rhs)
if (op == "~" && (is(U == typeof(this)) || is(U : T) || isInputRange!U && isImplicitlyConvertible!(ElementType!U, T)));

Append the elements of rhs at the end of the array.

If no allocator was provided when the list was created, the GCAllocator.std.experimental.allocator.gc_allocator will be used.

Parameters:

U rhs

can be an element that is implicitly convertible to T, an input range of such elements, or another Array

Returns:

a reference to this array

Complexity Ο(n + m), where m is the number of elements in rhs.

Examples:

import std.algorithm.comparison : equal;

Array!int a;
auto a2 = Array!int(4, 5);
assert(a.empty);

a ~= 1;
a ~= [2, 3];
assert(equal(a, [1, 2, 3]));

// append an input range
a ~= a2;
assert(equal(a, [1, 2, 3, 4, 5]));
a2.front = 0;
assert(equal(a, [1, 2, 3, 4, 5]));