tee

Implements a "tee" style pipe, wrapping an input range so that elements of the range can be passed to a provided function or OutputRange as they are iterated over. This is useful for printing out intermediate values in a long chain of range code, performing some operation with side-effects on each call to front or popFront, or diverting the elements of a range into an auxiliary OutputRange.

It is important to note that as the resultant range is evaluated lazily, in the case of the version of tee that takes a function, the function will not actually be executed until the range is "walked" using functions that evaluate ranges, such as std.array.array or std.algorithm.iteration.fold.

  1. auto tee(R1 inputRange, R2 outputRange)
    tee
    (
    Flag!"pipeOnPop" pipeOnPop = Yes.pipeOnPop
    R1
    R2
    )
    if (
    isInputRange!R1 &&
    isOutputRange!(R2, ElementType!R1)
    )
  2. auto tee(R1 inputRange)

Parameters

pipeOnPop

If Yes.pipeOnPop, simply iterating the range without ever calling front is enough to have tee mirror elements to outputRange (or, respectively, fun). Note that each popFront() call will mirror the old front value, not the new one. This means that the last value will not be forwarded if the range isn't iterated until empty. If No.pipeOnPop, only elements for which front does get called will be also sent to outputRange/fun. If front is called twice for the same element, it will still be sent only once. If this caching is undesired, consider using std.algorithm.iteration.map instead.

inputRange R1

The input range being passed through.

outputRange R2

This range will receive elements of inputRange progressively as iteration proceeds.

Return Value

Type: auto

An input range that offers the elements of inputRange. Regardless of whether inputRange is a more powerful range (forward, bidirectional etc), the result is always an input range. Reading this causes inputRange to be iterated and returns its elements in turn. In addition, the same elements will be passed to outputRange or fun as well.

Examples

import std.algorithm.comparison : equal;
import std.algorithm.iteration : filter, map;

// Sum values while copying
int[] values = [1, 4, 9, 16, 25];
int sum = 0;
auto newValues = values.tee!(a => sum += a).array;
assert(equal(newValues, values));
assert(sum == 1 + 4 + 9 + 16 + 25);

// Count values that pass the first filter
int count = 0;
auto newValues4 = values.filter!(a => a < 10)
                        .tee!(a => count++)
                        .map!(a => a + 1)
                        .filter!(a => a < 10);

//Fine, equal also evaluates any lazy ranges passed to it.
//count is not 3 until equal evaluates newValues4
assert(equal(newValues4, [2, 5]));
assert(count == 3);

See Also

Meta