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));
+});