Expander< SRC, RES > Class Template Reference

#include "lib/iter-explorer.hpp"

Description

template<class SRC, class RES>
class lib::iter_explorer::Expander< SRC, RES >

Decorator for IterExplorer adding the ability to "expand children". The expandChildren() operation is the key element of a depth-first evaluation: it consumes one element and performs a preconfigured expansion functor on that element to yield its "children". These are given in the form of another iterator, which needs to be compatible to the source iterator ("compatibility" boils down to both iterators yielding a compatible value type). Now, this sequence of children effectively replaces the expanded source element in the overall resulting sequence; which means, the nested sequence was flattened into the results. Since this expand() operation can again be invoked on the results, the implementation of such an evaluation requires a stack datastructure, so the nested iterator from each expand() invocation can be pushed to become the new active source for iteration. Thus the primary purpose of this Expander (decorator) is to integrate those "nested child iterators" seamlessly into the overall iteration process; once a child iterator is exhausted, it will be popped and iteration continues with the previous child iterator or finally with the source iterator wrapped by this decorator. The source pipeline is only pulled once the expanded children are exhausted.

Remarks

since we allow a lot of leeway regarding the actual form and definition of the expansion functor, there is a lot of minute technical details, mostly confined within the _FunTraits traits. For the same reason, we need to prepare two different bindings of the passed raw functor, one to work on the source sequence, and the other one to work on the result sequence of a recursive child expansions; these two sequences need not be implemented in the same way, which simplifies the definition of algorithms.

Template Parameters

SRC	the wrapped source iterator, typically a IterExplorer or nested decorator.
FUN	the concrete type of the functor passed. Will be dissected to find the signature

Note

the return type of #yield depends both on the return type produced from the original sequence and the return type of the sequence established through the expand functor. An attempt is made to reconcile these and this attempt may fail (at compile time). The reason is, any further processing downstream can not tell if data was produced by the original sequence of the expansion sequence. Notably, if one of these two delivers results by-value, then the Expander will always deliver all results by-value, because it would not be possible to expose a reference to some value that was just delivered temporarily from a source iterator.

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

Public Types
using	pointer = typename _Trait::pointer
using	reference = typename _Trait::reference
using	value_type = typename _Trait::value_type
using	YieldRes = typename _Trait::YieldRes

Public Member Functions
template<typename FUN >
	Expander (SRC &&parentExplorer, FUN &&expandFunctor)
bool	checkPoint () const
size_t	depth () const
	diagnostics: current level of nested child expansion
void	expandChildren ()
	core operation: expand current head element
void	iterNext ()
void	rootCurrent ()
	lock into the current child sequence. More...
YieldRes	yield () const

Protected Member Functions
ResIter &	accessCurrentChildIter ()
void	dropExhaustedChildren ()
bool	hasChildren () const

Private Types
using	_Trait = _ExpanderTraits< SRC, RES >
using	ChldExpandFunctor = function< RES(ResIter &)>
using	ResIter = typename _Trait::ResIter
using	RootExpandFunctor = function< RES(SRC &)>

Private Member Functions
void	incrementCurrent ()
bool	invariant () const

Private Attributes
ChldExpandFunctor	expandChild_
RootExpandFunctor	expandRoot_
IterStack< ResIter >	expansions_

Member Typedef Documentation

YieldRes

using YieldRes = typename _Trait::YieldRes

Note

result type bindings based on a common type of source and expanded result

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

Member Function Documentation

rootCurrent()

void rootCurrent ( )

inline

lock into the current child sequence.

This special feature turns the current child sequence into the new root, thereby discarding everything else in the expansions stack, including the original root sequence.

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

accessCurrentChildIter()

ResIter& accessCurrentChildIter ( )

inlineprotected

accessor for downstream layers to allow close collaboration

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

Inheritance diagram for Expander< SRC, RES >:

Collaboration diagram for Expander< SRC, RES >:

---

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

• iter-explorer.hpp