<?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');
    }
}