added Arrays::firstKey(), lastKey()

Author: dg

src/Utils/Arrays.php

@@ -154,8 +154,9 @@ public static function last(array $array, ?callable $predicate = null): mixed
 
 	/**
 	 * Returns the key of first matching item the specified predicate or null if there is no such item.
+	 * The callback has the signature `function ($value, $key, $array): bool`.
 	 */
-	private static function firstKey(array $array, callable $predicate): int|string|null
+	public static function firstKey(array $array, callable $predicate): int|string|null
 	{
 		foreach ($array as $k => $v) {
 			if ($predicate($v, $k, $array)) {
@@ -166,6 +167,16 @@ private static function firstKey(array $array, callable $predicate): int|string|
 	}
 
 
+	/**
+	 * Returns the key of last matching item the specified predicate or null if there is no such item.
+	 * The callback has the signature `function ($value, $key, $array): bool`.
+	 */
+	public static function lastKey(array $array, callable $predicate): int|string|null
+	{
+		return self::firstKey(array_reverse($array, preserve_keys: true), $predicate);
+	}
+
+
 	/**
 	 * Inserts the contents of the $inserted array into the $array immediately after the $key.
 	 * If $key is null (or does not exist), it is inserted at the beginning.

tests/Utils/Arrays.firstKey().phpt

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+use Nette\Utils\Arrays;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+test('internal array pointer is not affected', function () {
+	$arr = [1, 2, 3];
+	end($arr);
+	Assert::null(Arrays::firstKey($arr, fn() => false));
+	Assert::same(3, current($arr));
+});
+
+test('with predicate', function () {
+	Assert::null(Arrays::firstKey([], fn() => true));
+	Assert::null(Arrays::firstKey([], fn() => false));
+	Assert::null(Arrays::firstKey(['' => 'x'], fn() => false));
+	Assert::same(0, Arrays::firstKey([null], fn() => true));
+	Assert::null(Arrays::firstKey([null], fn() => false));
+	Assert::same(0, Arrays::firstKey([1, 2, 3], fn() => true));
+	Assert::null(Arrays::firstKey([1, 2, 3], fn() => false));
+	Assert::same(2, Arrays::firstKey([1, 2, 3], fn($v) => $v > 2));
+	Assert::same(0, Arrays::firstKey([1, 2, 3], fn($v) => $v < 2));
+});
+
+test('predicate arguments', function () {
+	Arrays::firstKey([2 => 'x'], fn() => Assert::same(['x', 2, [2 => 'x']], func_get_args()));
+});

tests/Utils/Arrays.lastKey().phpt

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+use Nette\Utils\Arrays;
+use Tester\Assert;
+
+require __DIR__ . '/../bootstrap.php';
+
+
+test('internal array pointer is not affected', function () {
+	$arr = [1, 2, 3];
+	Assert::same(2, Arrays::lastKey($arr, fn() => true));
+	Assert::same(1, current($arr));
+});
+
+test('with predicate', function () {
+	Assert::null(Arrays::lastKey([], fn() => true));
+	Assert::null(Arrays::lastKey([], fn() => false));
+	Assert::null(Arrays::lastKey(['' => 'x'], fn() => false));
+	Assert::same(0, Arrays::lastKey([null], fn() => true));
+	Assert::null(Arrays::lastKey([null], fn() => false));
+	Assert::same(2, Arrays::lastKey([1, 2, 3], fn() => true));
+	Assert::null(Arrays::lastKey([1, 2, 3], fn() => false));
+	Assert::same(2, Arrays::lastKey([1, 2, 3], fn($v) => $v > 2));
+	Assert::same(0, Arrays::lastKey([1, 2, 3], fn($v) => $v < 2));
+});
+
+test('predicate arguments', function () {
+	Arrays::lastKey([2 => 'x'], fn() => Assert::same(['x', 2, [2 => 'x']], func_get_args()));
+});