186 lines
8.8 KiB
PHP
186 lines
8.8 KiB
PHP
<?php
|
|
/**
|
|
* @author Daniel J. Summers <daniel@bitbadger.solutions>
|
|
* @license MIT
|
|
* @since 3.0.0
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace BitBadger\InspiredByFSharp;
|
|
|
|
use Error;
|
|
use Exception;
|
|
use InvalidArgumentException;
|
|
|
|
/**
|
|
* `Arr` has static functions that wrap PHP's native `array_*` functions with versions that provide a function which
|
|
* takes the input array. This makes these functions pipeable using PHP 8.5's pipe operator (ex.
|
|
* `array(1, 2, 3) |> Arr::map(fn ($x) => $x * 2)` would provide the array `[2, 4, 6]`).
|
|
*/
|
|
class Arr
|
|
{
|
|
/**
|
|
* Determine if all elements of an array match the given boolean callback.
|
|
*
|
|
* @param callable<mixed, ?mixed> $callback The callback function to call to check each element. If this function
|
|
* returns `false`, `false` is returned and the callback will not be called for further elements.
|
|
* @return callable<array, array> A function that calls `array_all` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-all.php `array_all` Documentation
|
|
*/
|
|
public static function all(callable $callback): callable
|
|
{
|
|
return fn (array $array) => array_all($array, $callback);
|
|
}
|
|
|
|
/**
|
|
* Determine if any elements of an array match the given boolean callback.
|
|
*
|
|
* @param callable<mixed, ?mixed> $callback The callback function to call to check each element. If this function
|
|
* returns `true`, `true` is returned and the callback will not be called for further elements.
|
|
* @return callable<array, array> A function that calls `array_any` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-any.php array_any Documentation
|
|
*/
|
|
public static function any(callable $callback): callable
|
|
{
|
|
return fn (array $array) => array_any($array, $callback);
|
|
}
|
|
|
|
/**
|
|
* Returns an array with all keys from array lowercased or uppercased. Numbered indices are left as is.
|
|
*
|
|
* @param int $case Either `CASE_UPPER` or `CASE_LOWER` (default)
|
|
* @return callable<array, array> A function that calls `array_change_key_case` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-change-key-case.php array_change_key_case Documentation
|
|
*/
|
|
public static function changeKeyCase(int $case = CASE_LOWER): callable
|
|
{
|
|
return fn (array $array) => array_change_key_case($array, $case);
|
|
}
|
|
|
|
/**
|
|
* Chunks an array into arrays with `$length` elements. The last chunk may contain less than `$length` elements.
|
|
*
|
|
* @param int $length The size of each chunk.
|
|
* @param bool $preserveKeys When set to `true` keys will be preserved. Default is `false` which will reindex the
|
|
* chunk numerically.
|
|
* @return callable<array, array<array>> A function that calls `array_chunk` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-chunk.php array_chunk Documentation
|
|
*/
|
|
public static function chunk(int $length, bool $preserveKeys = false): callable
|
|
{
|
|
return fn (array $array) => array_chunk($array, $length, $preserveKeys);
|
|
}
|
|
|
|
/**
|
|
* Returns the values from a single column of the array, identified by the `$columnKey`. Optionally, an `$indexKey`
|
|
* may be provided to index the values in the returned array by the values from the `$indexKey` column of the input
|
|
* array.
|
|
*
|
|
* @param int|string|null $columnKey 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 `$indexKey` to reindex the
|
|
* array).
|
|
* @param int|string|null $indexKey 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.
|
|
* @return callable A function that calls `array_column` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-column.php array_column Documentation
|
|
*/
|
|
public static function column(int|string|null $columnKey, int|string|null $indexKey = null): callable
|
|
{
|
|
return fn (array $array) => array_column($array, $columnKey, $indexKey);
|
|
}
|
|
|
|
/**
|
|
* Counts the occurrences of each distinct value in an array.
|
|
*
|
|
* @return callable<array<mixed, int|string>, array<int|string, int>> A function that calls `array_count` with the
|
|
* given array.
|
|
* @see https://www.php.net/manual/en/function.array-count-values.php array_count_values Documentation
|
|
*/
|
|
public static function countValues(): callable
|
|
{
|
|
return array_count_values(...);
|
|
}
|
|
|
|
/**
|
|
* Compares `$array` against one or more other arrays and returns the values in `$array` that are not present in any
|
|
* of the other arrays.
|
|
*
|
|
* @param array ...$arrays The arrays against which the comparison should be made
|
|
* @return callable<array, array> A function that calls `array_diff` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-diff.php array_diff Documentation
|
|
*/
|
|
public static function diff(array ...$arrays): callable
|
|
{
|
|
return fn (array $array) => array_diff($array, ...$arrays);
|
|
}
|
|
|
|
/**
|
|
* Compares `$array` against `$arrays` and returns the difference. Unlike `Arr::diff()`, the array keys are also
|
|
* used in the comparison.
|
|
*
|
|
* @param array ...$arrays The arrays against which the comparison should be made
|
|
* @return callable<array, array> A function that calls `array_diff_assoc` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-diff-assoc.php array_diff_assoc Documentation
|
|
*/
|
|
public static function diffAssoc(array ...$arrays): callable
|
|
{
|
|
return fn (array $array) => array_diff_assoc($array, ...$arrays);
|
|
}
|
|
|
|
/**
|
|
* Compares the keys from `$array` against the keys from `$arrays` and returns the difference. This function is like
|
|
* `Arr::diff()`, except the comparison is done on the keys instead of the values.
|
|
*
|
|
* @param array ...$arrays The arrays against which the comparison should be made
|
|
* @return callable<array, array> A function that calls `array_diff_key` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-diff-key.php array_diff_key Documentation
|
|
*/
|
|
public static function diffKey(array ...$arrays): callable
|
|
{
|
|
return fn (array $array) => array_diff_key($array, ...$arrays);
|
|
}
|
|
|
|
/**
|
|
* Compares `$array` against `$arrays` and returns the difference. Unlike `Arr::diff()`, the array keys are also
|
|
* used in the comparison. Unlike `Arr::diffAssoc()`, a user supplied callback function is used for the indices
|
|
* comparison, not internal function.
|
|
*
|
|
* @param callable<mixed, mixed, int> $keyCompareFunc 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.
|
|
* @param array ...$arrays The arrays against which the comparison should be made
|
|
* @return callable<array, array> A function that calls `array_diff_assoc` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-diff-assoc.php array_diff_assoc Documentation
|
|
*/
|
|
public static function diffUAssoc(callable $keyCompareFunc, array ...$arrays): callable
|
|
{
|
|
return fn (array $array) => array_diff_uassoc($array, $arrays, $keyCompareFunc);
|
|
}
|
|
|
|
/**
|
|
* Transform each element of an array to a different element (optionally merging other mapped arrays).
|
|
*
|
|
* @param callable|null $callback A callable to run for each element in each array.<br><br>
|
|
* `null` can be passed as a value to `$callback` to perform a zip operation on multiple arrays and return
|
|
* an array where each element is an array containing the elements from the input arrays at the same position of
|
|
* the internal array pointer. If only array is provided, `Arr::map()` will return the input array.
|
|
* @param array ...$arrays Supplementary variable list of array arguments to run through the callback function.
|
|
* @return callable<array, array> A function that calls `array_map` with the given array.
|
|
* @see https://www.php.net/manual/en/function.array-map.php array_map Documentation
|
|
*/
|
|
public static function map(?callable $callback, array ...$arrays): callable
|
|
{
|
|
return fn (array $array) => array_map($callback, $array, ...$arrays);
|
|
}
|
|
|
|
/**
|
|
* @throws Exception This class should not be constructed
|
|
*/
|
|
private function __construct()
|
|
{
|
|
throw new Exception('This is a static class; do not instantiate it');
|
|
}
|
|
}
|