Lumiera  0.pre.03
IterExplorer< SRC, _COM_ > Class Template Reference

#include "lib/iter-explorer.hpp"


template<class SRC, template< class, class > class _COM_ = iter_explorer::DefaultCombinator>
class lib::IterExplorer< SRC, _COM_ >

Adapter for using an Iterator in the way of a Monad This allows to "bind" or "flatMap" a functor, thereby creating a derived version of the iterator, yielding the (flattened) combination of all the results generated by this bound functor.

The rationale is to apply some exploration or expansion pattern on the elements of the source sequence (source iterator) – while completely separating out the mechanics how to treat and combine individual elements.

implementation approach
IterExplorer is a thin wrapper, based on IterStateWrapper; thus the assumption is for the actual elements to be generated by a "state core", which is embedded right into each instance. To provide the monad bind operator >>= , we need the help of a strategy template, the so called Combinator. This strategy contains the details how to combine the results of various iterators and to join them together into a single new IterExplorer instance. Thus, obviously this Combinator strategy template relies on additional knowledge about the source iterator's implementation. Such is unavoidable, since C++ isn't a functional programming language.

When invoking the bind (flat map) operator, a suitably represented functor is embedded into an instance of the Combinator template. Moreover, a copy of the current IterExplorer is embedded alongside. The resulting object becomes the state core of the new IterExplorer object returned as result. So the result is an iterator, but – when "pulled" – it will in turn pull from the source iterator and feed the provided elements through the exploration functor, which this way has been bound into the resulting monad. The purpose of the Combinator strategy is to join together various resulting iterators, thereby "flattening" one level of "monad packaging" (hence the name "flat map operator").

figuring out what happens here just from the code might lead to confusion. You really need to grasp the monad concept first, which is a design pattern commonly used in functional programming. For the practical purpose in question here, you might consider it a "programmable semicolon": it links together a chain of operations detailed elsewhere, and provided in a dynamic fashion (as functor at runtime). More specifically, these operations will expand and explore a dynamic source data set on the fly. Notably this allows us to handle such an "exploration" in a flexible way, without the need to allocate heap memory to store intermediary results, but also without using the stack and recursive programming.
be sure to consider the effects of copying iterators on any hidden state referenced by the source iterator(s). Basically any iterator must behave sane when copied while in iteration: IterExplorer first evaluates the head element of the source (the explorer function should build an independent, new result sequence based on this first element). Afterwards, the source is advanced and then copied into the result iterator.
IterExplorer and all the provided combination strategies are deliberately designed to work on sequences of values. These values will indeed be copied for invocation of the exploration function. The rationale for this choice is data locality and the danger of dangling references to an implicitly created temporary (since in it is so common practice in C++ to use const& ). Thus, if you need to work on references to a common data structure, you need to use either pointers or some reference wrapper explicitly as value type right from start.
SRCthe source sequence or iterator to wrap
<em>COM</em>"Combinator" strategy template. When binding (>>= ) a function, an instance of that strategy becomes the new SRC for the created new IterExplorer. This instantiation of the strategy gets as type parameters:
  • this IterExplorer's instance type
  • the type of the function bound with >>=

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

Public Types

typedef SRC::pointer pointer
typedef SRC::reference reference
typedef SRC::value_type value_type
- Public Types inherited from IterStateWrapper< SRC::value_type, SRC >
typedef SRC::value_type * pointer
typedef SRC::value_type & reference
typedef SRC::value_type value_type

Public Member Functions

 IterExplorer ()
 by default create an empty iterator More...
 IterExplorer (SRC const &iterStateCore)
 wrap an iterator-like state representation to build it into a monad. More...
template<class FUN >
FlatMapped< FUN >::Type operator>>= (FUN explorer)
 monad bind ("flat map") operator. More...
- Public Member Functions inherited from IterStateWrapper< SRC::value_type, SRC >
 IterStateWrapper (SRC &&initialState)
 IterStateWrapper (SRC const &initialState)
 IterStateWrapper ()
bool empty () const
bool isValid () const
 operator bool () const
reference operator* () const
IterStateWrapperoperator++ ()
pointer operator-> () const


struct  FlatMapped
 Metafunction: the resulting type when binding ("flat mapping") a functor of type FUN. More...

Private Member Functions

IterExplorer const & accessRemainingElements ()

Additional Inherited Members

- Protected Member Functions inherited from IterStateWrapper< SRC::value_type, SRC >
void __throw_if_empty () const
SRC & stateCore ()
 allow derived classes to access state representation More...

Member Typedef Documentation

◆ value_type

typedef SRC::value_type value_type

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

◆ reference

typedef SRC::reference reference

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

◆ pointer

typedef SRC::pointer pointer

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

Class Documentation

◆ lib::IterExplorer::FlatMapped

struct lib::IterExplorer::FlatMapped
Class Members
typedef IterExplorer< _COM_
< IterExplorer, FUN >, _COM_ >
+ Collaboration diagram for IterExplorer< SRC, _COM_ >::FlatMapped< FUN >:

Constructor & Destructor Documentation

◆ IterExplorer() [1/2]

IterExplorer ( )

by default create an empty iterator

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

◆ IterExplorer() [2/2]

IterExplorer ( SRC const &  iterStateCore)

wrap an iterator-like state representation to build it into a monad.

The resulting entity is both an iterator yielding the elements generated by the core, and it provides the (monad) bind operator.

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

Member Function Documentation

◆ operator>>=()

FlatMapped<FUN>::Type operator>>= ( FUN  explorer)

monad bind ("flat map") operator.

Using a specific function to explore and work on the "contents" of this IterExplorer, with the goal to build a new IterExplorer combining the results of this function application. The enclosing IterExplorer instance provides a Strategy template COM, which defines how those results are actually to be combined. An instantiation of this "Combinator" strategy becomes the state core of the result iterator.

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

◆ accessRemainingElements()

IterExplorer const& accessRemainingElements ( )

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

+ Inheritance diagram for IterExplorer< SRC, _COM_ >:
+ Collaboration diagram for IterExplorer< SRC, _COM_ >:

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