README

The abstract TypedArray class implements typed arrays in PHP with strict type checking. The class implements the Iterator, ArrayAccess, and Countable interfaces, allowing you to work with the object as with a regular array.

Features

Strong Typing: All values are checked against the type returned by the getType() method via get_debug_type.
Fixed Length: Option to prevent array resizing.
Nesting: Support for multidimensional typed arrays.
Rich API: Methods for filtering, sorting, searching, transforming, and other array operations.

How to install

You can install the package with the composer:

composer require multihanded/typed-array

Public Methods

Note: All class methods are provided with full PHPDoc blocks describing their parameters, return values, and thrown exceptions. Detailed information about each method is available directly in your IDE using autocompletion or by hovering over it.

Abstract Methods

Method	Description
`static getType(): string`	An abstract method that must be implemented in the derived class and returns a string with the expected data type.

Constructor and Instance Creation

Method	Description
`__construct(array $initialArray = [], bool $fixedLength = false)`	Constructor. Accepts an initial array and a fixed-length flag.
`static fill(int $start_index, int $count, mixed $value): static`	Creates a new instance filled with the specified value for the index range. If `$count` is greater than the array length or less than 0, a `ValueError` is thrown.
`static fillKeys(array $keys, mixed $value): static`	Creates a new instance filled with a value using the array of keys.
`static combine(array $keys, array $values): static`	Creates an instance using one array for keys and another for values.

Basic Operations

Method	Description
`set(mixed $value, string\|int\|null $key = null): $this`	Sets the value by key (or appends to the end of the array). Returns the current instance.
`plain(): array`	Converts the inner collection to a regular PHP array.
`plainRecursive(?int $depth = null): array`	Recursively converts nested collections to a regular array. If `$depth = null` (the default), all possible nesting levels are traversed. If `$depth` is specified as a number, the conversion is limited to the specified number of levels.
`count(): int`	Returns the number of elements (`interface Countable`).
`isFixedLength(): bool`	Checks if the array's length is fixed.
`fixLength(): $this`	Fixes the array's length, preventing it from changing. Returns the current instance.

Iteration and Element Access

Method	Description
`rewind(): void`	Resets the internal pointer (`interface Iterator`).
`current(): mixed`	Returns the current element (`interface Iterator`).
`key(): mixed`	Returns the current key (`interface Iterator`).
`next(): void`	Moves the pointer forward (`interface Iterator`).
`valid(): bool`	Checks if the current position (`interface Iterator`) is valid.
`prev(): void`	Moves the pointer to the previous element.
`end(): void`	Moves the pointer to the last element.
`offsetExists(mixed $offset): bool`	Checks if a key exists (`interface ArrayAccess`).
`offsetGet(mixed $offset): mixed`	Returns the value by key (`interface ArrayAccess`).
`offsetSet(mixed $offset, mixed $value): void`	Sets the value (`interface ArrayAccess`).
`offsetUnset(mixed $offset): void`	Removes an element by key (`interface ArrayAccess`).

Checking and Searching

Method	Description
`all(callable $callback): bool`	Checks whether all elements satisfy the callback function.
`any(callable $callback): bool`	Checks whether at least one element satisfies the callback function.
`find(callable $callback, bool $findKey = false): mixed`	Returns the first element (or its key) that satisfies the callback.
`isList(): bool`	Checks whether the array is a list (keys are numbered sequentially starting from 0).
`keyExists(string\|int $key): bool`	Checks whether a key exists.
`keyFirst(): int\|string\|null`	Returns the first key of the array.
`keyLast(): int\|string\|null`	Returns the last key of the array.
`keys(mixed $filterValue): array`	Returns keys that contain the specified value.
`first(): mixed`	Returns the first value of the array.
`last(): mixed`	Returns the last value of the array.
`inArray(mixed $needle): bool`	Checks if a value is in the array.
`search(mixed $needle): int\|string\|false`	Searches for a value and returns the first matching key.

Conversion and Modification (Immutable)

Important: All methods in this section return a new instance of the class with fixedLength = false.

Intersections and Divergences

