Menu

Reference

Reference / Manticore\Ds

Vec

finalclass
final class Vec<T> implements \ArrayAccess, \Countable, \IteratorAggregate, \JsonSerializable

A growable list of values of any type, indexed 0..count-1.

A Vec holds arbitrary PHP values (use the typed arrays such as {@see Int32Array} when every element is a fixed-width number). Reads and writes by index are O(1), push() is amortised O(1). Unlike a PHP array it has no gaps and no string keys: an index outside 0..count-1 throws OutOfBoundsException, a non-int index throws TypeError, and elements cannot be unset(); use pop() to drop the last one.

A Vec is an object (assignment copies the handle, clone copies the elements shallowly). It implements ArrayAccess ($v[$i], $v[] = $x), Countable, IteratorAggregate and JsonSerializable (encoded as a JSON array).

$v = new Vec();
$v->push('a');
$v[] = 'b';
echo count($v);   // 2

Example

use Manticore\Ds\Vec;

$v = new Vec();
$v->push('a');
$v[] = 'b';
$v->push(42);                   // any type
echo count($v), "\n";           // 3
echo $v[1], "\n";               // b

$v[0] = 'z';
echo $v->pop(), "\n";           // 42

$nums = Vec::fromArray([1, 2, 3, 4]);
$squares = $nums->map(fn($n) => $n * $n);
echo json_encode($squares), "\n";
echo $nums->filter(fn($n) => $n % 2 === 0)->reduce(fn($sum, $n) => $sum + $n, 0), "\n";

try {
    echo $v[10];
} catch (OutOfBoundsException $e) {
    echo $e->getMessage(), "\n";
}

Output

3
b
42
[1,4,9,16]
6
Index invalid or out of range

See also: Map, Set

Methods

__construct()Creates an empty vector.
__clone()Makes the clone an independent vector with the same elements (copied shallowly).
fromArray()Builds a vector from the values of $values; the keys are ignored.
push()Appends $value; $v[] = $value is the same.
pop()Removes and returns the last element.
count()Returns the number of elements.
isEmpty()Tells whether the vector has no elements.
clear()Removes every element.
offsetExists()Tells whether $offset is an int index inside 0..count-1: isset($v[$offset]).
offsetGet()Returns the element at $offset: $v[$offset].
offsetSet()Replaces the element at $offset: $v[$offset] = $value; with a null offset ($v[] = $value) it appends.
offsetUnset()Always throws: elements cannot be removed from the middle.
toArray()Copies the elements into a PHP list.
getIterator()Iterates the elements by index, yielding index => element.
jsonSerialize()Encodes as a JSON array of the elements.
each()Calls $f($element, $index) for every element, in order.
map()Builds a new vector of $f($element, $index) for every element.
filter()Builds a new vector with the elements for which $f($element, $index) is truthy.
reduce()Folds the elements into one value: $carry = $f($carry, $element, $index).
any()Tells whether $f($element, $index) is truthy for at least one element (stops at the first).
all()Tells whether $f($element, $index) is truthy for every element (stops at the first miss).
find()Returns the first element for which $f($element, $index) is truthy.

__construct()#source

function __construct()

Creates an empty vector.

__clone()#source

function __clone()

Makes the clone an independent vector with the same elements (copied shallowly).

fromArray()#source

static function fromArray(array $values): Vec

Builds a vector from the values of $values; the keys are ignored.

Parameters

$values array<T>
the source array

Returns

Vec<T> — a new vector holding the values in array order

push()#source

function push(mixed $value): void

Appends $value; $v[] = $value is the same.

Parameters

$value T
the element to append

pop()#source

function pop(): mixed

Removes and returns the last element.

Returns

T — the removed element

Throws

\UnderflowException
when the vector is empty

count()#source

function count(): int

Returns the number of elements.

Returns

int — the element count

isEmpty()#source

function isEmpty(): bool

Tells whether the vector has no elements.

Returns

bool — true when empty

clear()#source

function clear(): void

Removes every element.

offsetExists()#source

function offsetExists(mixed $offset): bool

Tells whether $offset is an int index inside 0..count-1: isset($v[$offset]).

Any other $offset (including a numeric string) answers false.

Parameters

$offset mixed
the index

Returns

bool — true when the index is valid

offsetGet()#source

function offsetGet(mixed $offset): mixed

Returns the element at $offset: $v[$offset].

Parameters

$offset mixed
the index

Returns

mixed — the element

Throws

\OutOfBoundsException
when the index is outside 0..count-1
\TypeError
when the index is not an int

offsetSet()#source

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

Replaces the element at $offset: $v[$offset] = $value; with a null offset ($v[] = $value) it appends.

Parameters

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

Throws

\OutOfBoundsException
when the index is outside 0..count-1
\TypeError
when the index is not an int

offsetUnset()#source

function offsetUnset(mixed $offset): void

Always throws: elements cannot be removed from the middle.

Parameters

$offset mixed
the index

Throws

\Error
always; use pop() to drop the last element

toArray()#source

function toArray(): array

Copies the elements into a PHP list.

Returns

list<T> — the elements in index order

getIterator()#source

function getIterator(): \Generator

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

Returns

\Generator — a generator over the elements

jsonSerialize()#source

function jsonSerialize(): mixed

Encodes as a JSON array of the elements.

Returns

mixed — the list from {@see toArray()}

each()#source

function each(callable $f): void

Calls $f($element, $index) for every element, in order.

Parameters

$f callable(T, int): void
the callback

map()#source

function map(callable $f): Vec

Builds a new vector of $f($element, $index) for every element.

Parameters

$f callable(T, int): U
maps an element (and its index) to the new element

Returns

Vec<U> — a new vector; this one is unchanged

filter()#source

function filter(callable $f): Vec

Builds a new vector with the elements for which $f($element, $index) is truthy.

The kept elements are renumbered from 0.

Parameters

$f callable(T, int): bool
the predicate

Returns

Vec<T> — a new vector; this one is unchanged

reduce()#source

function reduce(callable $f, mixed $initial): mixed

Folds the elements into one value: $carry = $f($carry, $element, $index).

Parameters

$f callable(R, T, int): R
combines the carry with the next element
$initial R
the starting carry, also the result for an empty vector

Returns

R — the final carry

any()#source

function any(callable $f): bool

Tells whether $f($element, $index) is truthy for at least one element (stops at the first).

Parameters

$f callable(T, int): bool
the predicate

Returns

bool — false for an empty vector

all()#source

function all(callable $f): bool

Tells whether $f($element, $index) is truthy for every element (stops at the first miss).

Parameters

$f callable(T, int): bool
the predicate

Returns

bool — true for an empty vector

find()#source

function find(callable $f): mixed

Returns the first element for which $f($element, $index) is truthy.

null means "none matched" but is also a valid element; use {@see any()} when the vector can hold null.

Parameters

$f callable(T, int): bool
the predicate

Returns

?T — the first matching element, or null

View source