Skip to content

Wiki Arr

Jump to bottom
Danijel Galić edited this page Feb 1, 2024 · 3 revisions 
final class \FireHub\Core\Support\LowLevel\Arr()

Important

This class is marked as final.

### Array low-level proxy class

This class was created by Danijel Galić <danijel.galic@outlook.com>
Copyright: 2024 FireHub Web Application Framework
License: <https://opensource.org/licenses/OSL-3.0> OSL Open Source License version 3
Version: GIT: $Id$ Blob checksum.

Fully Qualified Class Name:  \FireHub\Core\Support\LowLevel\Arr
Source code:  view source code
Blame:  view blame
History:  view history

Methods

Type Name Title
public static keyExist ### Checks if the given key or index exists in the array
public static inArray ### Checks if a value exists in an array
public static isList ### Checks whether a given array is a list
public static multiSort ### Sort multiple or multidimensional arrays
public static walk ### Apply a user function to every member of an array
public static walkRecursive ### Apply a user function recursively to every member of an array
public static countValues ### Counts the occurrences of each distinct value in an array
public static fill ### Fill an array with values
public static fillKeys ### Fill an array with values, specifying keys
public static foldKeys ### Changes the case of all keys in an array
public static chunk ### ### Split an array into chunks
public static column ### Return the values from a single column in the input array
public static combine ### Creates an array by using one array for keys and another for its values
public static difference ### Computes the difference of arrays using values for comparison
public static differenceFunc ### Computes the difference of arrays using values for comparison by using a callback for comparison
public static differenceKey ### Computes the difference of arrays using keys for comparison
public static differenceKeyFunc ### Computes the difference of arrays using keys for comparison by using a callback for data comparison
public static differenceAssoc ### Computes the difference of arrays with additional index check
public static differenceAssocFuncValue ### Computes the difference of arrays with additional index check by using a callback for value comparison
public static differenceAssocFuncKey ### Computes the difference of arrays with additional index check by using a callback for key comparison
public static differenceAssocFuncKeyValue ### Computes the difference of arrays with additional index check by using a callback for key-value comparison
public static intersect ### Computes the intersection of arrays using values for comparison
public static intersectFunc ### Computes the intersection of arrays using values for comparison by using a callback for data comparison
public static intersectKey ### Computes the intersection of arrays using keys for comparison
public static intersectKeyFunc ### Computes the intersection of arrays using keys for comparison by using a callback for data comparison
public static intersectAssoc ### Computes the intersection of arrays with additional index check
public static intersectAssocFuncValue ### Computes the intersection of arrays with additional index check by using a callback for value comparison
public static intersectAssocFuncKey ### Computes the intersection of arrays with additional index check by using a callback for key comparison
public static intersectAssocFuncKeyValue ### Computes the intersection of arrays with additional index check by using a callback for key-value comparison
public static filter ### Filter elements in an array
public static flip ### Exchanges all keys with their associated values in an array
public static keys ### Return all the keys or a subset of the keys of an array
public static values ### Return all the values from an array
public static map ### Applies the callback to the elements of the given arrays
public static merge ### Merges the elements of one or more arrays together
public static mergeRecursive ### Merge two or more arrays recursively
public static pad ### Pad array to the specified length with a value
public static replace ### Replaces elements from passed arrays into the first array
public static replaceRecursive ### Replace two or more arrays recursively
public static reverse ### Reverse the order of array items
public static slice ### Extract a slice of the array
public static splice ### Remove a portion of the array and replace it with something else
public static unique ### Removes duplicate values from an array
public static range ### Create an array containing a range of elements
public static random ### Pick one or more random keys out of an array
public static reduce ### Iteratively reduce the array to a single value using a callback function
public static pop ### Pop the element off the end of array
public static push ### Push elements onto the end of array
public static shift ### Removes an item at the beginning of an array
public static unshift ### Prepend one or more elements to the beginning of an array
public static firstKey ### Get first key from an array
public static lastKey ### Get last key from array
public static product ### Calculate the product of values in an array
public static sum ### Calculate the sum of values in an array
public static search ### Searches the array for a given value and returns the first corresponding key if successful
public static shuffle ### Shuffle array
public static sort ### Sorts array
public static sortByKey ### Sorts array by key
public static sortBy ### Sorts an array by values using a user-defined comparison function
public static sortKeyBy ### Sorts array by key using a user-defined comparison function

# method: keyExist

public static Arr::keyExist(array-key $key, array $array):bool

Note

Method will search for the keys in the first dimension only. Nested keys in multidimensional arrays will not be found.

### Checks if the given key or index exists in the array

