Description

Helper template(s) for creating Lumiera Forward Iterators.

These are the foundation to build up iterator like types from scratch. Usually, these templates will be created and provided by a custom container type and accessed by the client through a typedef name "`iterator`" (similar to the usage within the STL). For more advanced usage, the providing container might want to subclass these iterators, e.g. to provide an additional, specialised API.

Depending on the concrete situation, several flavours are provided:

the IterAdapter retains an active callback connection to the controlling container, thus allowing arbitrary complex behaviour.
the IterStateWrapper uses a variation of that approach, where the representation of the current state is embedded as an state value element right into the iterator instance.
very similar is IterableDecorator, but this time directly as decorator to inherit from the »state core«, and without checks.
the RangeIter allows just to expose a range of elements defined by a STL-like pair of "start" and "end" iterators

Some more specific use cases are provided in the extension header iter-adapter-ptr-deref.hpp

often, objects are managed internally by pointers, while allowing the clients to use direct references; to support this usage scenario, PtrDerefIter wraps an existing iterator, while dereferencing any value automatically on access.
for some (very specific) usage situations we intend to explore the contents of a stable and unmodifiable data structure through pointers. The AddressExposingIter wraps another Lumiera Forward Iterator and exposes addresses – assuming the used source iterator is exposing references to pre-existing storage locations (not temporaries).

There are many further ways of building a Lumiera Forward Iterator. For example, lib::IterSource exposes a "iterable" source of data elements, while hiding the actual container or generator implementation behind a VTable call. Furthermore, complex processing chains with recursive expansion can be built with the IterExporer builder function. Besides, there are adapters for the most common usages with STL containers, and such iterators can also be combined and extended with the help of itertools.hpp

Basically every class in compliance with our specific iterator concept can be used as a building block within this framework.

Lumiera Forward Iterator concept

Similar to the STL, instead of using a common "Iterator" base class, we rather define a common set of functions and behaviour which can be expected from any such iterator. These rules are similar to STL's "forward iterator", with the addition of an bool check to detect iteration end. The latter is inspired by the hasNext() function found in many current languages supporting iterators. In a similar vein (inspired from functional programming), we deliberately don't support the various extended iterator concepts from STL and boost (random access iterators, output iterators, arithmetics, difference between iterators and the like). According to this concept, an iterator is a promise for pulling values, and nothing beyond that.

Any Lumiera forward iterator can be in a "exhausted" (invalid) state, which can be checked by the bool conversion. Especially, any instance created by the default ctor is always fixed to that state. This state is final and can't be reset, meaning that any iterator is a disposable one-way-off object.
iterators are copyable and equality comparable
when an iterator is not in the exhausted state, it may be dereferenced to yield the "current" value.
moreover, iterators may be incremented until exhaustion.

See also: iter-adapter-test.cpp; itertools.hpp; IterSource (completely opaque iterator); value-type-binding.hpp

Definition in file iter-adapter.hpp.

#include "lib/error.hpp"
#include "lib/meta/value-type-binding.hpp"
#include <iterator>

Classes
class	CheckedCore< COR >
	Adapter to add sanity checks to a »state core«. More...

class	ConstIter< IT >
	wrapper to expose values as const More...

class	IterableDecorator< T, COR >
	Decorator-Adapter to make a »state core« iterable as Lumiera Forward Iterator. More...

class	IterAdapter< POS, CON >
	Adapter for building an implementation of the »Lumiera Forward Iterator« concept. More...

class	IterStateCore< IT >
	Adapter to dress up an existing »Lumiera Forward Iterator« as »state core«. More...

class	IterStateWrapper< T, ST >
	Another Lumiera Forward Iterator building block, based on incorporating a state type right into the iterator. More...

struct	IterType< TY >
	Helper for type rewritings: get the element type for an iterator like entity. More...

struct	IterType< Iter< TY, CON > >

struct	IterType< RangeIter< IT > >

class	NumIter< INT >
	Enumerate all "numbers" within a range. More...

class	RangeIter< IT >
	Accessing a STL element range through a Lumiera forward iterator, An instance of this iterator adapter is completely self-contained and allows to iterate once over the range of elements, until `pos==end`. More...

struct	IterType< RangeIter< IT > >::SimilarIter< T2 >
	< rebind to rewritten Iterator wrapped into RangeIter More...

struct	IterType< Iter< TY, CON > >::SimilarIter< T2 >
	< rebind to a similarly structured Iterator with value type T2 More...

