View source code Display the source code in std/range.d from which this page was generated on github. Improve this page Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone. Page wiki View or edit the community-maintained wiki page associated with this page.

Function std.range.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.reduce.

Prototypes

auto tee(std.typecons.Flag!("pipeOnPop").Flag pipeOnPop, R1, R2)(
  R1 inputRange,
  R2 outputRange
)
if (isInputRange!R1 && isOutputRange!(R2, ElementType!R1));

auto tee(alias fun, std.typecons.Flag!("pipeOnPop").Flag pipeOnPop, R1)(
  R1 inputRange
)
if (is(typeof(fun) == void) || isSomeFunction!fun);

Parameters

NameDescription
pipeOnPop If Yes.pipeOnPop, simply iterating the range without ever calling front is enough to have tee mirror elements to outputRange (or, respectively, fun). If No.pipeOnPop, only elements for which front does get called will be also sent to outputRange/fun.
inputRange The input range beeing passed through.
outputRange This range will receive elements of inputRange progressively as iteration proceeds.
fun This function will be called with elements of inputRange progressively as iteration proceeds.

Returns

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.

See Also

std.algorithm.iteration.each

Example

import std.algorithm : equal, 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 newValues3
assert(equal(newValues4, [2, 5]));
assert(count == 3);

Authors

Andrei Alexandrescu, David Simcha, and Jonathan M Davis. Credit for some of the ideas in building this module goes to Leonardo Maffi.

License

Boost License 1.0.

Comments