www.digitalmars.com

D Programming Language 2.0

Last update Thu Sep 16 11:25:55 2010

std.array

License:
Boost License 1.0.

Authors:
Andrei Alexandrescu

Copyright Andrei Alexandrescu 2008 - 2009. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at

http:
//www.boost.org/LICENSE_1_0.txt)

ForeachType!(Range)[] array(Range)(Range r);
Returns a newly-allocated dynamic array consisting of a copy of the input range, static array, dynamic array, or class or struct with an opApply function r. Note that narrow strings are handled as a special case in an overload.

Example:
auto a = array([1, 2, 3, 4, 5][]);
assert(a == [ 1, 2, 3, 4, 5 ]);

ElementType!(String)[] array(String)(String str);
Convert a narrow string to an array type that fully supports random access. This is handled as a special case and always returns a dchar[], const(dchar)[], or immutable(dchar)[] depending on the constness of the input.

bool empty(T)(in T[] a);
Implements the range interface primitive empty for built-in arrays. Due to the fact that nonmember functions can be called with the first argument using the dot notation, array.empty is equivalent to empty(array).

Example:
void main()
{
    auto a = [ 1, 2, 3 ];
    assert(!a.empty);
    assert(a[3 .. $].empty);
}

T[] save(T)(T[] 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.save is equivalent to save(array).

Example:
void main()
{
    auto a = [ 1, 2, 3 ];
    auto b = a.save;
    assert(b is a);
}

void popFront(T)(ref T[] 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.popFront is equivalent to popFront(array).

Example:
void main()
{
    int[] a = [ 1, 2, 3 ];
    a.popFront;
    assert(a == [ 2, 3 ]);
}

void popBack(T)(ref T[] 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.popBack is equivalent to popBack(array).

Example:
void main()
{
    int[] a = [ 1, 2, 3 ];
    a.popBack;
    assert(a == [ 1, 2 ]);
}

typeof(A[0]) front(A)(A a);
void front(T)(T[] a, T v);
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.front is equivalent to front(array).

Example:
void main()
{
    int[] a = [ 1, 2, 3 ];
    assert(a.front == 1);
}

typeof(A.init[0]) back(A)(A 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.back is equivalent to back(array).

Example:
void main()
{
    int[] a = [ 1, 2, 3 ];
    assert(a.back == 3);
}

void insert(T, Range)(ref T[] array, size_t pos, Range stuff);
Inserts stuff in container at position pos.

void replace(T, Range)(ref T[] array, size_t from, size_t to, Range stuff);
Erases elements from array with indices ranging from from (inclusive) to to (exclusive).

Erases element from array at index from.

Replaces elements from array with indices ranging from from (inclusive) to to (exclusive) with the range stuff. Expands or shrinks the array as needed.

struct Appender(A : T[],T);
Implements an output range that appends data to an array. This is recommended over a ~= data when appending many elements because it is more efficient.

Example:
auto app = appender!string();
string b = "abcdefg";
foreach (char c; b) app.put(c);
assert(app.data == "abcdefg");

int[] a = [ 1, 2 ];
auto app2 = appender(a);
app2.put(3);
app2.put([ 4, 5, 6 ]);
assert(app2.data == [ 1, 2, 3, 4, 5, 6 ]);

this(T[] arr);
Construct 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 initializing an appender on an array, appending to the original array will reallocate.

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();
Returns 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.

T[] data();
Returns the managed array.

template put(U) if (isImplicitlyConvertible!(U,T) || isSomeChar!(T) && isSomeChar!(U))
Appends one item to the managed array.

void put(U item);
Appends one item to the managed array.

template put(Range) if (isInputRange!(Range) && is(typeof(Appender.init.put(items.front))))
Appends an entire range to the managed array.

void put(Range items);
Appends an entire range to the managed array.

void clear();
Clears the managed array.

void shrinkTo(size_t newlength);
Shrinks the managed array to the given length. Passing in a length that's greater than the current array length throws an enforce exception.

struct RefAppender(A : T[],T);
An 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.

this(T[]* arr);
Construct a ref appender 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. RefAppender assumes that arr is a non-null value.

Note, do not use builtin appending (i.e. ~=) on the original array passed in until you are done with the appender, because calls to the appender override those appends.

size_t capacity();
Returns 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.

T[] data();
Returns the managed array.

Appender!(E[]) appender(A : E[], E)(A array = null);
Convenience function that returns an Appender!(A) object initialized with array.

RefAppender!(E[]) appender(A : E[]*, E)(A array);
Convenience function that returns a RefAppender!(A) object initialized with array. Don't use null for the array pointer, use the other version of appender instead.