Menu

Reference

Reference / Manticore\Ds

TypedArray

abstractclass
abstract class TypedArray<T> implements \ArrayAccess, \Countable, \IteratorAggregate, \JsonSerializable

The base of every fixed-width array: a resizable, contiguous run of numbers (or bits) stored at their declared width.

Where a PHP array or SplFixedArray boxes every element, a typed array stores the elements unboxed, back to back: Int8Array takes one byte per element, Float64Array eight, BitArray one bit. Indexes are the positions 0..count-1, and access follows SplFixedArray: an index outside that range throws OutOfBoundsException, an integer-like string or a float or bool index is cast to int, anything else is a TypeError. Unlike SplFixedArray the size can change with setSize(), push(), pop(), insert() and remove().

Nothing wraps or truncates silently. Storing a value that does not fit the element type throws ValueError (out of range) or TypeError (wrong kind of value); the exact rules are on {@see IntTypedArray}, {@see FloatTypedArray} and {@see BitArray}. Unset elements do not exist: a fresh array, and every element added by growing it, holds 0 (0.0, false).

An array is an object: assignment copies the handle, clone copies the elements. It implements ArrayAccess, Countable, IteratorAggregate (yielding index => value) and JsonSerializable (a JSON list); it also serializes as a list of its elements. Two arrays are compared with {@see equals()}, not ==.

T is the type an element is read as: the scalar itself, or a #[TypeDef] class over it (UInt16Array<TokenKind>).

Methods

__construct()Creates an array of $size elements, all zero (0, 0.0 or false).
__clone()Makes the clone an independent array holding the same elements.
fromArray()Builds an array from the values of $values; the keys are ignored.
toArray()Copies the elements into a PHP list.
count()Returns the number of elements.
getSize()Returns the number of elements (the SplFixedArray spelling of count()).
setSize()Resizes the array to $size elements.
push()Appends $value; $a[] = $value is the same.
pop()Removes and returns the last element.
insert()Opens $count elements holding $value before position $at.
remove()Removes $count elements from position $at; the tail moves down.
fill()Stores $value into the positions $from up to (not including) $to.
copyFrom()Copies $count elements of $src starting at $srcAt to this array starting at $dstAt.
apply()Replaces each element with $f($element, $index), in place.
equals()Whether $other is the same class of array with the same elements.
indexOf()First position >= $from holding $value, or -1.
offsetExists()Tells whether $offset names an element: isset($a[$offset]).
offsetSet()Stores $value at $offset: $a[$offset] = $value; $a[] = $value appends.
offsetUnset()Zeroes the element: a fixed-width slot cannot be absent.
getIterator()Iterates the elements by index, yielding index => element.
jsonSerialize()Encodes as a JSON array of the elements.

__construct()#source

function __construct(int $size = 0)

Creates an array of $size elements, all zero (0, 0.0 or false).

Parameters

$size int = 0
the initial number of elements

Throws

\ValueError
when $size is negative

__clone()#source

function __clone()

Makes the clone an independent array holding the same elements.

fromArray()#source

static function fromArray(array $values): static

Builds an array from the values of $values; the keys are ignored.

Each value is checked like an element assignment ($a[$i] = $v).

Parameters

$values array<int|string, mixed>
the source values

Returns

static — a new array of count($values) elements, in array order

Throws

\ValueError
when a value is out of range for the element type
\TypeError
when a value is of the wrong kind

toArray()#source

function toArray(): array

Copies the elements into a PHP list.

Returns

array<int, mixed> — the elements in index order

count()#source

function count(): int

Returns the number of elements.

Returns

int — the element count

getSize()#source

function getSize(): int

Returns the number of elements (the SplFixedArray spelling of count()).

Returns

int — the element count

setSize()#source

function setSize(int $size): void

Resizes the array to $size elements.

Growing appends zero elements; shrinking drops the tail.

Parameters

$size int
the new number of elements

Throws

\ValueError
when $size is negative

push()#source

function push(mixed $value): void

Appends $value; $a[] = $value is the same. Amortised O(1).

Parameters

$value mixed
the element to append

Throws

\ValueError
when the value is out of range for the element type
\TypeError
when the value is of the wrong kind

pop()#source