Returns true if the given key is set in the array. Key can be any value possible for an array index.

Source code:  view source code
Blame:  view blame

Parameters

  • array-key $key - Key to check.
  • array $array - array<array-key, mixed> An array with keys to check.

Returns

  • bool - True if key exists in an array, false otherwise.

# method: inArray

public static Arr::inArray(mixed $value, array $array):bool

### Checks if a value exists in an array

Source code:  view source code
Blame:  view blame

Parameters

  • mixed $value - The searched value. note: If a needle is a string, the comparison is done in a case-sensitive manner.
  • array $array - array<array-key, mixed> The array.

Returns

  • bool - True if value is found in the array, false otherwise.

# method: isList

public static Arr::isList(array $array):bool

Note

This function returns true on empty arrays.

### Checks whether a given array is a list

Determines if the given array is a list. An array is considered a list if its keys consist of consecutive numbers from 0 to count($array)-1.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, TValue> The array being evaluated.

Returns

  • bool - ($array is list ? true: false) True if an array is a list, false otherwise.

# method: multiSort

public static Arr::multiSort(array $array):bool

Caution

Associative (string) keys will be maintained, but numeric keys will be re-indexed.> [!NOTE] Resets array's internal pointer to the first element.

### Sort multiple or multidimensional arrays

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, array<array-key, mixed>> A multidimensional array being sorted.

Throws

  • \Error - Failed to sort a multi-sort array.
  • \ValueError - If array sizes are inconsistent.

Returns

  • bool - True on success.

# method: walk

public static Arr::walk(array &$array, callable $callback):true

### Apply a user function to every member of an array

Applies the user-defined callback function to each element of the array $array. Method is not affected by the internal array pointer of an array. Method will walk through the entire array regardless of pointer position.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array - array<TKey, TValue> The array to apply a user function.
  • callable $callback - callable (TValue $value, TKey $key):mixed Typically, function name takes on two parameters. The array parameter's value is the first, and the key/index second. If a function name needs to be working with the actual values of the array, specify the first parameter of function name as a reference. Then, any changes made to those elements will be made in the original array itself. Users may not change the array itself from the callback function, e.g., add/delete elements, unset elements, etc.

Throws

Returns

  • true - True on success.

# method: walkRecursive

public static Arr::walkRecursive(array &$array, callable $callback):true

### Apply a user function recursively to every member of an array

Applies the user-defined callback function to each element of the array. This function will recurse into deeper arrays.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array - array<TKey, TValue> The array to apply a user function.
  • callable $callback - callable (TValue $value, TKey $key):mixed Typically, function name takes on two parameters. The array parameter's value is the first, and the key/index second. If a function name needs to be working with the actual values of the array, specify the first parameter of function name as a reference. Then, any changes made to those elements will be made in the original array itself. Users may not change the array itself from the callback function. E.g., Add/delete elements, unset elements, etc.

Returns

  • true - True on success.

# method: countValues

public static Arr::countValues(array $array):array

### Counts the occurrences of each distinct value in an array

Returns an array using the values of $array (which must be int-s or strings) as keys and their frequency in an $array as values.

Source code:  view source code
Blame:  view blame

Templates

  • TValue of array-key

Parameters

  • array $array - array<array-key, TValue> The array of values to count.

Returns

  • array - array<array-key, positive-int> An associative array of values from input as keys and their count as value.

# method: fill

public static Arr::fill(mixed $value, int $start_index, int $length):array

### Fill an array with values

Fills an array with $length entries of the value of the $value parameter, keys starting at the $start_index parameter.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • mixed $value - TValue Value to use for filling.
  • int $start_index - The first index of the returned array.
  • int $length

Throws

Returns

  • array - array<int, TValue> Filled array.

# method: fillKeys

public static Arr::fillKeys(array $keys, mixed $value):array

### Fill an array with values, specifying keys

Fills an array with the value of the $value parameter, using the values of the $keys array as keys.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $keys - array<array-key, array-key> Array of values that will be used as keys. Illegal values for a key will be converted to string.
  • mixed $value - TValue Value to use for filling.

Throws

  • \Error - If key could not be converted to string.

Returns

  • array - array<TKey, TValue> The filled array.

# method: foldKeys

public static Arr::foldKeys(array $array, \FireHub\Core\Support\Enums\String\CaseFolding $case = CaseFolding::LOWER):array

### Changes the case of all keys in an array

Returns an array with all keys from array lowercased or uppercased. Numbered indices are left as is.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to work on.
  • \FireHub\Core\Support\Enums\String\CaseFolding $case = CaseFolding::LOWER - [optional] \FireHub\Core\Support\Enums\String\CaseFolding::LOWER|\FireHub\Core\Support\Enums\String\CaseFolding::UPPER Either LOWER or UPPER case folding.

