{

private const int ROW_MEMBERSHIP_LOOKUP_MIN_VALUES = 256;

/**

public static function between(array $array, string $key, float|int $from, float|int $to): array

{

$results = [];

foreach ($array as $index => $item) {

if (

is_array($item)

&& ArraySingle::exists($item, $key)

&& compare($item[$key], $from, '>=')

&& compare($item[$key], $to, '<=')

) {

$results[$index] = $item;

}

}

return $results;

}

/**

public static function countBy(array $array, string|callable $groupBy): array

{

$counts = [];

$useCallback = !is_string($groupBy);

foreach ($array as $key => $row) {

if (!$useCallback && (!is_array($row) || !array_key_exists($groupBy, $row))) {

continue;

}

$bucket = $useCallback ? $groupBy($row, $key) : $row[$groupBy];

$arrayKey = self::requireArrayKey($bucket, 'countBy');

$counts[$arrayKey] = ($counts[$arrayKey] ?? 0) + 1;

}

return $counts;

}

/**

public static function duplicatesBy(array $array, string|callable $keyOrCallback, bool $strict = false): array

{

return self::collectByDerivedKey($array, $keyOrCallback, $strict, keepDuplicates: true);

}

/**

public static function firstWhere(

array $array,

string $key,

mixed $operator = null,

mixed $value = null,

mixed $default = null,

): mixed {

if (func_num_args() === 3) {

$value = $operator;

$operator = null;

}

$operator = is_string($operator) ? $operator : null;

foreach ($array as $row) {

if (

is_array($row)

&& ArraySingle::exists($row, $key)

&& compare($row[$key], $value, $operator)

) {

return $row;

}

}

return $default;

}

/**

public static function firstWhereIn(array $array, string $key, array $values, bool $strict = false, mixed $default = null): mixed

{

$lookup = self::buildInLookup($values, $strict);

if ($lookup === null) {

return self::firstWhereInByScan($array, $key, $values, $strict, $default);

}

foreach ($array as $row) {

if (!is_array($row) || !array_key_exists($key, $row)) {

continue;

}

if (self::rowLookupContains($lookup, $values, $row[$key], $strict)) {

return $row;

}

}

return $default;

}

/**

public static function groupBy(array $array, string|callable $groupBy, bool $preserveKeys = false): array

{

$results = [];

$useCallback = !is_string($groupBy);

foreach ($array as $key => $row) {

if (!$useCallback && (!is_array($row) || !array_key_exists($groupBy, $row))) {

continue;

}

$resolved = $useCallback ? $groupBy($row, $key) : $row[$groupBy];

$groupKey = self::requireArrayKey($resolved, 'groupBy');

if ($preserveKeys) {

$results[$groupKey][$key] = $row;

} else {

$results[$groupKey][] = $row;

}

}

return $results;

}

/**

public static function indexBy(array $array, string|callable $indexBy): array

{

return static::keyBy($array, $indexBy);

}

/**

public static function keyBy(array $array, string|callable $keyBy): array

{

$results = [];

$useCallback = !is_string($keyBy);

foreach ($array as $index => $row) {

if (!$useCallback && (!is_array($row) || !array_key_exists($keyBy, $row))) {

continue;

}

$resolved = $useCallback ? $keyBy($row, $index) : $row[$keyBy];

$results[self::requireArrayKey($resolved, 'keyBy')] = $row;

}

return $results;

}

/**

public static function last(array $array, ?callable $callback = null, mixed $default = null): mixed

{

if ($callback === null) {

return empty($array) ? $default : end($array);

}

$resolved = $default;

foreach ($array as $key => $row) {

if ($callback($row, $key)) {

$resolved = $row;

}

}

return $resolved;

}

/**

public static function mapWithKeys(array $array, callable $callback): array

{

$results = [];

foreach ($array as $key => $row) {

$mapped = $callback($row, $key);

if (!is_array($mapped)) {

continue;

}

foreach ($mapped as $mappedKey => $mappedValue) {

$results[$mappedKey] = $mappedValue;

}

}

return $results;

}

/**

public static function max(array $array, string|callable $keyOrCallback): float|int|null

{

return self::formatNumericResult(

self::selectExtremeValue($array, $keyOrCallback, pickMax: true),

);

}

/**

public static function maxBy(array $array, string|callable $keyOrCallback): mixed

{

return self::selectExtremeRow($array, $keyOrCallback, pickMax: true);

}

/**

public static function min(array $array, string|callable $keyOrCallback): float|int|null

{

return self::formatNumericResult(

self::selectExtremeValue($array, $keyOrCallback, pickMax: false),

);

}

/**

public static function minBy(array $array, string|callable $keyOrCallback): mixed

{

return self::selectExtremeRow($array, $keyOrCallback, pickMax: false);

}

/**

public static function pluck(array $array, string $column, ?string $indexBy = null): array

{

$results = [];

foreach ($array as $row) {

if (!is_array($row) || !array_key_exists($column, $row)) {

continue;

}

$value = $row[$column];

if ($indexBy === null) {

$results[] = $value;

continue;

}

if (array_key_exists($indexBy, $row)) {

$results[self::requireArrayKey($row[$indexBy], 'pluck')] = $value;

}

}

return $results;

}

/**

public static function reject(array $array, mixed $callback = true): array

{

$results = [];

if (!is_string($callback) && is_callable($callback)) {

foreach ($array as $key => $row) {

if (!$callback($row, $key)) {

$results[$key] = $row;

}

}

return $results;

}

foreach ($array as $key => $row) {

if ($row != $callback) {

$results[$key] = $row;

}

}

return $results;

}

/**

public static function some(array $array, callable $callback): bool

{

return array_any($array, $callback);

}

/**

public static function sortBy(

array $array,

string|callable $by,

bool $desc = false,

int $options = \SORT_REGULAR,

): array {

if (!is_string($by)) {

$scores = [];

foreach ($array as $key => $row) {

$scores[$key] = self::invokeRowCallback($by, $row, $key);

}

uksort(

$array,

static function (int|string $leftKey, int|string $rightKey) use ($scores, $desc, $options): int {

$comparison = self::compareSortValues(

$scores[$leftKey] ?? null,

$scores[$rightKey] ?? null,

$options,

);

return self::applySortDirection($comparison, $desc);

},

);

return $array;

}

uasort($array, function ($a, $b) use ($by, $desc, $options) {

$valA = is_array($a) ? ($a[$by] ?? null) : null;

$valB = is_array($b) ? ($b[$by] ?? null) : null;

return self::applySortDirection(

self::compareSortValues($valA, $valB, $options),

$desc,

);

});

return $array;

}

/**

public static function sortByDesc(array $array, string|callable $by, int $options = \SORT_REGULAR): array

{

return static::sortBy($array, $by, true, $options);

}

/**

public static function sortByMany(array $array, array $criteria): array

{

if ($criteria === []) {

return $array;

}

$prepared = self::prepareSortByManyCriteria($array, $criteria);

uksort(

$array,

static fn(int|string $leftKey, int|string $rightKey): int => self::compareByManyCriteria(

$leftKey,

$rightKey,

$prepared,

),

);

return $array;

}

/**

public static function sortRecursive(array $array, int $options = \SORT_REGULAR, bool $descending = false): array

{

foreach ($array as &$value) {

if (is_array($value)) {

$value = static::sortRecursive($value, $options, $descending);

}

}

unset($value);

if (ArraySingle::isAssoc($array)) {

$descending

? krsort($array, $options)

: ksort($array, $options);

} else {

usort(

$array,

static fn(mixed $left, mixed $right): int => $descending

? -self::compareSortValues($left, $right, $options)

: self::compareSortValues($left, $right, $options),

);

}

return $array;

}

/**

public static function sortRecursiveGuarded(

array $array,

int $options = \SORT_REGULAR,

bool $descending = false,

int $maxDepth = 256,

int $maxNodes = 100000,

bool $throwOnTooDeep = false,

): array {

$visitedNodes = 0;

$complete = true;

return self::sortRecursiveWithGuards(

$array,

$options,

$descending,

1,

$visitedNodes,

$maxDepth,

$maxNodes,

$throwOnTooDeep,

$complete,

);

}

/**

public static function sum(array $array, string|callable|null $keyOrCallback = null): float|int

{

$total = 0;

foreach ($array as $key => $row) {

$total += self::extractSummableValue($row, $keyOrCallback, $key);

}

return $total;

}

/**

public static function uniqueBy(array $array, string|callable $keyOrCallback, bool $strict = false): array

{

return self::collectByDerivedKey($array, $keyOrCallback, $strict, keepDuplicates: false);

}

/**

public static function where(array $array, string $key, mixed $operator = null, mixed $value = null): array

{

if (func_num_args() === 3) {

$value = $operator;

$operator = null;

}

$operator = is_string($operator) ? $operator : null;

$results = [];

foreach ($array as $index => $item) {

if (

is_array($item)

&& ArraySingle::exists($item, $key)

&& compare($item[$key], $value, $operator)

) {

$results[$index] = $item;

}

}

return $results;

}

/**

public static function whereBetween(array $array, string $key, float|int $from, float|int $to): array

{

return self::between($array, $key, $from, $to);

}

/**

public static function whereCallback(array $array, ?callable $callback = null, mixed $default = null): mixed

{

if ($callback === null) {

return empty($array) ? $default : $array;

}

$results = [];

foreach ($array as $index => $item) {

if ((bool) $callback($item, $index)) {

$results[$index] = $item;

}

}

return $results;

}

/**

public static function whereContains(array $array, string $key, string $needle, bool $caseSensitive = true): array

{

$match = $caseSensitive ? $needle : strtolower($needle);

return self::filterByTextMatch(

$array,

$key,

static fn(string $text): bool => str_contains($caseSensitive ? $text : strtolower($text), $match),

);

}

/**

public static function whereEndsWith(array $array, string $key, string $suffix, bool $caseSensitive = true): array

{

$needle = $caseSensitive ? $suffix : strtolower($suffix);

return self::filterByTextMatch(

$array,

$key,

static fn(string $text): bool => str_ends_with($caseSensitive ? $text : strtolower($text), $needle),

);

}

/**

public static function whereIn(array $array, string $key, array $values, bool $strict = false): array

{

$results = [];

$lookup = self::buildInLookup($values, $strict);

if ($lookup === null) {

return self::whereInByScan($array, $key, $values, $strict, true);

}

foreach ($array as $index => $row) {

if (!is_array($row) || !array_key_exists($key, $row)) {

continue;

}

if (self::rowLookupContains($lookup, $values, $row[$key], $strict)) {

$results[$index] = $row;

}

}

return $results;

}

/**

public static function whereLike(array $array, string $key, string $pattern, bool $caseSensitive = false): array

{

$quoted = preg_quote($pattern, '/');

$regex = '/\\A' . str_replace(['%', '_'], ['.*', '.'], $quoted) . '\\z/s' . ($caseSensitive ? '' : 'i');

$results = [];

foreach ($array as $index => $row) {

if (!is_array($row) || !array_key_exists($key, $row)) {

continue;

}

$value = $row[$key];

if (!is_scalar($value) && $value !== null) {

continue;

}

$matched = preg_match($regex, (string) $value);

if ($matched === false) {

throw new \RuntimeException('SQL-like pattern matching failed: ' . preg_last_error_msg());

}

if ($matched === 1) {

$results[$index] = $row;

}

}

return $results;

}

/**

public static function whereNotIn(array $array, string $key, array $values, bool $strict = false): array

{

$results = [];

$lookup = self::buildInLookup($values, $strict);

if ($lookup === null) {

return self::whereInByScan($array, $key, $values, $strict, false);

}

foreach ($array as $index => $row) {

if (!is_array($row) || !array_key_exists($key, $row)) {

$results[$index] = $row;

continue;

}

if (!self::rowLookupContains($lookup, $values, $row[$key], $strict)) {

$results[$index] = $row;

}

}

return $results;

}

/**

public static function whereNotNull(array $array, string $key): array

{

return self::filterByNullState($array, $key, expectNull: false);

}

/**

public static function whereNull(array $array, string $key): array

{

return self::filterByNullState($array, $key, expectNull: true);

}

/**

public static function whereStartsWith(array $array, string $key, string $prefix, bool $caseSensitive = true): array

{

$needle = $caseSensitive ? $prefix : strtolower($prefix);

return self::filterByTextMatch(

$array,

$key,

static fn(string $text): bool => str_starts_with($caseSensitive ? $text : strtolower($text), $needle),

);

}

private static function applySortDirection(int $comparison, bool $desc): int

{

return $desc ? -$comparison : $comparison;

}

private static function asNumeric(mixed $value): float|int

{

return ArraySingleOps::numericValue($value) ?? 0;

}

private static function asString(mixed $value): string

{

return ArraySharedOps::asString($value);

}

/**

private static function buildInLookup(array $values, bool $strict): ?array

{

if (count($values) < self::ROW_MEMBERSHIP_LOOKUP_MIN_VALUES) {

return null;

}

if ($strict) {

return ArrayValueSetOps::strictLookup($values);

}

$lookup = ['type:non-numeric-string' => true];

foreach ($values as $value) {

if (!is_string($value) || is_numeric($value)) {

return null;

}

$lookup['value:' . strlen($value) . ':' . $value] = true;

}

return $lookup;

}

/**

private static function collectByDerivedKey(

array $array,

string|callable $keyOrCallback,

bool $strict,

bool $keepDuplicates,

): array {

if (!$strict) {

return self::collectByDerivedKeyLoose($array, $keyOrCallback, $keepDuplicates);

}

return self::collectByDerivedKeyStrict($array, $keyOrCallback, $keepDuplicates);

}

/**

private static function collectByDerivedKeyLoose(

array $array,

string|callable $keyOrCallback,

bool $keepDuplicates,

): array {

$results = [];

$seen = [];

foreach ($array as $index => $row) {

if (is_string($keyOrCallback)) {

if (!is_array($row) || !array_key_exists($keyOrCallback, $row)) {

continue;

}

$derived = $row[$keyOrCallback];

} else {

$derived = self::invokeRowCallback($keyOrCallback, $row, $index);

}

$alreadySeen = in_array($derived, $seen, false);

if ($alreadySeen === $keepDuplicates) {

$results[$index] = $row;

}

if (!$alreadySeen) {

$seen[] = $derived;

}

}

return $results;

}

/**

private static function collectByDerivedKeyStrict(

array $array,

string|callable $keyOrCallback,

bool $keepDuplicates,

): array {

$results = [];

$seen = [];

$digestBuckets = [];

$fallback = [];

foreach ($array as $index => $row) {

if (is_string($keyOrCallback)) {

if (!is_array($row) || !array_key_exists($keyOrCallback, $row)) {

continue;

}

$derived = $row[$keyOrCallback];

} else {

$derived = self::invokeRowCallback($keyOrCallback, $row, $index);

}

$alreadySeen = ArrayValueSetOps::strictValueAlreadySeen(

$derived,

$seen,

$digestBuckets,

$fallback,

);

if ($alreadySeen === $keepDuplicates) {

$results[$index] = $row;

}

}

return $results;

}

/**

private static function compareByManyCriteria(int|string $leftKey, int|string $rightKey, array $criteria): int

{

foreach ($criteria as $criterion) {

$leftValue = $criterion['values'][$leftKey];

$rightValue = $criterion['values'][$rightKey];

$comparison = self::compareSortValues($leftValue, $rightValue, $criterion['options']);

if ($comparison !== 0) {

return self::applySortDirection($comparison, $criterion['desc']);

}

}

return 0;

}

/**

private static function compareSortValues(mixed $left, mixed $right, int $options): int

{

if ($left === $right) {

return 0;

}

$caseInsensitive = (bool) ($options & \SORT_FLAG_CASE);

$baseOption = $options & ~\SORT_FLAG_CASE;

return match ($baseOption) {

\SORT_NUMERIC => self::asNumeric($left) <=> self::asNumeric($right),

\SORT_STRING => $caseInsensitive

? strcasecmp(self::asString($left), self::asString($right))

: strcmp(self::asString($left), self::asString($right)),

\SORT_NATURAL => $caseInsensitive

? strnatcasecmp(self::asString($left), self::asString($right))

: strnatcmp(self::asString($left), self::asString($right)),

\SORT_LOCALE_STRING => strcoll(self::asString($left), self::asString($right)),

default => $left <=> $right,

};

}

private static function extractComparableValue(mixed $row, string|callable $keyOrCallback, int|string $key): float|int|null

{

if (!is_string($keyOrCallback)) {

$result = self::invokeRowCallback($keyOrCallback, $row, $key);

return ArraySingleOps::numericValue($result);

}

if (is_array($row) && array_key_exists($keyOrCallback, $row)) {

return ArraySingleOps::numericValue($row[$keyOrCallback]);

}

return null;

}

private static function extractRowTextValue(mixed $row, string $key): ?string

{

if (!is_array($row) || !array_key_exists($key, $row)) {

return null;

}

$value = $row[$key];

if (!is_scalar($value) && $value !== null) {

return null;

}

return (string) $value;

}

private static function extractSummableValue(mixed $row, string|callable|null $keyOrCallback, int|string $key): float|int

{

if ($keyOrCallback === null) {

return ArraySingleOps::numericValue($row) ?? 0;

}

if (!is_string($keyOrCallback)) {

$result = self::invokeRowCallback($keyOrCallback, $row, $key);

return ArraySingleOps::numericValue($result) ?? 0;

}

if (is_array($row) && isset($row[$keyOrCallback])) {

return ArraySingleOps::numericValue($row[$keyOrCallback]) ?? 0;

}

return 0;

}

/**

private static function filterByNullState(array $array, string $key, bool $expectNull): array

{

$results = [];

foreach ($array as $index => $row) {

if (!is_array($row) || !array_key_exists($key, $row)) {

continue;

}

$isNull = $row[$key] === null;

if (($expectNull && $isNull) || (!$expectNull && !$isNull)) {

$results[$index] = $row;

}

}

return $results;

}

/**