#include "lib/iter-explorer.hpp"

Description

template<class SRC>
class lib::IterExplorer< SRC >

Adapter to build a demand-driven tree expanding and exploring computation based on a custom opaque state core.

TreeExploer adheres to the Monad pattern known from functional programming, insofar the expansion step is tied into the basic template by means of a function provided at usage site. This allows to separate the mechanics of evaluation and result combination from the actual processing and thus to define tree structured computations based on an opaque source data structure not further disclosed.

Template Parameters

SRC	a suitably adapted source iterator or state core, wrapped into an instance of the iter_explorer::BaseAdapter template

usage

IterExplorer is meant to be used as Builder for a processing pipeline. For this to work, it is essential to pick the SRC baseclass properly.

to build a IterExplorer, use the explore() free function, which cares to pick up and possibly adapt the given iteration source
to add processing layers, invoke the builder operations on IterExplorer in a chained fashion, thereby binding functors or lambdas. Capture the final result with an auto variable.
the result is iterable in accordance to »Lumiera Forward Iterator«

Warning: deliberately, the builder functions exposed on IterExplorer will move the old object into the new, augmented iterator. This is possibly dangerous, since one might be tempted to invoke such a builder function on an existing iterator variable captured by auto.

Todo:: if this turns out as a problem on the long run, we'll need to block the iterator operations on the builder (by inheriting protected) and provide an explicit build()-function, which removes the builder API and unleashes or slices down to the iterator instead.

Definition at line 1579 of file iter-explorer.hpp.

Public Types
using	pointer = typename meta::ValueTypeBinding< SRC >::pointer

using	reference = typename meta::ValueTypeBinding< SRC >::reference

using	TAG_IterExplorer_Src = SRC

using	value_type = typename meta::ValueTypeBinding< SRC >::value_type

Public Member Functions
bool	and_all ()
	simplified terminal builder to check if all results yields `true` (short-circuit)

SRC	asIterator ()
	terminal builder to strip the IterExplorer and expose the built Pipeline. More...

IterExploreSource< value_type >	asIterSource ()
	terminal builder to package the processing pipeline as IterSource. More...

auto	asPtr ()
	preconfigured transformer to pass pointers down the pipeline

size_t	count ()
	simplified terminal builder to count number of elements from this sequence. More...

template<template< typename > class SET = std::set>
auto	deduplicate ()
	preconfigured decorator to materialise, sort and deduplicate all source elements. More...

auto	derefPtr ()
	preconfigured transformer to dereference pointers into references

template<template< typename > class CON = std::vector>
auto	effuse ()
	terminal builder to pour and materialise all results from this Pipeline. More...

template<class CON >
auto	effuse (CON &&sink) -> CON

template<class CON >
void	effuse (CON &con)
	_terminal builder to fill an existing container with all results from this Pipeline

template<class FUN >
auto	expand (FUN &&expandFunctor)
	preconfigure this IterExplorer to allow for »expansion of children«. More...

auto	expandAll ()
	extension functionality to be used on top of expand(), to perform expansion automatically. More...

template<class FUN >
auto	expandAll (FUN &&expandFunctor)
	shortcut notation to invoke expand(expandFunctor) followed by expandAll()

auto	expandOnIteration ()
	extension functionality to be used on top of expand(), to perform expansion on next iteration. More...

template<class FUN >
auto	filter (FUN &&filterPredicate)
	adapt this IterExplorer to filter results, by invoking the given functor to approve them. More...

template<class FUN >
void	foreach (FUN &&consumer)
	terminal builder to invoke a functor for side effect on the complete pipeline. More...

template<uint grp>
auto	grouped ()
	adapt this IterExplorer to group result elements into fixed size chunks, packaged as std::array. More...

template<class FGRP , class FAGG >
auto	groupedBy (FGRP &&groupFun, FAGG &&aggFun)
	adapt this IterExplorer to group elements by a custom criterium and aggregate the group members. More...

template<class FGRP >
auto	groupedBy (FGRP &&groupFun)
	simplified grouping to sum / combine all values in a group

bool	has_any ()
	simplified terminal builder to check if any result yields `true` (short-circuit)

template<class FUN >
auto	iterUntil (FUN &&untilCond)
	adapt this IterExplorer to iterate until a condition becomes first true. More...

template<class FUN >
auto	iterWhile (FUN &&whileCond)
	adapt this IterExplorer to iterate only as long as a condition holds true. More...

