iter-explorer.hpp

Go to the documentation of this file.

/*
  ITER-EXPLORER.hpp  -  building blocks for iterator evaluation strategies

  Copyright (C)         Lumiera.org
    2017,               Hermann Vosseler <Ichthyostega@web.de>

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of
  the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef LIB_ITER_EXPLORER_H
#define LIB_ITER_EXPLORER_H


#include "lib/error.hpp"
#include "lib/uninitialised-storage.hpp"
#include "lib/meta/duck-detector.hpp"
#include "lib/meta/function.hpp"
#include "lib/meta/trait.hpp"
#include "lib/wrapper.hpp"        
#include "lib/iter-adapter.hpp"
#include "lib/iter-source.hpp"   
#include "lib/iter-stack.hpp"
#include "lib/util.hpp"

#include <functional>
#include <optional>
#include <utility>


//Forward declaration to allow a default result container for IterExplorer::effuse
namespace std {
  template<typename T, class A> class vector;
}


namespace lib {
  
  using std::move;
  using std::forward;
  using std::function;
  using util::isnil;
  
  namespace error = lumiera::error;
  
  namespace iter_explorer { // basic iterator wrappers...
    
    template<class CON>
    using iterator = typename meta::Strip<CON>::TypeReferred::iterator;
    template<class CON>
    using const_iterator = typename meta::Strip<CON>::TypeReferred::const_iterator;
    
    template<class CON>
    struct StlRange
      : RangeIter<iterator<CON>>
      {
        StlRange() =default;
        StlRange (CON& container)
          : RangeIter<iterator<CON>> {begin(container), end(container)}
          { }
       // standard copy operations acceptable
      };
    
    template<class CON>
    struct StlRange<const CON>
      : RangeIter<const_iterator<CON>>
      {
        StlRange() =default;
        StlRange (CON const& container)
          : RangeIter<const_iterator<CON>> {begin(container), end(container)}
          { }
       // standard copy operations acceptable
      };
    
    template<class CON>
    struct StlRange<CON &>
      : StlRange<CON>
      {
        using StlRange<CON>::StlRange;
      };
    
    
    template<class ISO>
    class IterSourceIter
      : public ISO::iterator
      {
        using Iterator = typename ISO::iterator;
        
      public:
        IterSourceIter()  =default;
        // standard copy operations
        
        IterSourceIter (ISO& externalSource)
          : Iterator{ISO::build (externalSource)}
          { }
        
        IterSourceIter (ISO* heapObject)
          : Iterator{heapObject? ISO::build (heapObject)
                               : Iterator()}
          { }
        
        using Source = ISO;
        
        Source&
        source()
          {
            REQUIRE (ISO::iterator::isValid());
            return static_cast<ISO&> (*ISO::iterator::source());
          }
      };
    
  }//(End) namespace iter_explorer : basic iterator wrappers
  
  
  
  
  namespace { // IterExplorer traits
    
    using meta::enable_if;
    using meta::disable_if;
    using meta::Yes_t;
    using meta::No_t;
    using meta::_Fun;
    using std::__and_;
    using std::__not_;
    using std::is_const_v;
    using std::is_base_of;
    using std::common_type;
    using std::common_type_t;
    using std::conditional_t;
    using std::is_convertible;
    using std::remove_reference_t;
    using meta::is_StateCore;
    using meta::can_IterForEach;
    using meta::can_STL_ForEach;
    using meta::ValueTypeBinding;
    using meta::has_TypeResult;
    
    
    template<class SRC>
    struct shall_wrap_STL_Iter
      : __and_<can_STL_ForEach<SRC>
              ,__not_<can_IterForEach<SRC>>
              >
      { };
    
    template<class SRC>
    struct shall_use_Lumiera_Iter
      : __and_<can_IterForEach<SRC>
              ,__not_<is_StateCore<SRC>>
              >
      { };
    
    
    template<class COR>
    struct CoreYield
      {
        using Res = remove_reference_t<decltype(std::declval<COR>().yield())>;
        
        using value_type = typename meta::RefTraits<Res>::Value;
        using reference  = typename meta::RefTraits<Res>::Reference;
        using pointer    = typename meta::RefTraits<Res>::Pointer;
      };
    
    
    template<class SRC, typename SEL=void>
    struct _DecoratorTraits
      {
        static_assert (!sizeof(SRC), "Can not build IterExplorer: Unable to figure out how to iterate the given SRC type.");
      };
    
    template<class SRC>
    struct _DecoratorTraits<SRC,   enable_if<is_StateCore<SRC>>>
      {
        using SrcRaw  = typename lib::meta::Strip<SRC>::Type;
        using SrcVal  = typename CoreYield<SrcRaw>::value_type;
        using SrcIter = lib::IterableDecorator<SrcVal, lib::CheckedCore<SrcRaw>>;
      };
    
    template<class SRC>
    struct _DecoratorTraits<SRC,   enable_if<shall_use_Lumiera_Iter<SRC>>>
      {
        using SrcIter = remove_reference_t<SRC>;
        using SrcVal  = typename SrcIter::value_type;
      };
    
    template<class SRC>
    struct _DecoratorTraits<SRC,   enable_if<shall_wrap_STL_Iter<SRC>>>
      {
        static_assert (not std::is_rvalue_reference<SRC>::value,
                       "container needs to exist elsewhere during the lifetime of the iteration");
        using SrcIter = iter_explorer::StlRange<SRC>;
        using SrcVal  = typename SrcIter::value_type;
      };
    
    template<class ISO>
    struct _DecoratorTraits<ISO*,  enable_if<is_base_of<IterSource<typename ISO::value_type>, ISO>>>
      {
        using SrcIter = iter_explorer::IterSourceIter<ISO>;
        using SrcVal  = typename ISO::value_type;
      };
    
    template<class ISO>
    struct _DecoratorTraits<ISO*&, enable_if<is_base_of<IterSource<typename ISO::value_type>, ISO>>>
      : _DecoratorTraits<ISO*>
      { };
    
    template<class ISO>
    struct _DecoratorTraits<ISO&,  enable_if<is_base_of<IterSource<typename ISO::value_type>, ISO>>>
      : _DecoratorTraits<ISO*>
      { };
    
    
    
    template<class SRC, class RES>
    struct _ExpanderTraits
      {
        using ResIter = typename _DecoratorTraits<RES>::SrcIter;
        using SrcYield = typename ValueTypeBinding<SRC>::value_type;
        using ResYield = typename ValueTypeBinding<ResIter>::value_type;
        static constexpr bool can_reconcile =
           has_TypeResult<common_type<SrcYield,ResYield>>();
        
        static_assert (can_reconcile,
                       "source iterator and result from the expansion must yield compatible values");
        static_assert (is_const_v<SrcYield> == is_const_v<ResYield>,
                       "source and expanded types differ in const-ness");
        
        // NOTE: unfortunately std::common_type decays (strips cv and reference)
        //       in C++20, there would be std::common_reference; for now we have to work around that
        using CommonType = conditional_t<is_const_v<SrcYield> or is_const_v<ResYield>
                                        , const common_type_t<SrcYield,ResYield>
                                        ,       common_type_t<SrcYield,ResYield>
                                        >;
        using value_type = typename ValueTypeBinding<CommonType>::value_type;
        using reference  = typename ValueTypeBinding<CommonType>::reference;
        using pointer    = typename ValueTypeBinding<CommonType>::pointer;
      };
    
  }//(End) IterExplorer traits
  
  
  
  
  
  namespace iter_explorer { // Implementation of Iterator decorating layers...
    
    constexpr auto ACCEPT_ALL = [](auto){return true;};
    constexpr auto IDENTITY   = [](auto it){return *it;};
    
    template<class FUN, typename SRC>
    struct _FunTraits
      {
        template<typename F, typename SEL =void>
        struct FunDetector
          {
            using Sig = typename _Fun<F>::Sig;
          };
        
        template<typename F>
        struct FunDetector<F,  disable_if<_Fun<F>> >
          {
            using Arg = typename std::add_lvalue_reference<SRC>::type;
            using Ret = decltype(std::declval<F>() (std::declval<Arg>()));
            using Sig = Ret(Arg);
          };
        
        
        using Sig = typename FunDetector<FUN>::Sig;
        using Arg = typename _Fun<Sig>::Args::List::Head;  // assuming function with a single argument
        using Res = typename _Fun<Sig>::Ret;
        static_assert (meta::is_UnaryFun<Sig>());
        
        
        
        template<class ARG, class SEL =void>
        struct ArgAdapter
          {
            using FunArgType = remove_reference_t<Arg>;
            static_assert (std::is_convertible<ARG, FunArgType>::value,
                           "the bound functor must accept the source iterator or state core as parameter");
            
            static decltype(auto)
            wrap (FUN&& rawFunctor)  
              {
                return forward<FUN> (rawFunctor);
              }
          };
        
        template<class IT>
        struct ArgAdapter<IT,   enable_if<__and_<is_convertible<typename IT::reference, Arg>
                                                 ,__not_<is_convertible<IT, Arg>>>>>        // need to exclude the latter, since IterableDecorator
          {                                                                                //  often seems to accept IT::value_type (while in fact it doesn't)
            static auto
            wrap (function<Sig> rawFun)          
              {
                return [rawFun](IT& srcIter) -> Res { return rawFun(*srcIter); };
              }
          };
        
        template<class IT>
        struct ArgAdapter<IT,   enable_if<__and_< is_base_of<IterSource<typename IT::value_type>, typename IT::Source>
                                                 , is_base_of<IterSource<typename IT::value_type>, remove_reference_t<Arg>>
                                                 > >>
          {
            using Source = typename IT::Source;
            
            static auto
            wrap (function<Sig> rawFun)       
              {
                return [rawFun](IT& iter) -> Res { return rawFun(iter.source()); };
              }
          };
        
        
        
        static auto
        adaptFunctor (FUN&& rawFunctor)
          {
            return function<Res(SRC&)> {ArgAdapter<SRC>::wrap (forward<FUN> (rawFunctor))};
          }
      };
    
    
    template<typename FUN, typename SRC>
    inline void
    static_assert_isPredicate()
    {
      using Res = typename _FunTraits<FUN,SRC>::Res;
      static_assert(std::is_constructible<bool, Res>::value, "Functor must be a predicate");
    }
    
    
    template<class SRC, class FUN>
    struct _ReduceTraits
      {
        using Result = typename iter_explorer::_FunTraits<FUN,SRC>::Res;
        using ResVal = typename lib::meta::RefTraits<Result>::Value;
      };
    
    
    
    
    
    template<class SRC>
    struct BaseAdapter
      : SRC
      {
        BaseAdapter() = default;
        BaseAdapter(SRC const& src) : SRC{src}                { }
        BaseAdapter(SRC && src)     : SRC{forward<SRC> (src)} { }
        
        void expandChildren() { }
        size_t depth()  const { return 0; }
      };
    
    
    template<class SRC, class RES>
    class Expander
      : public SRC
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
        using _Trait = _ExpanderTraits<SRC,RES>;
        using ResIter = typename _Trait::ResIter;
        using RootExpandFunctor = function<RES(SRC&)>;
        using ChldExpandFunctor = function<RES(ResIter&)>;
        
        RootExpandFunctor expandRoot_;
        ChldExpandFunctor expandChild_;
        
        IterStack<ResIter> expansions_;
        
      public:
        Expander() =default;
        // inherited default copy operations
        
        template<typename FUN>
        Expander (SRC&& parentExplorer, FUN&& expandFunctor)
          : SRC{move (parentExplorer)}                   // NOTE: slicing move to strip IterExplorer (Builder)
          , expandRoot_ {_FunTraits<FUN,SRC>    ::adaptFunctor (forward<FUN> (expandFunctor))}  // adapt to accept SRC&
          , expandChild_{_FunTraits<FUN,ResIter>::adaptFunctor (forward<FUN> (expandFunctor))}  // adapt to accept RES&
          , expansions_{}
          { }
        
        
        
        void
        expandChildren()
          {
            REQUIRE (this->checkPoint(), "attempt to expand an empty explorer");
            REQUIRE (invariant());
            
            ResIter expanded{ hasChildren()? expandChild_(*expansions_)
                                           : expandRoot_(*this)};
            if (not isnil(expanded))
              expansions_.push (move(expanded)); // note: source of expansion retained
            else
              iterNext();  // expansion unsuccessful, thus consume source immediately
            
            ENSURE (invariant());
          }
        
        size_t
        depth()  const
          {
            return expansions_.size();
          }
        
        void
        rootCurrent()
          {
            if (not hasChildren()) return;
            static_cast<SRC&> (*this) = move (*expansions_);
            expansions_.clear();
          }
        
        
      public: /* === Iteration control API for IterableDecorator === */
        
        using value_type = typename _Trait::value_type;
        using reference = typename _Trait::reference;
        using pointer = typename _Trait::pointer;
        
        
        bool
        checkPoint()  const
          {
            ENSURE (invariant());
            
            return hasChildren()
                or SRC::isValid();
          }
        
        reference
        yield()  const
          {
            return hasChildren()? **expansions_
                                : **this;
          }
        
        void
        iterNext()
          {
            incrementCurrent();
            dropExhaustedChildren();
            ENSURE (invariant());
          }
        
      private:
        bool
        invariant()  const
          {
            return not hasChildren()
                or expansions_->isValid();
          }
        
        void
        incrementCurrent()
          {
            if (hasChildren())
              ++(*expansions_);
            else
              ++(*this);
          }
        
        
      protected:
        bool
        hasChildren()  const
          {
            return 0 < depth();
          }
        
        ResIter&
        accessCurrentChildIter()
          {
            REQUIRE (hasChildren());
            return *expansions_;
          }
        
        void
        dropExhaustedChildren()
          {
            while (not invariant())
              {
                ++expansions_;      // pop expansion stack (to reinstate invariant)
                incrementCurrent(); // consume source of innermost expansion
              }
          }
      };
    
    
    
    template<class SRC>
    class AutoExpander
      : public SRC
      {
        static_assert(is_StateCore<SRC>::value, "need wrapped state core as predecessor in pipeline");
        
      public:
        using SRC::SRC;
        
        void
        iterNext()
          {
            SRC::__throw_if_empty();
            SRC::expandChildren();
          }
      };
    
    
    
    template<class SRC>
    class ScheduledExpander
      : public SRC
      {
        static_assert(is_StateCore<SRC>::value, "need wrapped state core as predecessor in pipeline");
        
        bool shallExpand_ = false;
        
      public:
        using SRC::SRC;
        
        void
        expandChildren()
          {
            shallExpand_ = true;
          }
        
        void
        iterNext()
          {
            if (shallExpand_)
              {
                SRC::__throw_if_empty();
                SRC::expandChildren();
                shallExpand_ = false;
              }
            else
              SRC::iterNext();
          }
      };
    
    
    
    template<class SRC, class RES>
    class Transformer
      : public SRC
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
        using TransformFunctor = function<RES(SRC&)>;
        using TransformedItem = wrapper::ItemWrapper<RES>;
        
        TransformFunctor trafo_;
        TransformedItem treated_;
        
      public:
        using value_type = typename meta::ValueTypeBinding<RES>::value_type;
        using reference  = typename meta::ValueTypeBinding<RES>::reference;
        using pointer    = typename meta::ValueTypeBinding<RES>::pointer;
        
        
        Transformer() =default;
        // inherited default copy operations
        
        template<typename FUN>
        Transformer (SRC&& dataSrc, FUN&& transformFunctor)
          : SRC{move (dataSrc)}                            // NOTE: slicing move to strip IterExplorer (Builder)
          , trafo_{_FunTraits<FUN,SRC>::adaptFunctor (forward<FUN> (transformFunctor))}
          { }
        
        
        void
        expandChildren()
          {
            treated_.reset();
            SRC::expandChildren();
          }
        
      public: /* === Iteration control API for IterableDecorator === */
        
        bool
        checkPoint()  const
          {
            return bool(srcIter());
          }
        
        reference
        yield()  const
          {
            return unConst(this)->invokeTransformation();
          }
        
        void
        iterNext()
          {
            ++ srcIter();
            treated_.reset();
          }
        
      private:
        SRC&
        srcIter()  const
          {
            return unConst(*this);
          }
        
        reference
        invokeTransformation ()
          {
            if (not treated_)  // invoke transform function once per src item
              treated_ = trafo_(srcIter());
            return *treated_;
          }
      };
    
    
    
    template<class SRC, class RES, uint grp>
    class Grouping
      : public SRC
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
      protected:
        using Group = std::array<RES, grp>;
        using Iter  = typename Group::iterator;
        struct Buffer
          : lib::UninitialisedStorage<RES,grp>
          {
            Group& group(){ return *this;          }
            Iter begin()  { return group().begin();}
            Iter end()    { return group().end();  }
          };
        Buffer buff_;
        uint   pos_{0};
        
        
      public:
        using value_type = Group;
        using reference  = Group&;
        using pointer    = Group*;

        Grouping() =default;
        // inherited default copy operations
        
        Grouping (SRC&& dataSrc)
          : SRC{move (dataSrc)}
          {
            pullGroup(); // initially pull to establish the invariant
          }
        
        
        auto
        getGroupedElms()
          {
            ENSURE (buff_.begin()+pos_ <= buff_.end());
                   // Array iterators are actually pointers
            return RangeIter{buff_.begin(), buff_.begin()+pos_};
          }
        
        auto
        getRestElms()
          {
            return checkPoint()? RangeIter<Iter>()
                               : getGroupedElms();
          }
        
        void
        expandChildren()
          {
            SRC::expandChildren();
            pullGroup();
          }
        
      public: /* === Iteration control API for IterableDecorator === */
        
        bool
        checkPoint()  const
          {
            return pos_ == grp;
          }
        
        reference
        yield()  const
          {
            return unConst(buff_).group();
          }
        
        void
        iterNext()
          {
            pullGroup();
          }
        
        
      protected:
        SRC&
        srcIter()  const
          {
            return unConst(*this);
          }
        
        void
        pullGroup ()
          {
            for (pos_=0
                ; pos_<grp and srcIter()
                ; ++pos_,++srcIter()
                )
              buff_.group()[pos_] = *srcIter();
          }
      };
    
    
    
    template<class SRC, typename AGG, class GRP>
    class GroupAggregator
      : public SRC
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
      protected:
        using SrcValue   = typename meta::ValueTypeBinding<SRC>::value_type;
        using Grouping   = function<GRP(SRC&)>;
        using Aggregator = function<void(AGG&, SrcValue&)>;
        
        std::optional<AGG> agg_{};
        
        Grouping   grouping_;
        Aggregator aggregate_;
        
      public:
        using value_type = typename meta::RefTraits<AGG>::Value;
        using reference  = typename meta::RefTraits<AGG>::Reference;
        using pointer    = typename meta::RefTraits<AGG>::Pointer;

        GroupAggregator() =default;
        // inherited default copy operations
        
        template<class FGRP, class FAGG>
        GroupAggregator (SRC&& dataSrc, FGRP&& groupFun, FAGG&& aggFun)
          : SRC{move (dataSrc)}
          , grouping_{_FunTraits<FGRP,SRC>::adaptFunctor (forward<FGRP> (groupFun))}
          , aggregate_{forward<FAGG> (aggFun)}
          {
            pullGroup(); // initially pull to establish the invariant
          }
        
        
      public: /* === Iteration control API for IterableDecorator === */
        bool
        checkPoint()  const
          {
            return bool(agg_);
          }
        
        reference
        yield()  const
          {
            return *unConst(this)->agg_;
          }
        
        void
        iterNext()
          {
            if (srcIter())
              pullGroup();
            else
              agg_ = std::nullopt;
          }
        
        
      protected:
        SRC&
        srcIter()  const
          {
            return unConst(*this);
          }
        
        void
        pullGroup()
          {
            GRP group = grouping_(srcIter());
            agg_ = AGG{};
            do{
                aggregate_(*agg_, *srcIter());
                ++ srcIter();
              }
            while (srcIter() and group == grouping_(srcIter()));
          }
      };
    
    
    
    
    template<class SRC>
    class Filter
      : public SRC
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
      protected:
        using FilterPredicate = function<bool(SRC&)>;
        
        FilterPredicate predicate_;
        
      public:
        
        Filter() =default;
        // inherited default copy operations
        
        template<typename FUN>
        Filter (SRC&& dataSrc, FUN&& filterFun)
          : SRC{move (dataSrc)}
          , predicate_{_FunTraits<FUN,SRC>::adaptFunctor (forward<FUN> (filterFun))}
          {
            pullFilter(); // initially pull to establish the invariant
          }
        
        
        void
        expandChildren()
          {
            SRC::expandChildren();
            pullFilter();
          }
        
      public: /* === Iteration control API for IterableDecorator === */
        
        bool
        checkPoint()  const
          {
            return bool(srcIter());
          }
        
        typename SRC::reference
        yield()  const
          {
            return *srcIter();
          }
        
        void
        iterNext()
          {
            ++ srcIter();
            pullFilter();
          }
        
        
      protected:
        SRC&
        srcIter()  const
          {
            return unConst(*this);
          }
        
        bool
        isDisabled()  const
          {
            return not bool{predicate_};
          }
        
        void
        pullFilter ()
          {
            if (isDisabled()) return;
            while (srcIter() and not predicate_(srcIter()))
              ++srcIter();
          }
      };
    
    
    
    template<class SRC>
    class MutableFilter
      : public Filter<SRC>
      {
        using _Filter = Filter<SRC>;
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
      public:
        MutableFilter() =default;
        // inherited default copy operations
        
        template<typename FUN>
        MutableFilter (SRC&& dataSrc, FUN&& filterFun)
          : _Filter{move (dataSrc), forward<FUN> (filterFun)}
          { }
        
        
      public: /* === API to Remould the Filter condition underway === */
        
        template<typename COND>
        void
        andFilter (COND&& conjunctiveClause)
          {
            remouldFilter (forward<COND> (conjunctiveClause)
                          ,[](auto first, auto chain)
                             {
                               return [=](auto& val)
                                         {
                                           return first(val)
                                              and chain(val);
                                         };
                             });
          }
        
        template<typename COND>
        void
        andNotFilter (COND&& conjunctiveClause)
          {
            remouldFilter (forward<COND> (conjunctiveClause)
                          ,[](auto first, auto chain)
                             {
                               return [=](auto& val)
                                         {
                                           return first(val)
                                              and not chain(val);
                                         };
                             });
          }
        
        template<typename COND>
        void
        orFilter (COND&& disjunctiveClause)
          {
            remouldFilter (forward<COND> (disjunctiveClause)
                          ,[](auto first, auto chain)
                             {
                               return [=](auto& val)
                                         {
                                           return first(val)
                                               or chain(val);
                                         };
                             });
          }
        
        template<typename COND>
        void
        orNotFilter (COND&& disjunctiveClause)
          {
            remouldFilter (forward<COND> (disjunctiveClause)
                          ,[](auto first, auto chain)
                             {
                               return [=](auto& val)
                                         {
                                           return first(val)
                                               or not chain(val);
                                         };
                             });
          }
        
        void
        flipFilter()
          {
            auto dummy = [](auto){ return false; };
            remouldFilter (dummy
                          ,[](auto currentFilter, auto)
                             {
                               return [=](auto& val)
                                         {
                                           return not currentFilter(val);
                                         };
                             });
          }
        
        template<typename COND>
        void
        setNewFilter (COND&& entirelyDifferentPredicate)
          {
            remouldFilter (forward<COND> (entirelyDifferentPredicate)
                          ,[](auto, auto chain)
                             {
                               return [=](auto& val)
                                         {
                                           return chain(val);
                                         };
                             });
          }
        
        void
        disableFilter()
          {
            _Filter::predicate_ = nullptr;
          }
        
        
      private:
        template<typename COND, class COMB>
        void
        remouldFilter (COND&& additionalClause, COMB buildCombinedClause)
          {
            static_assert_isPredicate<COND,SRC>();
            
            if (_Filter::isDisabled())
              _Filter::predicate_ = ACCEPT_ALL;
            
            _Filter::predicate_ = buildCombinedClause (_Filter::predicate_   // pick up the existing filter predicate
                                                      ,_FunTraits<COND,SRC>::adaptFunctor (forward<COND> (additionalClause))
                                                      );                   //   wrap the extension predicate in a similar way
            _Filter::pullFilter();                                        //    then pull to re-establish the Invariant
          }
      };                                                                
    
    
    
    template<class SRC>
    class StopTrigger
      : public IterStateCore<SRC>
      {
        static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
        
        using Core = IterStateCore<SRC>;
        using Cond = function<bool(SRC&)>;
        
        Cond whileCondition_;
        
      public:
        
        StopTrigger() =default;
        // inherited default copy operations
        
        template<typename FUN>
        StopTrigger (SRC&& dataSrc, FUN&& condition)
          : Core{move (dataSrc)}
          , whileCondition_{_FunTraits<FUN,SRC>::adaptFunctor (forward<FUN> (condition))}
          { }
        
        
        bool
        checkPoint()  const
          {
            return Core::checkPoint()
               and whileCondition_(Core::srcIter());
          }
      };
    
    
    
    
    template<typename VAL>
    class ChildExpandableSource
      {
      protected:
         ~ChildExpandableSource() { }    
      public:
          virtual VAL* expandChildren()  =0;
          virtual size_t depth()  const  =0;
      };
    
    template<class SRC>
    class PackagedIterExplorerSource
      : public WrappedLumieraIter<SRC>
      , public ChildExpandableSource<typename SRC::value_type>
      {
        using Parent = WrappedLumieraIter<SRC>;
        using Val = typename SRC::value_type;                             
        
       ~PackagedIterExplorerSource() { }
      public:
        using Parent::Parent;
        
        virtual Val*
        expandChildren()  override
          {
            Parent::wrappedIter().expandChildren();
            return Parent::wrappedIter()?  & *Parent::wrappedIter()       
                                        : nullptr;
          }
        
        virtual size_t
        depth()  const override
          {
            return Parent::wrappedIter().depth();
          }
      };
    
  }//(End)Iterator decorating layer implementation
  
  
  
  
  
  template<typename VAL>
  struct IterExploreSource
    : IterSource<VAL>::iterator
    {
      using Expandable = iter_explorer::ChildExpandableSource<VAL>;
      
      
      IterExploreSource()  =default;
      // inherited default copy operations
      
      
      void
      expandChildren()
        {
          VAL* changedResult = expandableSource().expandChildren();
          this->resetPos (changedResult);                                 
        }
        
      size_t
      depth()  const
        {
          return expandableSource().depth();
        }
      
      
    private:
      template<class SRC>
      friend class IterExplorer;
      
      template<class IT>
      IterExploreSource (IT&& opaqueSrcPipeline)
        : IterSource<VAL>::iterator {
            IterSource<VAL>::build (
              new iter_explorer::PackagedIterExplorerSource<IT> {
                move (opaqueSrcPipeline)})}
      { }
      
      Expandable&
      expandableSource()  const
        {
          if (not this->source())
            throw error::State ("operating on a disabled default constructed IterExplorer"
                               ,error::LUMIERA_ERROR_BOTTOM_VALUE);
          
          auto source = unConst(this)->source().get();
          return dynamic_cast<Expandable&> (*source);
        }
    };
  
  
  
  
  
  /* ======= IterExplorer pipeline builder and iterator ======= */
  
  template<class SRC>
  class IterExplorer
    : public SRC
    {
      static_assert(can_IterForEach<SRC>::value, "Lumiera Iterator required as source");
      
      
    public:
      using value_type = typename meta::ValueTypeBinding<SRC>::value_type;
      using reference  = typename meta::ValueTypeBinding<SRC>::reference;
      using pointer    = typename meta::ValueTypeBinding<SRC>::pointer;
      
      using SRC::SRC;
      
      
      
      /* ==== Builder functions ==== */
      
      template<class FUN>
      auto
      expand (FUN&& expandFunctor)
        {
          using ExpandedChildren = typename iter_explorer::_FunTraits<FUN,SRC>::Res;
          
          using ResCore = iter_explorer::Expander<SRC, ExpandedChildren>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this), forward<FUN>(expandFunctor)});
        }
      
      
      auto
      expandAll()
        {
          using ResCore = iter_explorer::AutoExpander<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this)});
        }
      
      template<class FUN>
      auto
      expandAll (FUN&& expandFunctor)
        {
          return this->expand (forward<FUN> (expandFunctor))
                      .expandAll();
        }
      
      
      auto
      expandOnIteration()
        {
          using ResCore = iter_explorer::ScheduledExpander<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this)});
        }
      
      
      template<class FUN>
      auto
      transform (FUN&& transformFunctor)
        {
          using Product = typename iter_explorer::_FunTraits<FUN,SRC>::Res;
          
          using ResCore = iter_explorer::Transformer<SRC, Product>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this), forward<FUN>(transformFunctor)});
        }
      
      
      template<uint grp>
      auto
      grouped()
        {
          using Value   = typename meta::ValueTypeBinding<SRC>::value_type;
          using ResCore = iter_explorer::Grouping<SRC, Value, grp>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this)});
        }
      
      
      template<class FGRP, class FAGG>
      auto
      groupedBy (FGRP&& groupFun, FAGG&& aggFun)
        {
          using GroupVal = typename iter_explorer::_FunTraits<FGRP,SRC>::Res;
          
          static_assert (meta::is_BinaryFun<FAGG>());
          using ArgType1  = typename _Fun<FAGG>::Args::List::Head;
          using Aggregate = typename meta::RefTraits<ArgType1>::Value;
          
          using ResCore = iter_explorer::GroupAggregator<SRC, Aggregate, GroupVal>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this)
                                                ,forward<FGRP> (groupFun)
                                                ,forward<FAGG> (aggFun)});
        }
      
      template<class FGRP>
      auto
      groupedBy (FGRP&& groupFun)
        {
          using Value   = typename meta::ValueTypeBinding<SRC>::value_type;
          return groupedBy (forward<FGRP> (groupFun)
                           ,[](Value& agg, Value const& val){ agg += val; }
                           );
        }
      
      
      template<class FUN>
      auto
      iterWhile (FUN&& whileCond)
        {
          iter_explorer::static_assert_isPredicate<FUN,SRC>();
          
          using ResCore = iter_explorer::StopTrigger<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this), forward<FUN>(whileCond)});
        }
      
      
      template<class FUN>
      auto
      iterUntil (FUN&& untilCond)
        {
          iter_explorer::static_assert_isPredicate<FUN,SRC>();
          
          using ResCore = iter_explorer::StopTrigger<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          using ArgType = typename iter_explorer::_FunTraits<FUN,SRC>::Arg;
          
          return IterExplorer<ResIter> (ResCore { move(*this)
                                                ,[whileCond = forward<FUN>(untilCond)](ArgType val)
                                                  {
                                                    return not whileCond(val);
                                                  }
                                                });
        }
      
      
      template<class FUN>
      auto
      filter (FUN&& filterPredicate)
        {
          iter_explorer::static_assert_isPredicate<FUN,SRC>();
          
          using ResCore = iter_explorer::Filter<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this), forward<FUN>(filterPredicate)});
        }
      
      
      template<class FUN>
      auto
      mutableFilter (FUN&& filterPredicate)
        {
          iter_explorer::static_assert_isPredicate<FUN,SRC>();
          
          using ResCore = iter_explorer::MutableFilter<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this), forward<FUN>(filterPredicate)});
        }
      
      
      auto
      mutableFilter()
        {
          return mutableFilter (iter_explorer::ACCEPT_ALL);
        }
      
      
      
      template<template<class> class LAY>
      auto
      processingLayer()
        {
          using ResCore = LAY<SRC>;
          using ResIter = typename _DecoratorTraits<ResCore>::SrcIter;
          
          return IterExplorer<ResIter> (ResCore {move(*this)});
        }
      
      
      
      auto
      asPtr()
        {
          using Val = typename meta::ValueTypeBinding<SRC>::value_type;
          static_assert (not std::is_pointer_v<Val>);
          return IterExplorer::transform ([](Val& ref){ return &ref; });
        }
      
      auto
      derefPtr()
        {
          using Ptr = typename meta::ValueTypeBinding<SRC>::value_type;
          return IterExplorer::transform ([](Ptr ptr){ return *ptr; });
        }
      
      
      
      IterExploreSource<value_type>
      asIterSource()
        {
          return IterExploreSource<value_type> {move(*this)};
        }
      
      
      SRC
      asIterator()
        {
          return SRC {move(*this)};
        }
      
      template<class FUN>
      void
      foreach (FUN&& consumer)
        {
          auto consumeFun = iter_explorer::_FunTraits<FUN,SRC>::adaptFunctor (forward<FUN> (consumer));
          SRC& pipeline = *this;
          for ( ; pipeline; ++pipeline)
            consumeFun (pipeline);
        }
      
      
      template<class FUN
              ,typename COMB =decltype(std::plus<>())
              ,typename VAL  =typename iter_explorer::_ReduceTraits<SRC,FUN>::ResVal>
      VAL
      reduce (FUN&& accessor
             ,COMB junctor  =COMB()
             ,VAL seedVal   =VAL())
        {
          auto accessVal = iter_explorer::_FunTraits<FUN,SRC>::adaptFunctor (forward<FUN> (accessor));
          
          VAL sum{move(seedVal)};
          IterExplorer::foreach ([&](SRC& srcIter){ sum = junctor (sum, accessVal(srcIter)); });
          return sum;
        }
      
      auto
      resultSum()
        {
          return IterExplorer::reduce ([](const reference val){ return val; });
        }
      
      size_t
      count()
        {
          return IterExplorer::reduce ([](auto){ return size_t(1); });
        }
      
      bool
      has_any()
        {
          static_assert (std::is_constructible<bool,value_type>());
          SRC& pipeline = *this;
          for ( ; pipeline; ++pipeline)
            if (*pipeline)
              return true;
          return false;
        }
      
      bool
      and_all()
        {
          static_assert (std::is_constructible<bool,value_type>());
          SRC& pipeline = *this;
          for ( ; pipeline; ++pipeline)
            if (not *pipeline)
              return false;
          return true;
        }
      
      
      template<template<typename> class CON =std::vector>
      auto
      effuse()
        {
          CON<value_type> con{};
          this->effuse (con);
          return con;
        }
      
      template<class CON>
      auto
      effuse (CON&& sink) -> CON
        {
          CON con{move(sink)};
          this->effuse (con);
          return con;
        }
      
      template<class CON>
      void
      effuse (CON& con)
        {
          for (auto& val : *this)
            con.push_back (val);
        }
    };
  
  
  
  
  
  
  
  
  /* ==== convenient builder free functions ==== */
  
  template<class IT>
  inline auto
  explore (IT&& srcSeq)
  {
    using SrcIter = typename _DecoratorTraits<IT>::SrcIter;
    using Base = iter_explorer::BaseAdapter<SrcIter>;
    
    return IterExplorer<Base> (std::forward<IT> (srcSeq));
  }
  
  
} // namespace lib
#endif /* LIB_ITER_EXPLORER_H */