Function RegionAllocator.array

Copies range to an array. The array will be located on the RegionAllocator stack if any of the following conditions apply:

Unqual!(ElementType!R)[] array(R) (
  R range
)
if (isInputRange!R);

1. std.traits.hasIndirections!(ElementType!R) is false.

2. R is a builtin array. In this case range maintains pointers to all elements at least until array returns, preventing the elements from being freed by the garbage collector. A similar assumption cannot be made for ranges other than builtin arrays.

3. The RegionAllocatorStack instance used by this RegionAllocator is scanned by the garbage collector.

If none of these conditions is met, the array is returned on the C heap and GC.addRange is called. In either case, RegionAllocator.free, RegionAllocator.freeLast, or the last copy of this RegionAllocator instance going out of scope will free the array as if it had been allocated on the RegionAllocator stack.

Rationale

The most common reason to call array on a builtin array is to modify its contents inside a function without affecting the caller's view. In this case range is not modified and prevents the elements from being freed by the garbage collector. Furthermore, if the copy returned does need to be scanned, the client can call GC.addRange before modifying the original array.

Examples

auto alloc = newRegionAllocator();
auto arr = alloc.array(iota(5));
assert(arr == [0, 1, 2, 3, 4]);