Method	Description
`diff(TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference between arrays. Important: All passed `TypedArray` instances must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`diffAssoc(TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference with additional index checking. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`diffUassoc(callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference by checking indices via a callback.
`diffKey(TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference using the keys for comparison. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`diffUkey(callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference between keys via a callback. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`udiff(callable $value_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference via a callback for comparing values. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`udiffAssoc(callable $value_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Calculates the difference by checking indices via a callback for values. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`udiffUassoc(callable $value_compare_func, callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the difference via a callback for values and keys. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`intersect(TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection of arrays. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`intersectAssoc(TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection with additional index checking. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`intersectUassoc(callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection with index checking via the callback. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`intersectKey(TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection using keys. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`intersectUkey(callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection of keys via the callback. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`uintersect(callable $value_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection of values via the callback. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a TypeError.
`uintersectAssoc(callable $value_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection by checking the indices via a callback for values. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`uintersectUassoc(callable $value_compare_func, callable $key_compare_func, TypedArray $array, TypedArray ...$arrays): static`	Computes the intersection via a callback for values and keys. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.

Other Methods

Method	Description
`changeKeyCase(int $case = CASE_LOWER): static`	Changes the case of all keys.
`countValues(): array`	Counts the number of occurrences of each value.
`filter(?callable $callback = null, int $mode = 0): static`	Filters elements using a callback function. If `$callback` is not passed, all empty elements will be removed from the array.
`map(callable $callback): static`	Applies a callback to all elements.
`pad(int $length, mixed $value): static`	Pads an array to the specified length with a value.
`merge(TypedArray $array, TypedArray ...$arrays): static`	Merges multiple arrays. Important: All `TypedArray` passed must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`mergeRecursive(TypedArray $array, TypedArray ...$arrays): static`	Recursively merges arrays. Continues until it reaches elements that do not implement `TypedArray`. Important: All `TypedArray` passed must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`replace(TypedArray $array, TypedArray ...$arrays): static`	Replaces the values of the current array with the values from the passed arrays (keys from the passed arrays replace keys in the current array). Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`replaceRecursive(TypedArray $array, TypedArray ...$arrays): static`	Recursively replaces values. Goes deeper until it reaches elements that do not implement `TypedArray`. Important: All passed `TypedArray` must be instances of the same class as the caller. Attempting to pass an array of a different type will result in a `TypeError`.
`reverse(bool $preserveKeys = false): static`	Returns the array in reverse order.
`slice(int $offset, ?int $length = null, bool $preserveKeys = false): static`	Extracts a slice of the array.
`unique(): static`	Removes duplicate values.
`values(): static`	Returns all values in the array.

Modifying the Current Instance (Mutable)

Important: All methods in this section return the current instance ($this) for chaining purposes.

Sorting

Method	Description
`arsort(int $flags = SORT_REGULAR): $this`	Sorts in descending order, preserving keys.
`asort(int $flags = SORT_REGULAR): $this`	Sorts in ascending order, preserving keys.
`krsort(int $flags = SORT_REGULAR): $this`	Sorts by keys in descending order.
`ksort(int $flags = SORT_REGULAR): $this`	Sorts by keys in ascending order.
`natcasesort(): $this`	Sorts using the "natural order" algorithm (case-insensitive).
`natsort(): $this`	Sorts using the "natural order" algorithm.
`rsort(int $flags = SORT_REGULAR): $this`	Sorts in descending order.
`sort(int $flags = SORT_REGULAR): $this`	Sorts in ascending order.
`uasort(callable $callback): $this`	Sorts while preserving keys, using callback for comparison.
`uksort(callable $callback): $this`	Sorts by keys, using callback for comparison.
`usort(callable $callback): $this`	Sorts by values, using callback for comparison.
`multisort(TypedArray\|int $param, TypedArray\|int ...$params): $this`	Sorts the collection along with other `TypedArray` objects.
`shuffle(): $this`	Shuffles the array randomly.

Other Methods

Method	Description
`pop(): mixed`	Removes and returns the last element.
`push(mixed ...$values): int`	Adds one or more values to the end of the array.
`shift(): mixed`	Removes and returns the first element.
`unshift(mixed ...$values): int`	Adds one or more values to the beginning of the array.
`walk(callable $callback, mixed $arg = null): $this`	Applies a custom function to each element.
`walkRecursive(callable $callback, mixed $arg = null): $this`	Recursively applies a user-defined function until it reaches elements that do not implement `TypedArray`.

Calculating sums, products, and more

Method	Description
`sum(): int\|float`	Calculates the sum of all values.
`product(): int\|float`	Calculates the product of all values.
`reduce(callable $callback, mixed $initial = null): mixed`	Iteratively reduces an array to a single value.
`rand(int $num = 1): int\|string\|array`	Selects one or more random keys. If the array is empty, or `$num` is greater than the array length or less than 1, a `ValueError` is thrown.
`flip(): array`	Swaps all keys with their values (returns a regular array).

Working with Nesting

General Methods

Method	Description
`canDeepen(): bool`	Determines whether it is possible to go deeper to the next level of nesting.
`static isNestedArray(): bool`	Checks whether the current type represents a nested structure.
`depth(): int`	Calculates the actual nesting depth based on the contents.

Specialized Methods

Important: The following methods work only with the first level of nesting and require that the current instance be a multi-level typed array.

Method	Description
`flat(): TypedArray`	Collapses nested first-level collections into a single typed array, discarding keys.
`column(int\|string\|null $column_key, int\|string\|null $index_key = null): TypedArray`	Returns values from a single first-level column of a nested collection.
`zip(): static`	Zips nested first-level arrays, truncating the output to the length of the shortest array.
`chunk(int $length): static`	Concatenates first-level arrays and then splits them into chunks of the specified length. Keys are not preserved. If `$length` < 1, a `ValueError` is thrown.

Example of use

class IntArray extends TypedArray
{
    public static function getType(): string
    {
        return 'int';
    }
}

class NestedIntArray extends TypedArray
{
    public static function getType(): string
    {
        return IntArray::class;
    }
}

$typedArray = new NestedIntArray([
    new IntArray([1, 2, 3]),
    new IntArray([4, 5, 6]),
    new IntArray([7, 8, 9]),
]);

print_r($typedArray->walkRecursive(fn(&$val) => $val *= 2)->flat()->plain()); // [2, 4, 6, 8, 10, 12, 14, 16, 18]

multihanded/typed-array

包简介

README 文档

README

Features

How to install

Public Methods

Abstract Methods

Constructor and Instance Creation

Basic Operations

Iteration and Element Access

Checking and Searching

Conversion and Modification (Immutable)

Intersections and Divergences

Other Methods

Modifying the Current Instance (Mutable)

Sorting

Other Methods

Calculating sums, products, and more

Working with Nesting

General Methods

Specialized Methods

Example of use

统计信息

GitHub 信息

其他信息

承接程序开发