Returns

  • array - array<TKey, TValue> An array with its keys lower or uppercased.

# method: chunk

public static Arr::chunk(array $array, positive-int $length, bool $preserve_keys = false):array

### ### Split an array into chunks

Chunks an array into arrays with $length elements. The last chunk may contain less than $length elements.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array.
  • positive-int $length - The size of each chunk. If the length is less than 1, it will default to 1.
  • bool $preserve_keys = false - [optional] When set to true, keys will be preserved. Default is false that will reindex the chunk numerically.

Throws

Returns

  • array - ($preserve_keys is true ? list<array<TKey, TValue>> : list<list>) Multidimensional numerically indexed array, starting with zero, with each dimension containing $length elements.

# method: column

public static Arr::column(array $array, int|string $key, null|int|string $index = null):array

### Return the values from a single column in the input array

Returns the values from a single column of the $array, identified by the $key. Optionally, an argument key may be provided to $index the values in the returned array by the values from the index argument column of the input array.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - _array<array-key, array<TKey, TValue>> A multidimensional array (record set) from which to pull a column of values. If an array of objects is provided, then public properties can be directly pulled. In order for protected or private properties to be pulled, the class must implement both the __get() and _isset() magic methods.
  • int or string $key - TKey The column of values to return. This value may be an integer key of the column you wish to retrieve, or it may be a string key name for an associative array or property name. It may also be null to return complete arrays or objects (this is useful together with $index to reindex the array).
  • null or int or string $index = null - [optional] null|TKey The column to use as the index/keys for the returned array. This value may be the integer key of the column, or it may be the string key name. The value is cast as usual for array keys.

Returns

  • array - ($index is null ? array : array<TValue, TValue>) Array of values representing a single column from the input array.

# method: combine

public static Arr::combine(array $keys, array $values):array

### Creates an array by using one array for keys and another for its values

Creates an array by using the values from the $keys array as keys and the values from the $values array as the corresponding values.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $keys - array<array-key, TKey> Array of values to be used as keys. Illegal values for a key will be converted to string.
  • array $values - array<array-key, TValue> Array of values to be used as values on a combined array.

Throws

  • \ValueError - If arguments $keys and $values don't have the same number of elements.

Returns

  • array - array<TKey, TValue> The combined array.

# method: difference

public static Arr::difference(array $array, array ...$excludes):array

Note

This function only checks one dimension of an n-dimensional array. You can check deeper dimensions by using Arr#difference($array1[0], $array2[0]).

### Computes the difference of arrays using values for comparison

Compares an array against one or more other arrays and returns the values in array that are not present in any of the other arrays.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<array-key, TValue> The array to compare from.
  • variadic array $excludes - [optional] array<array-key, mixed> An array to compare against.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceFunc

public static Arr::differenceFunc(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] Please note that this function only checks one dimension of an n-dimensional array. Of course, you can check deeper dimensions by using Arr#differenceFunc($array1[0], $array2[0]), 'data_compare_func'.

### Computes the difference of arrays using values for comparison by using a callback for comparison

Computes the difference of arrays by using a callback function for data comparison. This is unlike Arr#difference() which uses an internal function for comparing the data.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceKey

public static Arr::differenceKey(array $array, array ...$excludes):array

Note

This function only checks one dimension of an n-dimensional array. Of course, you can check deeper dimensions by using Arr#differenceKey($array1[0], $array2[0]).

### Computes the difference of arrays using keys for comparison

Compares the keys from array against the keys from arrays and returns the difference. This function is like Arr#difference() except the comparison is done on the keys instead of the values.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • variadic array $excludes - [optional] array<array-key, mixed> An array to compare against.

Returns

  • array - array<TKey, TValue> Returns an array containing all the entries from array whose keys are absent from all the other arrays.

# method: differenceKeyFunc

public static Arr::differenceKeyFunc(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] This function only checks one dimension of an n-dimensional array. Of course, you can check deeper dimensions by using Arr#differenceKeyFunc($array1[0], $array2[0], 'callback_func').

### Computes the difference of arrays using keys for comparison by using a callback for data comparison

Compares the keys from array against the keys from arrays and returns the difference. This function is like Arr#difference() except the comparison is done on the keys instead of the values.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceAssoc

public static Arr::differenceAssoc(array $array, array ...$excludes):array

Note

This function only checks one dimension of an n-dimensional array. It is possible to check deeper dimensions by using, for example, Arr#differenceAssoc($array1[0], $array2[0]).> [!NOTE] Ensure arguments are passed in the correct order when comparing similar arrays with more keys. The new array should be the first in the list.

