Lumiera  0.pre.03
»edityourfreedom«
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
IterExplorer< SRC, _COM_ > Class Template Reference

#include "lib/iter-explorer.hpp"

Description

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").

Remarks
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.
Warning
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.
Parameters
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 (SRCconst &initialState)
 
 IterStateWrapper ()
 
bool empty () const
 
 ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (IterStateWrapper)
 
bool isValid () const
 
 operator bool () const
 
reference operator* () const
 
IterStateWrapperoperator++ ()
 
pointer operator-> () const
 

Classes

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

typedef SRC::value_type value_type

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

typedef SRC::reference reference

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

typedef SRC::pointer pointer

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


Class Documentation

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

Constructor & Destructor Documentation

IterExplorer ( )
inline

by default create an empty iterator

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

IterExplorer ( SRC const &  iterStateCore)
inlineexplicit

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

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

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.

IterExplorer const& accessRemainingElements ( )
inlineprivate

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

Referenced by IterExplorer< WrappedSequence< SRC >, BreadthFirstEvaluationCombinator >::operator>>=().

+ Here is the caller graph for this function:

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

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