Macros
#define	ENABLE_USE_IN_STD_RANGE_FOR_LOOPS(ITER)
	use a given Lumiera Forward Iterator in standard "range for loops" More...

#define	LIFT_PARENT_INCREMENT_OPERATOR(_BASECLASS_)
	define increment operator forwarding to baseclass but returning current More...

Functions
void	_throwIterExhausted ()

template<typename INT >
NumIter< INT >	eachNum (INT start, INT end)
	convenience function to iterate "each number"

template<class P1 , class P2 , class CON >
bool	operator!= (IterAdapter< P1, CON > const &il, IterAdapter< P2, CON > const &ir)

template<class T1 , class T2 , class ST >
bool	operator!= (IterStateWrapper< T1, ST > const &il, IterStateWrapper< T2, ST > const &ir)

template<class I1 , class I2 >
bool	operator!= (RangeIter< I1 > const &il, RangeIter< I2 > const &ir)

template<class I1 , class I2 >
bool	operator!= (NumIter< I1 > const &il, NumIter< I2 > const &ir)

template<class I1 , class I2 >
bool	operator!= (ConstIter< I1 > const &il, ConstIter< I2 > const &ir)

template<class P1 , class P2 , class CON >
bool	operator== (IterAdapter< P1, CON > const &il, IterAdapter< P2, CON > const &ir)
	Supporting equality comparisons...

template<class T1 , class T2 , class ST >
bool	operator== (IterStateWrapper< T1, ST > const &il, IterStateWrapper< T2, ST > const &ir)
	Supporting equality comparisons of equivalent iterators (same state type)...

template<class I1 , class I2 >
bool	operator== (RangeIter< I1 > const &il, RangeIter< I2 > const &ir)
	Supporting equality comparisons...

template<class I1 , class I2 >
bool	operator== (NumIter< I1 > const &il, NumIter< I2 > const &ir)
	Supporting equality comparisons...

template<class I1 , class I2 >
bool	operator== (ConstIter< I1 > const &il, ConstIter< I2 > const &ir)
	Supporting equality comparisons...

Namespaces
	lib
	Implementation namespace for support and library code.

Macro Definition Documentation

◆ ENABLE_USE_IN_STD_RANGE_FOR_LOOPS

#define ENABLE_USE_IN_STD_RANGE_FOR_LOOPS ( ITER )

Value:

friend ITER   begin (ITER const& it){ return it; }                      \
      friend ITER&& begin (ITER&& it)     { return static_cast<ITER&&> (it); } \
      friend ITER   end   (ITER const&)   { return ITER(); }                    \
      using iterator_category = std::input_iterator_tag;                         \
      using difference_type = size_t;

use a given Lumiera Forward Iterator in standard "range for loops"

Definition at line 124 of file iter-adapter.hpp.

Referenced by ConstIter< IT >::getBase(), RangeIter< StlIter >::getPos(), NumIter< INT >::getPos(), IterableDecorator< Epoch, StorageAdaptor >::IterableDecorator(), and IterSnapshot< VAL >::IterSnapshot().

◆ LIFT_PARENT_INCREMENT_OPERATOR

#define LIFT_PARENT_INCREMENT_OPERATOR ( _BASECLASS_ )

Value:

auto&                       \
      operator++()                 \
        {                           \
          _BASECLASS_::operator++(); \
          return *this;               \
        }

define increment operator forwarding to baseclass but returning current

Definition at line 132 of file iter-adapter.hpp.

Class Documentation

◆ lib::IterType

struct lib::IterType

Inheritance diagram for IterType< TY >:

Collaboration diagram for IterType< TY >:

◆ lib::IterType< Iter< TY, CON > >

struct lib::IterType< Iter< TY, CON > >

Class Members
typedef CON	Container
typedef TY	ElemType

Collaboration diagram for IterType< Iter< TY, CON > >:

◆ lib::IterType< RangeIter< IT > >::SimilarIter

struct lib::IterType< RangeIter< IT > >::SimilarIter

Class Members
typedef IterType< IT > ::template SimilarIter< T2 > ::Type	WrappedIter
typedef RangeIter< WrappedIter >	Type

Collaboration diagram for IterType< RangeIter< IT > >::SimilarIter< T2 >:

◆ lib::IterType< Iter< TY, CON > >::SimilarIter

struct lib::IterType< Iter< TY, CON > >::SimilarIter

Class Members
typedef Iter< T2, CON >	Type

Collaboration diagram for IterType< Iter< TY, CON > >::SimilarIter< T2 >: