core.internal.array.capacity

This module contains support for controlling dynamic arrays' capacity and length

License:

Distributed under the Boost Software License 1.0. (See accompanying file LICENSE)

Source

core/internal/array/capacity.d

pure nothrow @property @trusted size_t capacity(T)(T[] arr);

(Property) Gets the current capacity of a slice. The capacity is the size that the slice can grow to before the underlying array must be reallocated or extended.

If an append must reallocate a slice with no possibility of extension, then 0 is returned. This happens when the slice references a static array, or if another slice references elements past the end of the current slice.

Note

The capacity of a slice may be impacted by operations on other slices.

Examples:

//Static array slice: no capacity
int[4] sarray = [1, 2, 3, 4];
int[]  slice  = sarray[];
assert(sarray.capacity == 0);
//Appending to slice will reallocate to a new array
slice ~= 5;
assert(slice.capacity >= 5);

//Dynamic array slices
int[] a = [1, 2, 3, 4];
int[] b = a[1 .. $];
int[] c = a[1 .. $ - 1];
debug(SENTINEL) {} else // non-zero capacity very much depends on the array and GC implementation
{
    assert(a.capacity != 0);
    assert(a.capacity == b.capacity + 1); //both a and b share the same tail
}
assert(c.capacity == 0);              //an append to c must relocate c.

pure nothrow @trusted size_t reserve(T)(ref T[] arr, size_t newcapacity);

Reserves capacity for a slice. The capacity is the size that the slice can grow to before the underlying array must be reallocated or extended.

Returns:

The new capacity of the array (which may be larger than the requested capacity).

Examples:

//Static array slice: no capacity. Reserve relocates.
int[4] sarray = [1, 2, 3, 4];
int[]  slice  = sarray[];
auto u = slice.reserve(8);
assert(u >= 8);
assert(&sarray[0] !is &slice[0]);
assert(slice.capacity == u);

//Dynamic array slices
int[] a = [1, 2, 3, 4];
a.reserve(8); //prepare a for appending 4 more items
auto p = &a[0];
u = a.capacity;
a ~= [5, 6, 7, 8];
assert(p == &a[0]);      //a should not have been reallocated
assert(u == a.capacity); //a should not have been extended

nothrow ref @system inout(T[]) assumeSafeAppend(T)(auto ref inout(T[]) arr);

Assume that it is safe to append to this array. Appends made to this array after calling this function may append in place, even if the array was a slice of a larger array to begin with.

Use this only when it is certain there are no elements in use beyond the array in the memory block. If there are, those elements will be overwritten by appending to this array.

Warning

Calling this function, and then using references to data located after the given array results in undefined behavior.

Returns:

The input is returned.

Examples:

int[] a = [1, 2, 3, 4];

// Without assumeSafeAppend. Appending relocates.
int[] b = a [0 .. 3];
b ~= 5;
assert(a.ptr != b.ptr);

debug(SENTINEL) {} else
{
    // With assumeSafeAppend. Appending overwrites.
    int[] c = a [0 .. 3];
    c.assumeSafeAppend() ~= 5;
    assert(a.ptr == c.ptr);
}

template _d_arraysetlengthTImpl(Tarr : T[], T)

Implementation of _d_arraysetlengthT and _d_arraysetlengthTTrace

pure nothrow @trusted size_t _d_arraysetlengthT(return ref scope Tarr arr, size_t newlength);

Resize dynamic array

Parameters:

Tarr arr	the array that will be resized, taken as a reference
size_t newlength	new length of array

Returns:

The new length of the array

Bugs:

The safety level of this function is faked. It shows itself as @trusted pure nothrow to not break existing code.

alias _d_arraysetlengthTTrace = _d_HookTraceImpl!(Tarr, _d_arraysetlengthT, errorMessage);

TraceGC wrapper around core.internal.array.core.internal.array.capacity.d_arraysetlengthT.

Bugs:

This function template was ported from a much older runtime hook that bypassed safety, purity, and throwabilty checks. To prevent breaking existing code, this function template is temporarily declared @trusted pure nothrow until the implementation can be brought up to modern D expectations.