Arrays

You already have array<T> on the collections page. Methods live there: push, pop, count. arr:: is the few operations that do not belong on one array, because they answer a question about arrays rather than about a single value. stable_array<T> is a different type and is not in this namespace.

array<int32> $inbound = [1, 2];
array<int32> $outbound = [3];

array<int32> $all = arr::merge($inbound, $outbound);
echo $all->count();     // 3
echo $all->get(2);      // 3

merge

merge takes two arrays and gives you a third. It's a free function rather than a method because it touches a property of neither argument: both come in as const array<T>&, nothing is consumed, and nothing is changed.

array<string> $gates = ["Abydos"];
array<string> $more = ["Chulak", "Dakara"];

array<string> $network = arr::merge($gates, $more);
echo $network->count();     // 3
echo $network->get(1);      // Chulak

The elements are copied by the ordinary rules, so an element type whose copy needs a constructor needs one here too. See Copying. It allocates once for the result and no more, so merging two large arrays doesn't thrash.

room

array<int32> $chevrons = arr::room<int32>(7);

echo $chevrons->count();        // 0, it is empty
echo $chevrons->capacity();     // 7, and it will not reallocate until the eighth

$chevrons[] = 1;
echo $chevrons->count();        // 1

array<int32>(7) would have been the obvious spelling and it's the wrong one. Anybody who has met vec![0; 5] reads that as seven elements, not room for seven. Constructors can't be named, so the way to disambiguate is to stop using one. Reach for this whenever you know the final size, which is most of the time you're filling an array in a loop.

$a->room() is a different question: how much of that capacity is still spare. Arrays is where spare / commit live.

extend_from

array<int32> $dialed = [5, 8, 13, 21];
array<int32> $log = [1, 2];

arr::extend_from($log, $dialed->data(), 3);

echo $log->count();     // 5
echo $log->get(4);      // 13

It's extend for a pointer and a count: C hands you those, and a long integer array literal is filled this way in one copy rather than one append per element.

The result matches appending one at a time, capacity() included. Bytes copy in one go; anything else copies element by element, so a string keeps its retain.

The pointer is your promise: $count live elements, and not into the array you are growing.

Surface

Signature	What it does
arr::merge<T>(const array<T>& $a, const array<T>& $b) : array<T>	a new array, $a's elements then $b's
arr::room<T>(usize $count) : array<T>	an empty array with room for $count
arr::extend_from<T>(array<T>& $into, ptr<const T> $src, usize $count) : void	appends $count elements read from $src

Next

• Arrays for array<T> itself, which is where the real surface is.
• String functions for str::from, split, join and the rest of str::.