function pop(): mixed

Removes and returns the last element.

Returns

T — the removed element

Throws

\UnderflowException
when the array is empty

insert()#source

function insert(int $at, int $count, mixed $value = 0): void

Opens $count elements holding $value before position $at.

The elements from $at on move up. $at may equal the size, which appends. O(n) in the number of elements moved.

Parameters

$at int
the position to insert before, 0..count
$count int
how many elements to insert
$value mixed = 0
the value of every inserted element (default 0)

Throws

\ValueError
when $count is negative, or $value is out of range
\OutOfBoundsException
when $at is outside 0..count
\TypeError
when $value is of the wrong kind

remove()#source

function remove(int $at, int $count): void

Removes $count elements from position $at; the tail moves down.

Parameters

$at int
the first position to remove
$count int
how many elements to remove

Throws

\ValueError
when $count is negative
\OutOfBoundsException
when $at..$at+$count is not inside the array

fill()#source

function fill(mixed $value, int $from = 0, ?int $to = null): void

Stores $value into the positions $from up to (not including) $to.

Parameters

$value mixed
the value to store
$from int = 0
the first position
$to ?int = null
one past the last position; the size when null

Throws

\OutOfBoundsException
when the range is not inside the array
\ValueError
when $value is out of range for the element type
\TypeError
when $value is of the wrong kind

copyFrom()#source

function copyFrom(TypedArray $src, int $srcAt, int $dstAt, int $count): void

Copies $count elements of $src starting at $srcAt to this array starting at $dstAt.

$src must be an array of exactly the same class.

Parameters

$src TypedArray
the array to copy from
$srcAt int
the first source position
$dstAt int
the first destination position
$count int
how many elements to copy

Throws

\TypeError
when $src is not of the same class
\ValueError
when $count is negative
\OutOfBoundsException
when either range is not inside its array

apply()#source

abstract function apply(callable $f): void

Replaces each element with $f($element, $index), in place. The result is stored like $a[$i] = $v, so a value that does not fit throws and leaves the elements before it replaced. The size is read once: a callback that shrinks the array makes the next access throw OutOfBoundsException.

Parameters

$f callable
receives the element and its index, returns the new element

Throws

\ValueError
when a result is out of range for the element type
\TypeError
when a result is of the wrong kind
\OutOfBoundsException
when the callback shrank the array

equals()#source

function equals(TypedArray $other): bool

Whether $other is the same class of array with the same elements.

Parameters

$other TypedArray
the array to compare with

Returns

bool — true when the classes, sizes and every element agree

indexOf()#source

function indexOf(mixed $value, int $from = 0): int

First position >= $from holding $value, or -1.

A value that cannot be stored in this array (out of range) is never found and answers -1. A negative $from starts at 0. O(n).

Parameters

$value mixed
the value to look for
$from int = 0
the position to start at

Returns

int — the position, or -1 when not found

Throws

\TypeError
when $value is of the wrong kind

offsetExists()#source

function offsetExists(mixed $offset): bool

Tells whether $offset names an element: isset($a[$offset]).

An int, an integer-like string, a float or a bool is cast to an int position; any other $offset answers false.

Parameters

$offset mixed
the index

Returns

bool — true when the position is inside 0..count-1

offsetSet()#source

function offsetSet(mixed $offset, mixed $value): void

Stores $value at $offset: $a[$offset] = $value; $a[] = $value appends.

Parameters

$offset mixed
the index, or null to append
$value mixed
the element

Throws

\OutOfBoundsException
when the position is outside 0..count-1
\ValueError
when $value is out of range for the element type
\TypeError
when $value or $offset is of the wrong kind

offsetUnset()#source

function offsetUnset(mixed $offset): void

Zeroes the element: a fixed-width slot cannot be absent.

Parameters

$offset mixed
the index

Throws

\OutOfBoundsException
when the position is outside 0..count-1
\TypeError
when $offset is of the wrong kind

getIterator()#source

function getIterator(): \Iterator

Iterates the elements by index, yielding index => element.

Returns

\Iterator — an iterator over the elements

jsonSerialize()#source

function jsonSerialize(): array

Encodes as a JSON array of the elements.

Returns

array<int, mixed> — the elements as a list

View source