#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	YieldRes = _Trait::YieldRes

using	value_type = _Trait::value_type

using	reference = _Trait::reference

using	pointer = _Trait::pointer

Public Member Functions
	Expander ()=default

template<typename FUN >
	Expander (SRC &&parentExplorer, FUN &&expandFunctor)

void	expandChildren ()
	core operation: expand current head element

size_t	depth () const
	diagnostics: current level of nested child expansion

void	rootCurrent ()
	lock into the current child sequence.

bool	checkPoint () const

YieldRes	yield () const

void	iterNext ()

Protected Member Functions
bool	hasChildren () const

ResIter &	accessCurrentChildIter ()

void	dropExhaustedChildren ()

Private Types
using	_Trait = _ExpanderTraits< SRC, RES >

using	ResIter = _Trait::ResIter

using	RootExpandFunctor = function< RES(SRC &)>

using	ChldExpandFunctor = function< RES(ResIter &)>

Private Member Functions
bool	invariant () const

void	incrementCurrent ()

Private Attributes
RootExpandFunctor	expandRoot_

ChldExpandFunctor	expandChild_

IterStack< ResIter >	expansions_

Constructor & Destructor Documentation

◆ Expander() [1/2]

template<class SRC , class RES >

Expander ( )

default

◆ Expander() [2/2]

template<class SRC , class RES >

template<typename FUN >

Expander	(	SRC &&	parentExplorer,
		FUN &&	expandFunctor
	)

inline

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

Member Typedef Documentation

◆ _Trait

template<class SRC , class RES >

using _Trait = _ExpanderTraits<SRC,RES>

private

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

◆ ResIter

template<class SRC , class RES >

using ResIter = _Trait::ResIter

private

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

◆ RootExpandFunctor

template<class SRC , class RES >

using RootExpandFunctor = function<RES(SRC&)>

private

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

◆ ChldExpandFunctor

template<class SRC , class RES >

using ChldExpandFunctor = function<RES(ResIter&)>

private

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

◆ YieldRes

template<class SRC , class RES >

using YieldRes = _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.

◆ value_type

template<class SRC , class RES >

using value_type = _Trait::value_type

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

◆ reference

template<class SRC , class RES >

using reference = _Trait::reference

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

◆ pointer

template<class SRC , class RES >

using pointer = _Trait::pointer

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

Member Function Documentation

◆ expandChildren()

template<class SRC , class RES >

void expandChildren ( )

inline

core operation: expand current head element

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

References Expander< SRC, RES >::checkPoint(), Expander< SRC, RES >::expandChild_, Expander< SRC, RES >::expandRoot_, Expander< SRC, RES >::expansions_, Expander< SRC, RES >::hasChildren(), Expander< SRC, RES >::invariant(), Expander< SRC, RES >::iterNext(), and IterStack< TY >::push().

Here is the call graph for this function:

◆ depth()

template<class SRC , class RES >

size_t depth ( ) const

inline

diagnostics: current level of nested child expansion

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

References Expander< SRC, RES >::expansions_, and IterStack< TY >::size().

Referenced by Expander< SRC, RES >::hasChildren().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rootCurrent()

template<class SRC , class RES >

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.

References IterStack< TY >::clear(), Expander< SRC, RES >::expansions_, and Expander< SRC, RES >::hasChildren().

Here is the call graph for this function: