Helper template(s) for creating Lumiera Forward Iterators. More...

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 a State Core 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 an "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. However, by inspiration from functional programming, we deliberately do not 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 once, and nothing beyond that.

Notably,

any Lumiera forward iterator can be in a "exhausted" (invalid) state, which can be checked by the bool conversion. Especially, an instance created by the default ctor is always fixed to that state. This state is final and can not 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.
usually, the current value is exposed by-ref (but by-val is possible)
moreover, iterators may be incremented until exhaustion.

Conceptually, a Lumiera Iterator represents a lazy stream of calculations rather than a target value considered to be »within« a container. And while the result is in may cases deliberately exposed as a reference, in order to keep the door open for special-case manipulations, for the typical usage it is discouraged to assume anything about the source, beyond the limited access to some transient state as exposed during active iteration. Together, these rules enable a loose coupling to the source of data.

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>
#include <limits>

Namespaces
namespace	util

namespace	lib
	Implementation namespace for support and library code.

namespace	lib::anonymous_namespace{iter-adapter.hpp}

namespace	lib::iter

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

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

Typedefs
template<class IT >
using	Yield = decltype(std::declval< IT >().operator*())
	type binding helper: an iterato's actual result type

template<class COR >
using	CoreYield = decltype(std::declval< COR >().yield())
	the result type yielded by a »state core«

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

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

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

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

class	ContainerCore< CON >
	Adapter to »piggy-back« a STL iterable container inline and expose it as »state core«. More...

class	IterableDecorator< COR >
	Decorator-Adapter to make a »State Core« iterable as Lumiera Forward Iterator. 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...

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

struct	IterType< Iter< TY, CON > >

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

struct	IterType< RangeIter< IT > >

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

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

Functions
template<class OBJ >
OBJ *	unConst (const OBJ *o)
	shortcut to save some typing when having to define const and non-const variants of member functions

template<class OBJ >
OBJ &	unConst (OBJ const &)

void	_throwIterExhausted ()

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

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

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

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

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!= (RangeIter< I1 > const &il, RangeIter< I2 > const &ir)

template<typename INT >
NumIter< INT >	eachNum (INT start=std::numeric_limits< INT >::min(), INT end=std::numeric_limits< INT >::max())
	convenience function to iterate "each number"

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

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

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 134 of file iter-adapter.hpp.

◆ 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 142 of file iter-adapter.hpp.

Class Documentation

◆ 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< 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 >:

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

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

Class Members
typedef template Type	WrappedIter
typedef RangeIter< WrappedIter >	Type

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

Description

Lumiera Forward Iterator concept

Namespaces

Macros

Typedefs

Classes