Iterables: $else [WIP]

src/Utils/Iterables.php

@@ -48,38 +48,38 @@ public static function containsKey(iterable $iterable, mixed $key): bool
 
 
 	/**
-	 * Returns the first item (matching the specified predicate if given) or null if there is no such item.
-	 * The callback has the signature `function ($value, $key, $iterable): bool`.
+	 * Returns the first item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
+	 * The $predicate has the signature `function ($value, $key, $iterable): bool`.
 	 * @template T
 	 * @param  iterable<T>  $iterable
 	 * @return ?T
 	 */
-	public static function first(iterable $iterable, ?callable $predicate = null): mixed
+	public static function first(iterable $iterable, ?callable $predicate = null, ?callable $else = null): mixed
 	{
 		foreach ($iterable as $k => $v) {
 			if (!$predicate || $predicate($v, $k, $iterable)) {
 				return $v;
 			}
 		}
-		return null;
+		return $else ? $else() : null;
 	}
 
 
 	/**
-	 * Returns the key of first item (matching the specified predicate if given) or null if there is no such item.
-	 * The callback has the signature `function ($value, $key, $iterable): bool`.
+	 * Returns the key of first item (matching the specified predicate if given). If there is no such item, it returns result of invoking $else or null.
+	 * The $predicate has the signature `function ($value, $key, $iterable): bool`.
 	 * @template T
 	 * @param  iterable<T, mixed>  $iterable
 	 * @return ?T
 	 */
-	public static function firstKey(iterable $iterable, ?callable $predicate = null): mixed
+	public static function firstKey(iterable $iterable, ?callable $predicate = null, ?callable $else = null): mixed
 	{
 		foreach ($iterable as $k => $v) {
 			if (!$predicate || $predicate($v, $k, $iterable)) {
 				return $k;
 			}
 		}
-		return null;
+		return $else ? $else() : null;
 	}
 
 

tests/Utils/Iterables.first().phpt

@@ -37,3 +37,7 @@ test('with predicate', function () {
 test('predicate arguments', function () {
 	Iterables::first([2 => 'x'], fn() => Assert::same(['x', 2, [2 => 'x']], func_get_args()));
 });
+
+test('else', function () {
+	Assert::same(123, Iterables::first(new ArrayIterator([]), else: fn() => 123));
+});

tests/Utils/Iterables.firstKey().phpt

@@ -37,3 +37,7 @@ test('with predicate', function () {
 test('predicate arguments', function () {
 	Iterables::firstKey([2 => 'x'], fn() => Assert::same(['x', 2, [2 => 'x']], func_get_args()));
 });
+
+test('else', function () {
+	Assert::same(123, Iterables::firstKey(new ArrayIterator([]), else: fn() => 123));
+});