### Computes the difference of arrays with additional index check

Compares an array against arrays and returns the difference. Unlike Arr#difference(), the array keys are also used in the comparison.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • variadic array $excludes - [optional] array<array-key, mixed> An array to compare against.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceAssocFuncValue

public static Arr::differenceAssocFuncValue(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] Please note that this function only checks one dimension of an n-dimensional array. Of course, you can check deeper dimensions by using, for example, Arr#differenceAssocFuncValue($array1[0], $array2[0], 'some_comparison_func').

### Computes the difference of arrays with additional index check by using a callback for value comparison

Computes the difference of arrays with additional index check, compares data by a callback function.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceAssocFuncKey

public static Arr::differenceAssocFuncKey(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] This function only checks one dimension of an n-dimensional array. It is possible to check deeper dimensions by using, for example, Arr#differenceAssocFuncKey($array1[0], $array2[0], 'key_compare_func').

### Computes the difference of arrays with additional index check by using a callback for key comparison

Compares an array against arrays and returns the difference. Unlike Arr#difference(), the array keys are used in the comparison. Unlike Arr#differenceAssoc(), a user-supplied callback function is used for the indices comparison, not internal function.

Source code:  view source code
Blame:  view blame

Templates

  • TKey
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> Returns an array containing all the entries from $array that are not present in any of the other arrays.

# method: differenceAssocFuncKeyValue

public static Arr::differenceAssocFuncKeyValue(array $array, array $excludes, callable $callback_value, callable $callback_key):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] This function only checks one dimension of an n-dimensional array. It is possible to check deeper dimensions by using, for example, Arr#differenceAssocFuncKeyValue($array1[0], $array2[0], 'data_compare_func', 'key_compare_func').

### Computes the difference of arrays with additional index check by using a callback for key-value comparison

Computes the difference of arrays with additional index check, compares data and indexes by a callback function. Note that the keys are used in the comparison unlike Arr#difference() and Arr#differenceFunc().

Source code:  view source code
Blame:  view blame

Templates

  • TKey
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback_value - callable (mixed $a, mixed $b):int<-1, 1> The comparison function for value.
  • callable $callback_key - callable (mixed $a, mixed $b):int<-1, 1> The comparison function for key.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: intersect

public static Arr::intersect(array $array, array ...$arrays):array

Note

Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.

### Computes the intersection of arrays using values for comparison

Returns an array containing all the values of array that are present in all the arguments. Note that keys are preserved.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array with main values to check.
  • variadic array $arrays - [optional] array<array-key, mixed> An array to compare values against.

Returns

  • array - array<TKey, TValue> The filtered array.

# method: intersectFunc