template<class FUN >
auto	mutableFilter (FUN &&filterPredicate)
	attach a special filter adapter, allowing to change the filter predicate while iterating. More...

auto	mutableFilter ()

template<template< class > class LAY>
auto	processingLayer ()
	builder function to attach a custom extension layer. Any template in compliance with the general construction scheme can be injected through the template parameter. More...

template<class FUN , typename COMB = decltype(std::plus<>()), typename VAL = typename iter_explorer::_ReduceTraits<SRC,FUN>::ResVal>
VAL	reduce (FUN &&accessor, COMB junctor=COMB(), VAL seedVal=VAL())
	terminal builder to sum up or reduce values from the pipeline. More...

auto	resultSum ()
	simplified terminal builder to reduce by numeric sum. More...

template<class FUN >
auto	transform (FUN &&transformFunctor)
	adapt this IterExplorer to pipe each result value through a transformation function. More...

Member Typedef Documentation

◆ TAG_IterExplorer_Src

using TAG_IterExplorer_Src = SRC

for _PipelineDetector

Definition at line 1590 of file iter-explorer.hpp.

Member Function Documentation

◆ expand()

auto expand ( FUN && expandFunctor )

inline

preconfigure this IterExplorer to allow for »expansion of children«.

The resulting iterator exposes an expandChildren() function, which must be invoked explicitly and consumes then the current head element of this iterator and feeds it through the expansion functor, which was provided to this builder function here. This expansion functor is expected to yield a compatible sequence of "child" elements, which will be integrated into the overall result sequence instead of the consumed source element. Thus, repeatedly invoking expand() until exhaustion generates a depth-first evaluation, since every child will be expanded until reaching the leaf nodes of a tree like structure. The result-type of the compound will be chosen appropriately (which may imply to return by-value instead of by-reference)

Parameters

expandFunctor

a "function-like" entity to perform the actual "expansion". There are two distinct usage patterns, as determined by the signature of the provided callable, function or functor:

_"monad style"_: the functor takes a value from the sequence and produces a new sequence, iterator or collection of compatible values
_"opaque state manipulation"_: the functor accepts the concrete source iterator type, or even a "state core" type embedded therein. It yields a new sequence, state core or collection representing the "children". Obviously, the intention here is to allow hidden collaboration between the expansion functor and the embedded opaque "data source". For that reason, the functor may take its argument by reference, and a produced new "child state core" may likewise collaborate with that original data source or state core behind the scenes; the latter is guaranteed to exist during the whole lifetime of this IterExplorer.

Warning: be cautions when relying on stored references into the wrapped state core, because the IterExplorer pipeline as a whole is meant to be movable; either take those references only after the pipeline is »engaged« and placed at its final storage location, or ensure a way to „refresh“ this information on move.

Note: there is limited support for generic lambdas, but only for the second case. The reason is, we can not "probe" a template or generic lambda for possible argument and result types. Thus, if you provide a generic lambda, IterExplorer tries to pass it a SrcIter & (reference to the embedded original iterator). For any other cases, please provide a lambda or functor with a single, explicitly typed argument. Obviously, argument and result type should also make sense for the desired evaluation pattern, otherwise you'll get all kinds of nasty template compilation failures (have fun!)

Returns: processing pipeline with attached Expander decorator

Definition at line 1641 of file iter-explorer.hpp.

◆ expandAll()

auto expandAll ( )

inline

extension functionality to be used on top of expand(), to perform expansion automatically.

When configured, child elements will be expanded on each iteration step; it is thus not necessary to invoke expandChildren() (and doing so would have no further effect than just iterating). Thus, on iteration, each current element will be fed to the expand functor and the results will be integrated depth first.

Returns: processing pipeline with attached AutoExpander decorator

Warning: iteration will be infinite, unless the expand functor provides some built-in termination condition, returning an empty child sequence at that point. This would then be the signal for the internal combination mechanism to return to visiting the results of preceding expansion steps, eventually exhausting all data source(s).

Definition at line 1664 of file iter-explorer.hpp.

◆ expandOnIteration()

auto expandOnIteration ( )

inline

extension functionality to be used on top of expand(), to perform expansion on next iteration.

When configured, an expandChildren() call will not happen immediately, but rather in place of the next iteration step. Basically child expansion is kind of a special iteration step, and thus all we need to do is add another layer with a boolean state flag, which catches the expandChildren() and iterNext() calls and redirects appropriately.

