The filter (or stream filter) is a streaming pattern that discards items from a data stream based on a predicate, so that only data items satisfying (keep) or dissatisfying (discard) the predicate are passed to the next stage. This streaming pattern can only be used inside another pattern and consequently does not take an execution policy itself, but uses the execution policy of its enclosing pattern.

The interface to the filter pattern is provided by functions grppi::keep() and grppi::discard().

grppi::pipeline(exec,
  stage1,
  grppi::keep(predicate1),
  grppi::discard(predicate2),
  stage3,
  stage4);

Stream filter variants

There is a single variant:

Composable filter: Defines a filter that can be used as a building block by another pattern (e.g. a pipeline).

Key elements in stream filter

The central element in a filter is the Predicate. The operation may be any C++ callable entity. This operation, is a unary operation taking a data item and returning value that is contextually convertible to bool. Thus, a predicate pred is any operation, that given a value x of type T, makes the following valid:

if (predicate(item)) { /*...*/ }.

if (!predicate(item)) { /*...*/ }.

Details on stream filter variants

Composable filter

A composable filter has a single element:

A Predicate filtering values.

The input values will be generated by the upper level pattern, which will be also responsible for consuming the output values.

Example: A filter stage in a pipeline.

grppi::pipeline(exec,
  stageA,
  stageB,
  grppi::keep([](auto x) { return x.lenght()>4; }),
  stageC
  );

Note: For brevity we do not show here the details of other stages.

For composing complex patterns, the keep() and discard() functions may be used to create an object that may be supplied to another pattern to build a composed pattern.

Example: A composable filter stage in a pipeline.

auto keep_odd = grppi::keep(
  [](auto x) { return x%2; });
 
grppi::pipeline(exec,
  stageA,
  stageB,
  keep_odd,
  stageC
  );

Note: For brevity we do not show here the details of other stages.