Feature proposal: add new function \iter\tap

[athrawes]

Quite often when I'm in the middle of a pipeline of iterators, I would like to examine the current values coming through the pipeline without modifying them.

For example, I might want to log an intermediate result of the pipeline. One could abuse \iter\map to take items from the iterator, perform side effects, and return the items without modification; however, this is somewhat unwieldy:

$_ = \iter\map(doSomething(...), $queue);
$_ = \iter\map(
    function ($item) use ($logger) {
        $logger->info("did something with $item");
        return $item;
    },
    $_
);
$_ = \iter\map(doSomethingWithPreviousValues(...), $_);

As such, I'd like to propose a new function \iter\tap() which takes a callback and an iterable.
For each item in the iterable, it would call the callback with the item but return the item as passed to tap.

$_ = \iter\map(doSomething(...), $queue);
$_ = \iter\tap(fn ($item): void => $logger->info("did something with $item"), $_);
$_ = \iter\map(doSomethingWithPreviousValues(...), $_);

This would be similar in spirit to RxJS's tap function or the Java Stream.peek method

See #95

[nikic]

This has been implemented in #95, and I just created a release for it, so closing this issue.