Warning: expandAll and expandOnIteration are not meant to be used at the same time. Recommendation is to use expandOnIteration() right above (after) the expand() definition, since interplay with intermingled layers can be complex.

Definition at line 1692 of file iter-explorer.hpp.

◆ transform()

auto transform ( FUN && transformFunctor )

inline

adapt this IterExplorer to pipe each result value through a transformation function.

Several "layers" of mapping can be piled on top of each other, possibly mixed with the other types of adaptation, like the child-expanding operation, or a filter. Obviously, when building such processing pipelines, the input and output types of the functors bound into the pipeline need to be compatible or convertible. The transformation functor supports the same definition styles as described for expand

it can be pure functional, src -> res
it can accept the underlying source iterator and exploit side-effects
Returns
processing pipeline with attached Transformer decorator

Definition at line 1713 of file iter-explorer.hpp.

◆ grouped()

auto grouped ( )

inline

adapt this IterExplorer to group result elements into fixed size chunks, packaged as std::array.

The first group of elements is pulled eagerly at construction, while further groups are formed on consecutive iteration. Iteration ends when no further full group can be formed; this may leave out some leftover elements, which can then be retrieved by iteration through the special API getRestElms().

Returns: processing pipeline with attached Grouping decorator

Warning: yields a reference into the internal buffer, changed on next iteration.

Definition at line 1734 of file iter-explorer.hpp.

◆ groupedBy()

auto groupedBy	(	FGRP &&	groupFun,
		FAGG &&	aggFun
	)

inline

adapt this IterExplorer to group elements by a custom criterium and aggregate the group members.

The first group of elements is pulled eagerly at construction, further groups are formed on each iteration. Aggregation is done by a custom functor, which takes an aggregator value as first argument and the current element (or iterator) as second argument. Downstream, the aggregator value computed for each group is yielded on iteration.

Parameters

groupFun	a functor to derive a grouping criterium from the source sequence; consecutive elements yielding the same grouping value will be combined / aggregated
aggFun	a functor to compute contribution to the aggregate value. Signature `void(AGG&, Val&)`, where the type AGG implicitly also defines the value to use for accumulation and the result value, while Val must be assignable from the source value provided by the preceding iterator in the pipeline.

Definition at line 1757 of file iter-explorer.hpp.

◆ iterWhile()

auto iterWhile ( FUN && whileCond )

inline

adapt this IterExplorer to iterate only as long as a condition holds true.

Returns: processing pipeline with attached stop condition

Definition at line 1790 of file iter-explorer.hpp.

◆ iterUntil()

auto iterUntil ( FUN && untilCond )

inline

adapt this IterExplorer to iterate until a condition becomes first true.

Returns: processing pipeline with attached stop condition

Definition at line 1806 of file iter-explorer.hpp.

◆ filter()

auto filter ( FUN && filterPredicate )

inline

adapt this IterExplorer to filter results, by invoking the given functor to approve them.

The previously created source layers will be "pulled" to fast-forward immediately to the next element confirmed this way by the bound functor. If none of the source elements is acceptable, the iterator will transition to exhausted state immediately.

Returns: processing pipeline with attached Filter decorator

Definition at line 1831 of file iter-explorer.hpp.

◆ mutableFilter()

auto mutableFilter ( FUN && filterPredicate )

inline

attach a special filter adapter, allowing to change the filter predicate while iterating.

While otherwise this filter layer behaves exactly like the standard version, it exposes a special API to augment or even completely switch the filter predicate while in the middle of iterator evaluation. Of course, the underlying iterator is not re-evaluated from start (our iterators can not be reset), and so the new filter logic takes effect starting from the current element. Whenever the filter is remoulded, it is immediately re-evaluated, possibly causing the underlying iterator to be pulled until an element matching the condition is found.

Returns: processing pipeline with attached special MutableFilter decorator

See also: IterIterExplorer_test::verify_FilterChanges(); iter_explorer::MutableFilter::andFilter(); iter_explorer::MutableFilter::andNotFilter(); iter_explorer::MutableFilter::orFilter(); iter_explorer::MutableFilter::orNotFilter(); iter_explorer::MutableFilter::flipFilter(); iter_explorer::MutableFilter::setNewFilter()

Definition at line 1861 of file iter-explorer.hpp.

◆ processingLayer()

auto processingLayer ( )

inline

