Report a bug
If you spot a problem with this page, click here to create a Bugzilla 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.
rt.array.capacity
This module contains support for controlling dynamic arrays' capacity
License:
Distributed under the
Boost Software License 1.0.
(See accompanying file LICENSE)
Source rt/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_tnewcapacity
); - 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); }
Copyright © 1999-2019 by the D Language Foundation | Page generated by
Ddoc on Thu Jun 27 02:24:39 2019