WIP on pipeable array functions

src/Arr.php

@@ -0,0 +1,129 @@
+<?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(...);
+    }
+
+    /**
+     * 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');
+    }
+}