builder function to attach a custom extension layer. Any template in compliance with the general construction scheme can be injected through the template parameter.

it must take a first template parameter SRC and inherit from this source iterator
towards layers on top, it must behave like a state core, either by redefining the state core API functions, as defined by IterStateWrapper, or by inheriting them from a lower layer.
it is bound to play well with the other layers; especially it needs to be aware of expandChildren() calls, which for the consumer side behave like iterNext() calls. If a layer needs to do something special for iterNext(), it needs to perform a similar action for expandChildren().
it must be behave like a default-constructible, copyable value object
Returns
augmented IterExplorer, incorporating and adapting the injected layer

Definition at line 1893 of file iter-explorer.hpp.

◆ deduplicate()

auto deduplicate ( )

inline

preconfigured decorator to materialise, sort and deduplicate all source elements.

Warning: uses heap storage to effuse the source pipeline immediately

Definition at line 1926 of file iter-explorer.hpp.

◆ asIterSource()

IterExploreSource<value_type> asIterSource ( )

inline

terminal builder to package the processing pipeline as IterSource.

Invoking this function moves the whole iterator compound, as assembled by the preceding builder calls, into heap allocated memory and returns an iterator front-end. Any iteration and manipulation on that front-end is passed through virtual function calls into the back-end, thereby concealing all details of the processing pipeline.

Returns: an front-end handle object, which is an "Lumiera Forward Iterator", while holding onto a heap allocated abstracted data source.

Definition at line 1949 of file iter-explorer.hpp.

◆ asIterator()

SRC asIterator ( )

inline

terminal builder to strip the IterExplorer and expose the built Pipeline.

Returns: a »Lumiera Forward iterator« incorporating the complete pipeline logic.

Definition at line 1959 of file iter-explorer.hpp.

◆ foreach()

void foreach ( FUN && consumer )

inline

terminal builder to invoke a functor for side effect on the complete pipeline.

Note: exhausts and discards the pipeline itself

Definition at line 1970 of file iter-explorer.hpp.

◆ reduce()

VAL reduce	(	FUN &&	accessor,
		COMB	junctor = `COMB()`,
		VAL	seedVal = `VAL()`
	)

inline

terminal builder to sum up or reduce values from the pipeline.

In the general case a fold-left operation is performed; default values for the joining operation and the initial value however allow to fall back on summation of values.

Parameters

accessor	a functor working on the pipeline result values or the iterator
junctor	(optional) binary operation, joining the sum with the next result of the junctor
seedVal	(optional) initial value to start accumulation from

Returns: accumulation of all results from the pipeline, combined with the junctor

Definition at line 1992 of file iter-explorer.hpp.

◆ resultSum()

auto resultSum ( )

inline

simplified terminal builder to reduce by numeric sum.

Definition at line 2005 of file iter-explorer.hpp.

References stage::widget::anonymous_namespace{element-box-widget.cpp}::reduce().

Here is the call graph for this function:

◆ count()

size_t count ( )

inline

simplified terminal builder to count number of elements from this sequence.

Definition at line 2012 of file iter-explorer.hpp.

References stage::widget::anonymous_namespace{element-box-widget.cpp}::reduce().

Here is the call graph for this function:

◆ effuse()

auto effuse ( )

inline

terminal builder to pour and materialise all results from this Pipeline.

Template Parameters

CON	a STL compliant container to store generated values (defaults to `vector`)

Returns: new instance of the target container, filled with all values pulled from this Pipeline until exhaustion.

Definition at line 2049 of file iter-explorer.hpp.

Inheritance diagram for IterExplorer< SRC >:

Collaboration diagram for IterExplorer< SRC >:

The documentation for this class was generated from the following file:

iter-explorer.hpp

Description

template<class SRC> class lib::IterExplorer< SRC >

Public Types

Public Member Functions

Member Typedef Documentation

◆ TAG_IterExplorer_Src

Member Function Documentation

◆ expand()

◆ expandAll()

◆ expandOnIteration()

◆ transform()

◆ grouped()

◆ groupedBy()

◆ iterWhile()

◆ iterUntil()

◆ filter()

◆ mutableFilter()

◆ processingLayer()

◆ deduplicate()

◆ asIterSource()

◆ asIterator()

◆ foreach()

◆ reduce()

◆ resultSum()

◆ count()

◆ effuse()

template<class SRC>
class lib::IterExplorer< SRC >