Arrays\head()

Home >> Arrays >> Arrays\head()
reducer short-circuit accepts iterable returns value pure
Iterable → T | null
At a glance — Direct call — not a Closure constructor. Pulls one value from the source, then stops. Safe with infinite Generators.

Returns the first value of an array or iterable, or null if the source is empty. For Generators this is a genuine early-exit — the rest of the stream is not consumed. 

/**
  * @param iterable<int|string, mixed> $source
  * @return mixed The first value, or null if empty.
  */
Arrays\head(iterable $source)

Examples

Partial Application

This can be used to create a simple closure which can be used as a regular function. 

// Called directly with an array.
var_dump(Arrays\head(['a', 'b', 'c'])); // 'a'
var_dump(Arrays\head([]));              // NULL

Works with Iterables & Generators

Accepts a Generator or any Traversable as input. 

// A Generator source — head stops pulling after the first value.
$numbers = (function () {
    echo "yielded 1\n"; yield 1;
    echo "yielded 2\n"; yield 2;
    echo "yielded 3\n"; yield 3;
})();

echo Arrays\head($numbers);

// Output:
// yielded 1
// 1

// Values 2 and 3 are never produced.

Details

Arrays Functions

Releated Array access Functions