public static Arr::intersectFunc(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.

### Computes the intersection of arrays using values for comparison by using a callback for data comparison

Computes the intersection of arrays, compares data by a callback function.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> Arrays containing all the entries from $array that are not present in any of the other arrays.

# method: intersectKey

public static Arr::intersectKey(array $array, array ...$arrays):array

### Computes the intersection of arrays using keys for comparison

Returns an array containing all the entries of array which have keys that are present in all the arguments.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array with main values to check.
  • variadic array $arrays - [optional] array<array-key, mixed> An array to compare values against.

Returns

  • array - array<TKey, TValue> The filtered array.

# method: intersectKeyFunc

public static Arr::intersectKeyFunc(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

### Computes the intersection of arrays using keys for comparison by using a callback for data comparison

Returns an array containing all the values of array which have matching keys that are present in all the arguments.

Source code:  view source code
Blame:  view blame

Templates

  • TKey
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: intersectAssoc

public static Arr::intersectAssoc(array $array, array ...$arrays):array

Note

The two values from the key → value pairs are considered equal only if (string) $elem1 === (string) $elem2. In other words, a strict type check is executed, so the string representation must be the same.

### Computes the intersection of arrays with additional index check

Returns an array containing all the values of array that are present in all the arguments. Note that the keys are also used in the comparison unlike in Arr#intersect().

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array with main values to check.
  • variadic array $arrays - [optional] array<array-key, mixed> An array to compare values against.

Returns

  • array - array<TKey, TValue> The filtered array.

# method: intersectAssocFuncValue

public static Arr::intersectAssocFuncValue(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

### Computes the intersection of arrays with additional index check by using a callback for value comparison

Computes the intersection of arrays with additional index check, compares data by a callback function. Note that the keys are used in the comparison unlike in Arr#intersectFunc(). The data is compared by using a callback function.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - $callback callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: intersectAssocFuncKey

public static Arr::intersectAssocFuncKey(array $array, array $excludes, callable $callback):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

### Computes the intersection of arrays with additional index check by using a callback for key comparison

Computes the intersection of arrays with additional index check, compares data and indexes by separate callback functions.

Source code:  view source code
Blame:  view blame

Templates

  • TKey
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback - callable (mixed $a, mixed $b):int<-1, 1> The comparison function.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: intersectAssocFuncKeyValue

public static Arr::intersectAssocFuncKeyValue(array $array, array $excludes, callable $callback_value, callable $callback_key):array

Caution

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.> [!NOTE] The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

### Computes the intersection of arrays with additional index check by using a callback for key-value comparison

Computes the intersection of arrays with additional index check, compares data and indexes by separate callback functions.

Source code:  view source code
Blame:  view blame

Templates

  • TKey
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to compare from.
  • array $excludes - array<array-key, mixed> An array to compare against.
  • callable $callback_value - callable (mixed $a, mixed $b):int<-1, 1> The comparison function for value.
  • callable $callback_key - callable (mixed $a, mixed $b):int<-1, 1> The comparison function for key.

Returns

  • array - array<TKey, TValue> An array containing all the entries from $array that are not present in any of the other arrays.

# method: filter

public static Arr::filter(array $array, null|callable $callback = null, bool $pass_key = false):array

Caution

If the array is changed from the callback function (e.g., an element added, deleted or unset) then behavior of this function is undefined.

### Filter elements in an array

Iterates over each value in the $array passing them to the $callback function. If the $callback function returns true, the current value from an $array is returned into the result array. Array keys are preserved, and may result in gaps if the $array was indexed. The result array can be re-indexed using the values() function.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to iterate over.
  • null or callable $callback = null - [optional] null|callable (TValue, TKey=):bool The callback function to use. If no callback is supplied, all empty and false entries of an array will be removed.
  • bool $pass_key = false - [optional] Pass key as the argument to callback.

Returns

  • array - array<TKey, TValue> Filtered array.

# method: flip

public static Arr::flip(array $array):array

### Exchanges all keys with their associated values in an array

Returns an array in flip order; i.e., keys from an $array become values and values from an $array become keys. Note that the values of $array need to be valid keys, i.e., they need to be either int or string. A warning will be emitted if a value has the wrong type, and the key/value pair in question will not be included in the result. If a value has several occurrences, the latest key will be used as its value, and all others will be lost.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue of array-key

Parameters

  • array $array - array<TKey, TValue> The array to flip.

Returns

  • array - array<TKey, TValue> The flipped array.

# method: keys

public static Arr::keys(array $array, mixed $filter = null):array

### Return all the keys or a subset of the keys of an array

Returns the keys, numeric and string, from the $array. If a $filter is specified, then only the keys for that value are returned. Otherwise, all the keys from the array are returned.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> An array containing keys to return.
  • mixed $filter = null - [optional] If specified, then only keys containing these values are returned.

Returns

  • array - list An array of all the keys in input.

# method: values

public static Arr::values(array $array):array

### Return all the values from an array

Returns all the values from the array and indexes the array numerically.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • array $array - array<array-key, TValue> The array.

Returns

  • array - array An indexed array of values.

# method: map

public static Arr::map(array $array, callable $callback):array

### Applies the callback to the elements of the given arrays

Returns an array containing the results of applying the $callback to the corresponding value of an $array used as arguments for the callback. The number of parameters that the $callback function accepts should match the number of arrays passed to map(). Excess input arrays are ignored. An ArgumentCountError is thrown if an insufficient number of arguments is provided.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> Array to run through the callback function.
  • callable $callback - null|callable (TValue $value):mixed Callback function to run for each element in each array. Null can be passed as a value to $callback to perform a zip operation on multiple arrays. If only an array is provided, map() will return the input array.

Throws

Returns

  • array - array<TKey, mixed> Array containing all the elements of arr1 after applying the callback function.

# method: merge

public static Arr::merge(array ...$arrays):array

Note

If the input arrays have the same string keys, then the later value for that key will overwrite the previous one.> [!NOTE] If the arrays contain numeric keys, the later value will be appended.> [!NOTE] Numeric keys will be renumbered.

### Merges the elements of one or more arrays together

Merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array. If the input arrays have the same string keys, then the later value for that key will overwrite the previous one. If, however, the arrays contain numeric keys, the later value will not overwrite the original value, but will be appended. Values in the input arrays with numeric keys will be renumbered with incrementing keys starting from zero in the result array.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • variadic array $arrays - [optional] array<TKey, TValue> Variable list of arrays to merge.

Returns

  • array - array<TKey, TValue> The resulting array.

# method: mergeRecursive

public static Arr::mergeRecursive(array ...$arrays):array

### Merge two or more arrays recursively

Merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array. If the input arrays have the same string keys, then the values for these keys are merged into an array. This is done recursively, so that if one of the values is an array itself, the function will merge it with a corresponding entry in another array too. If, however, the arrays have the same numeric key, the later value will not overwrite the original value, but will be appended.

Source code:  view source code
Blame:  view blame

Parameters

  • variadic array $arrays - [optional] array<array-key, mixed> Variable list of arrays to recursively merge.

Returns

  • array - array<array-key, mixed> The resulting array.

# method: pad

public static Arr::pad(array $array, int $length, mixed $value):array

Caution

Keys can be re-numbered.

### Pad array to the specified length with a value

Returns a copy of the array padded to size specified by $length with value $value. If the length is positive, then the array is padded on the right if it's negative then on the left. If the absolute value of length is less than or equal to the length of the array, then no padding takes place. It is possible to add at most 1048576 elements at a time.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> Initial array of values to pad.
  • int $length - New size of the array. If the length is positive, then the array is padded on the right if it's negative then on the left. If the absolute value of length is less than or equal to the length of the array, then no padding takes place.
  • mixed $value - Value to pad if input is less than length.

Returns

  • array - array<array-key, mixed> A copy of the input padded to size specified by $length with value $value.

# method: replace

public static Arr::replace(array $array, array ...$replacements):array

### Replaces elements from passed arrays into the first array

Replaces the values of $array with values having the same keys in each of the following arrays. If a key from the first array exists in the second array, its value will be replaced by the value from the second array. If the key exists in the second array, and not the first, it will be created in the first array. If a key only exists in the first array, it will be left as is. If several arrays are passed for replacement, they will be processed in order, the later arrays overwriting the previous values. Method is not recursive, it will replace values in the first array by whatever type is in the second array.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • array $array - array The array in which elements are replaced.
  • variadic array $replacements

Returns

  • array - array The resulting array.

# method: replaceRecursive

public static Arr::replaceRecursive(array $array, array ...$replacements):array

### Replace two or more arrays recursively

Replaces the values of $array with the same values from all the following arrays. If a key from the first array exists in the second array, its value will be replaced by the value from the second array. If the key exists in the second array, and not the first, it will be created in the first array. If a key only exists in the first array, it will be left as is. If several arrays are passed for replacement, they will be processed in order, the later array overwriting the previous values. When the value in the first array is scalar, it will be replaced by the value in the second array, may it be scalar or array. When the value in the first array and the second array are both arrays, replaceRecursive() will replace their respective values recursively.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • array $array - array The array in which elements are replaced.
  • variadic array $replacements

Returns

  • array - array The resulting array.

# method: reverse

public static Arr::reverse(array $array, bool $preserve_keys = false):array

### Reverse the order of array items

Takes an input array and returns a new array with the order of the elements reversed.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> Array to reverse.
  • bool $preserve_keys = false - [optional] Whether you want to preserve keys from an original array or not. Non-numeric keys are not affected by this setting and will always be preserved.

Returns

  • array - ($preserve_keys is true ? array<TKey, TValue> : array<array-key, TValue>) The reversed array.

# method: slice

public static Arr::slice(array $array, int $offset, null|int $length = null, bool $preserve_keys = false):array

### Extract a slice of the array

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The input array.
  • int $offset - If the offset is non-negative, the sequence will start at that offset in the array. If the offset is negative, the sequence will start that far from the end of the array.
  • null or int $length = null - [optional] If length is given and is positive, then the sequence will have that many elements in it. If length is given and is negative, then the sequence will stop that many elements from the end of the array. If it is omitted, then the sequence will have everything from offset up until the end of the array.
  • bool $preserve_keys = false - [optional] Note that array_slice will reorder and reset the array indices by default. You can change this behavior by setting preserve_keys to true.

Returns

  • array - ($preserve_keys is true ? array<TKey, TValue> : array<TKey|int, TValue>) Sliced array.

# method: splice

public static Arr::splice(array &$array, int $offset, null|int $length = null, mixed $replacement = []):array

Note

Numerical keys in an array are not preserved.> [!NOTE] If replacement is not an array, it will be typecast to one (i.e. (array) $replacement). This may result in unexpected behavior when using an object or null replacement.

### Remove a portion of the array and replace it with something else

Removes the elements designated by offset and length from the array $array, and replaces them with the elements of the replacement array, if supplied.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array - array<TKey, TValue> Array to splice.
  • int $offset - If the offset is positive, then the start of the removed portion is at that offset from the beginning of the input array. If the offset is negative, then it starts that far from the end of the input array.
  • null or int $length = null - [optional] If length is omitted, removes everything from offset to the end of the array. If length is specified and is positive, then that many elements will be removed. If length is specified and is negative, then the end of the removed portion will be that many elements from the end of the array.
  • mixed $replacement = [] - [optional] If a replacement array is specified, then the removed elements will be replaced with elements from this array. If offset and length are such that nothing is removed, then the elements from the replacement array or array are inserted in the place specified by the offset. Keys in a replacement array are not preserved.

Returns

  • array - array<TKey|int, TValue> Spliced array.

# method: unique

public static Arr::unique(array $array):array

Note

The new array will preserve associative keys, and reindex others.> [!NOTE] This method is not intended to work on multidimensional arrays.

### Removes duplicate values from an array

Takes an input array and returns a new array without duplicate values.

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • array $array - array<TKey, TValue> The array to remove duplicates.

Returns

  • array - array<TKey, TValue> The filtered array.

# method: range

public static Arr::range(int|float|string $start, int|float|string $end, int|float $step = 1):array

Note

Character sequence values are limited to a length of one. If a length greater than one is entered. only the first character is used.

### Create an array containing a range of elements

Source code:  view source code
Blame:  view blame

Parameters

  • int or float or string $start - First value of the sequence.
  • int or float or string $end - The sequence is ended upon reaching the end value.
  • int or float $step = 1 - [optional] If a step value is given, it will be used as the increment between elements in the sequence. Step should be given as a positive number. If not specified, a step will default to 1.

Throws

  • \ValueError - If &start or &end is a string implicitly cast to int because the other boundary value is a number, $start or $end is a non-numeric string with more than one byte or &start or &end is the empty string.

Returns

  • array - array<int, int|float|string> An array of elements from start to end, inclusive, false otherwise.

# method: random

public static Arr::random(array $array, int $number = 1):array|int|string

Caution

This function does not generate cryptographically secure values, and must not be used for cryptographic purposes, or purposes that require returned values to be unguessable.

### Pick one or more random keys out of an array

Picks one or more random entries out of an array, and returns the key (or keys) of the random entries.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> The input array.
  • int $number = 1 - [optional] Specifies how many entries should be picked.

Throws

  • \ValueError - If $number is not between one and the number of elements in argument.

Returns

  • array or int or string - array<int, array-key>|int|string When picking only one entry, array_rand() returns the key for a random entry. Otherwise, an array of keys for the random entries is returned.

# method: reduce

public static Arr::reduce(array $array, callable $callback, mixed $initial = null):mixed

### Iteratively reduce the array to a single value using a callback function

Iteratively applies the $callback function to the elements of the $array, to reduce the array to a single value.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> The input array.
  • callable $callback - callable (mixed $carry, mixed $item):mixed The callable function.
  • mixed $initial = null - [optional] If the optional initial is available, it will be used at the beginning of the process, or as a final result in case the array is empty.

Returns

  • mixed - Resulting value or null if the array is empty and initial is not passed.

# method: pop

public static Arr::pop(array &$array):mixed

Note

This function will reset the array pointer of the input array after use.

### Pop the element off the end of array

Pops and returns the last element value of th $array, shortening the $array by one element.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • by reference array $array - array<array-key, TValue> The array to get the value from.

Returns

  • mixed - TValue|null The last value of an array. If an array is empty (or is not an array), null will be returned.

# method: push

public static Arr::push(array &$array, \FireHub\Core\Support\LowLevel\TValue ...$values):int

Note

If you use push to add one element to the array, it's better to use $array[] = because in that way there is no overhead of calling a function.

### Push elements onto the end of array

Method treats an array as a stack, and pushes the passed variables onto the end of array. The length of array increases by the number of variables pushed.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • by reference array $array - array<array-key, TValue> The input array.
  • variadic \FireHub\Core\Support\LowLevel\TValue $values - [optional] The values to push onto the end of the array.

Returns

  • int - The new number of elements in the array.

# method: shift

public static Arr::shift(array &$array):mixed

Note

This function will reset the array pointer of the input array after use.

### Removes an item at the beginning of an array

Shifts the first value of the array off and returns it, shortening the array by one element and moving everything down. All numerical array keys will be modified to start counting from zero while literal keys won't be affected.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • by reference array $array - array<array-key, TValue> Array to shift.

Returns

  • mixed - TValue|null The shifted value, or null if an array is empty or is not an array.

# method: unshift

public static Arr::unshift(array &$array, \FireHub\Core\Support\LowLevel\TValue ...$values):int

Note

Resets array's internal pointer to the first element.

### Prepend one or more elements to the beginning of an array

Method prepends passed elements to the front of the array. Note that the list of elements is prepended as a whole, so that the prepended elements stay in the same order. All numerical array keys will be modified to start counting from zero while literal keys won't be changed.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

Returns

  • int - The new number of elements in the array.

# method: firstKey

public static Arr::firstKey(array $array):null|int|string

### Get first key from an array

Get the first key of the given $array without affecting the internal array pointer.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> An array.

Returns

  • null or int or string - First key from $array or null if an array is empty.

# method: lastKey

public static Arr::lastKey(array $array):null|int|string

### Get last key from array

Get the last key of the given $array without affecting the internal array pointer.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> An array.

Returns

  • null or int or string - Last key from $array or null if an array is empty.

# method: product

public static Arr::product(array $array):int|float

### Calculate the product of values in an array

Returns the product of values in an array.

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> The array.

Returns

  • int or float - The product as an integer or float.

# method: sum

public static Arr::sum(array $array):int|float

### Calculate the sum of values in an array

Source code:  view source code
Blame:  view blame

Parameters

  • array $array - array<array-key, mixed> The input array.

Returns

  • int or float - The sum of values as an integer or float; 0 if the array is empty.

# method: search

public static Arr::search(mixed $value, array $array):int|string|false

Warning

This method may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.

### Searches the array for a given value and returns the first corresponding key if successful

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • mixed $value - The searched value. If $value is a string, the comparison is done in a case-sensitive manner.
  • array $array - array<array-key, mixed> Array to search.

Returns

  • int or string or false - TKey|false The key for value if it is found in the array, false otherwise.

# method: shuffle

public static Arr::shuffle(array &$array):true

Caution

This function does not generate cryptographically secure values, and must not be used for cryptographic purposes, or purposes that require returned values to be unguessable.> [!NOTE] This function assigns new keys to the elements in array. It will remove any existing keys that may have been assigned, rather than just reordering the keys.> [!NOTE] Resets array's internal pointer to the first element.

### Shuffle array

This function shuffles (randomizes the order of the elements in) an array.

Source code:  view source code
Blame:  view blame

Templates

  • TValue

Parameters

  • by reference array $array - array<array-key, TValue> The array.

Returns

  • true - Always returns true.

# method: sort

public static Arr::sort(array &$array, \FireHub\Core\Support\Enums\Order $order = Order::ASC, \FireHub\Core\Support\Enums\Sort $flag = Sort::SORT_REGULAR, bool $preserve_keys = false):true

Note

Resets array's internal pointer to the first element.

### Sorts array

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array - array<TKey, TValue> Array to sort.
  • \FireHub\Core\Support\Enums\Order $order = Order::ASC - [optional] Order type.
  • \FireHub\Core\Support\Enums\Sort $flag = Sort::SORT_REGULAR - [optional] Sort flag.
  • bool $preserve_keys = false - [optional] Whether you want to preserve keys from an original array or not.

Returns

  • true - Always true.

# method: sortByKey

public static Arr::sortByKey(array<int|string,mixed> &$array, \FireHub\Core\Support\Enums\Order $order = Order::ASC, \FireHub\Core\Support\Enums\Sort $flag = Sort::SORT_REGULAR):true

Note

Resets array's internal pointer to the first element.

### Sorts array by key

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

Returns

  • true - Always true.

# method: sortBy

public static Arr::sortBy(array &$array, callable $callback, bool $preserve_keys = false):true

Note

Resets array's internal pointer to the first element.

### Sorts an array by values using a user-defined comparison function

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array
  • callable $callback - callable (TValue $a, TValue $b):int<-1, 1> The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
  • bool $preserve_keys = false - [optional] Whether you want to preserve keys from an original array or not.

Returns

  • true - Always true.

# method: sortKeyBy

public static Arr::sortKeyBy(array &$array, callable $callback):true

Note

Resets array's internal pointer to the first element.

### Sorts array by key using a user-defined comparison function

Source code:  view source code
Blame:  view blame

Templates

  • TKey of array-key
  • TValue

Parameters

  • by reference array $array - array<TKey, TValue> Array to sort.
  • callable $callback - callable (TKey $a, TKey $b):int<-1, 1> The callback comparison function. Function cmp_function should accept two parameters which will be filled by pairs of array keys. The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.

Returns

  • true - Always true.

Build with phpDocumentor using template FireHub phpDocumentor Wiki Template.

Clone this wiki locally