iter-adapter.hpp

Go to the documentation of this file.

/*
  ITER-ADAPTER.hpp  -  helpers for building simple forward iterators

   Copyright (C)
     2009,            Hermann Vosseler <Ichthyostega@web.de>
     2017,2024,       Hermann Vosseler <Ichthyostega@web.de>

  **Lumiera** 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. See the file COPYING for further details.

*/

#ifndef LIB_ITER_ADAPTER_H
#define LIB_ITER_ADAPTER_H


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

#include <iterator>


namespace util {   // see lib/util.hpp
  template<class OBJ>
  OBJ* unConst (const OBJ*);
  template<class OBJ>
  OBJ& unConst (OBJ const&);
}

namespace lib {
  
  
  namespace { // internal helpers
    inline void
    _throwIterExhausted()
    {
      throw lumiera::error::Invalid ("Can't iterate further",
            lumiera::error::LUMIERA_ERROR_ITER_EXHAUST);
    }
  }
  
#define ENABLE_USE_IN_STD_RANGE_FOR_LOOPS(ITER)                              \
      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;

#define LIFT_PARENT_INCREMENT_OPERATOR(_BASECLASS_)\
      auto&                       \
      operator++()                 \
        {                           \
          _BASECLASS_::operator++(); \
          return *this;               \
        }
  
  
  namespace iter {
    template<class IT>
    using Yield = decltype(std::declval<IT>().operator*());
    
    template<class COR>
    using CoreYield = decltype(std::declval<COR>().yield());
    
  }
  
  

  template<class POS, class CON>
  class IterAdapter
    {
      CON source_;
      mutable POS pos_;
      
      using _ValTrait = meta::ValueTypeBinding<std::remove_pointer_t<POS>>;
      
    public:
      using value_type = typename _ValTrait::value_type;
      using reference = typename _ValTrait::reference;
      using pointer = typename _ValTrait::pointer;
      
      
      IterAdapter (CON src, POS const& startpos)
        : source_(src)
        , pos_(startpos)
        {
          check();
        }
      
      IterAdapter ()
        : source_()
        , pos_()
        { }
      
      explicit
      operator bool() const
        {
          return isValid();
        }
      
      
      /* === lumiera forward iterator concept === */
      
      reference
      operator*() const
        {
          _maybe_throw();
          return *pos_;
        }
      
      pointer
      operator->() const
        {
          _maybe_throw();
          return & *pos_;
        }
      
      IterAdapter&
      operator++()
        {
          _maybe_throw();
          iterate();
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return check();
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
      
    protected: /* === iteration control interface === */
      
      bool
      check()  const
        {
          return source_ && checkPoint (source_,pos_);           // extension point: free function checkPoint(...)
        }
      
      void
      iterate()
        {
          iterNext (source_,pos_);                               // extension point: free function iterNext(...)
          check();
        }    // checkPoint() might mark end condition
            //  for comparison with IterAdapter{}
      
      
      
    protected:
      using ConRef = typename meta::RefTraits<CON>::Reference;
      
      ConRef       source()       { return                source_; }
      const ConRef source() const { return unConst(this)->source_; }
      
      void
      resetPos (POS otherPos)                                    
        {
          pos_ = otherPos;
          check();
        }
      
    private:
      void
      _maybe_throw()  const
        {
          if (not isValid())
            _throwIterExhausted();
        }
      
      
    public:
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (IterAdapter);
      
      template<class P1, class P2, class CX>
      friend bool operator== (IterAdapter<P1,CX> const&, IterAdapter<P2,CX> const&);
    };
  
  
  template<class P1, class P2, class CON>
  inline bool operator== (IterAdapter<P1,CON> const& il, IterAdapter<P2,CON> const& ir)  { return il.pos_ == ir.pos_; }
  
  template<class P1, class P2, class CON>
  inline bool operator!= (IterAdapter<P1,CON> const& il, IterAdapter<P2,CON> const& ir)  { return not (il == ir); }
  
  
  

  template<class ST, typename T =iter::CoreYield<ST>>
  class IterStateWrapper
    {
      ST core_;
      
    public:
      using value_type = typename meta::RefTraits<T>::Value;
      using reference  = typename meta::RefTraits<T>::Reference;
      using pointer    = typename meta::RefTraits<T>::Pointer;
      
      IterStateWrapper (ST&& initialState)
        : core_(std::forward<ST>(initialState))
        { }
      
      IterStateWrapper (ST const& initialState)
        : core_(initialState)
        { }
      
      IterStateWrapper ()
        : core_()
        { }
      
      explicit
      operator bool() const
        {
          return isValid();
        }
      
      
      /* === lumiera forward iterator concept === */
      
      T
      operator*() const
        {
          __throw_if_empty();
          return core_.yield();      // core interface: yield
        }
      
      pointer
      operator->() const
        {
          if constexpr (meta::isLRef_v<T>)
            {
              __throw_if_empty();
              return & core_.yield();    // core interface: yield
            }
          else
            static_assert (!sizeof(T),
               "can not provide operator-> "
               "since iterator pipeline generates a value");
        }
      
      IterStateWrapper&
      operator++()
        {
          __throw_if_empty();
          core_.iterNext();          // core interface: iterNext
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return core_.checkPoint(); // core interface: checkPoint
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
    protected:
      
      ST &      stateCore()       { return core_; }
      ST const& stateCore() const { return core_; }
      
      void
      __throw_if_empty()  const
        {
          if (not isValid())
            _throwIterExhausted();
        }
      
      
      
    public:
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (IterStateWrapper);
      
      template<class STX, class T1, class T2>
      friend bool operator== (IterStateWrapper<STX,T1> const&, IterStateWrapper<STX,T2> const&);
    };
  
  
  
  template<class ST, class T1, class T2>
  inline bool
  operator== (IterStateWrapper<ST,T1> const& il, IterStateWrapper<ST,T2> const& ir)
  {
    return (il.empty()   and ir.empty())
        or (il.isValid() and ir.isValid() and il.core_ == ir.core_);
  }
  
  template<class ST, class T1, class T2>
  inline bool
  operator!= (IterStateWrapper<ST,T1> const& il, IterStateWrapper<ST,T2> const& ir)
  {
    return not (il == ir);
  }
  
  
  
  
  template<class IT>
  class IterStateCore
    : public IT
    {
      static_assert (lib::meta::can_IterForEach<IT>::value
                    ,"Lumiera Iterator required as source");
    protected:
      IT&
      srcIter()  const
        {
          return util::unConst(*this);
        }
      
    public:
      using IT::IT;
      
      /* === state protocol API for IterStateWrapper === */
      bool
      checkPoint()  const
        {
          return bool(srcIter());
        }
      
      typename IT::reference
      yield()  const
        {
          return *srcIter();
        }
      
      void
      iterNext()
        {
          ++ srcIter();
        }
    };
  
  
  
  template<class COR>
  class CheckedCore
    : public COR
    {
      static_assert (lib::meta::is_StateCore<COR>::value
                    ,"Adapted type must expose a »state core« API");
    protected:
      COR&
      _rawCore()  const
        {
          return util::unConst(*this);
        }
      
      void
      __throw_if_empty()  const
        {
          if (not checkPoint())
            _throwIterExhausted();
        }
      
    public:
      template<typename...ARGS>
      CheckedCore (ARGS&& ...init)
        : COR(std::forward<ARGS>(init)...)
        { }
      
      CheckedCore()                               =default;
      CheckedCore (CheckedCore&&)                 =default;
      CheckedCore (CheckedCore const&)            =default;
      CheckedCore& operator= (CheckedCore&&)      =default;
      CheckedCore& operator= (CheckedCore const&) =default;
      
      using TAG_CheckedCore_Raw = COR;        
      
      
      /* === state protocol API for IterStateWrapper === */
      bool
      checkPoint()  const
        {
          return _rawCore().checkPoint();
        }
      
      decltype(auto)
      yield()  const
        {
          __throw_if_empty();
          return _rawCore().yield();
        }
      
      void
      iterNext()
        {
          __throw_if_empty();
          _rawCore().iterNext();
        }
    };
  
  
  
  template<class CON>
  class ContainerCore
    : public CON
    {
      using Iter = typename CON::iterator;
      
      Iter p_;
      
    public:
      ContainerCore (CON&& container)
        : CON(std::forward<CON>(container))
        , p_{CON::begin()}
        { }
      
      // copy and assignment acceptable (warning!)
      
      
      /* === »state core« protocol API === */
      bool
      checkPoint()  const
        {
          return p_ != CON::end();
        }
      
      decltype(auto)
      yield()  const
        {
          return *p_;
        }
      
      void
      iterNext()
        {
          ++p_;
        }
    };
  
  
  
  
  template<class COR>
  class IterableDecorator
    : public COR
    {
      COR &      _core()       { return static_cast<COR&>       (*this); }
      COR const& _core() const { return static_cast<COR const&> (*this); }
      
    protected:
      void
      __throw_if_empty()  const
        {
          if (not isValid())
            _throwIterExhausted();
        }
      
    public:
      using YieldRes   = iter::CoreYield<COR>;
      using value_type = typename meta::RefTraits<YieldRes>::Value;
      using reference  = typename meta::RefTraits<YieldRes>::Reference;
      using pointer    = typename meta::RefTraits<YieldRes>::Pointer;
      
      
      template<typename...ARGS>
      IterableDecorator (ARGS&& ...init)
        : COR(std::forward<ARGS>(init)...)
        { }
      
      IterableDecorator()                                     =default;
      IterableDecorator (IterableDecorator&&)                 =default;
      IterableDecorator (IterableDecorator const&)            =default;
      IterableDecorator& operator= (IterableDecorator&&)      =default;
      IterableDecorator& operator= (IterableDecorator const&) =default;
      
      
      /* === lumiera forward iterator concept === */
      
      explicit operator bool() const { return isValid(); }
      
      YieldRes
      operator*() const
        {
          return _core().yield();          // core interface: yield
        }
      
      pointer
      operator->() const
        {
          if constexpr (meta::isLRef_v<YieldRes>)
            return & _core().yield();      // core interface: yield
          else
            static_assert (!sizeof(COR),
               "can not provide operator-> "
               "since iterator pipeline generates a value");
        }
      
      IterableDecorator&
      operator++()
        {
          _core().iterNext();              // core interface: iterNext
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return _core().checkPoint();     // core interface: checkPoint
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
      
      
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (IterableDecorator);
      
      
      friend bool
      operator== (IterableDecorator const& il, IterableDecorator const& ir)
      {
        return (il.empty()   and ir.empty())
            or (il.isValid() and ir.isValid() and il._core() == ir._core());
      }
      friend bool
      operator!= (IterableDecorator const& il, IterableDecorator const& ir)
      {
        return not (il == ir);
      }
    };
  
  
  
  
  
  
  
  template<class IT>
  class RangeIter
    {
      IT p_;
      IT e_;
      
      using _ValTrait = meta::ValueTypeBinding<meta::remove_pointer_t<IT>>;
      
    public:
      using pointer    = typename _ValTrait::pointer;
      using reference  = typename _ValTrait::reference;
      
      using value_type = typename std::remove_reference<reference>::type;
      
      
      RangeIter (IT const& start, IT const& end)
        : p_(start)
        , e_(end)
        { }
      
      RangeIter ()
        : p_()
        , e_()
        { }
      
      
      template<class I2>
      RangeIter (I2 const& oIter)
        : p_(oIter.getPos())
        , e_(oIter.getEnd())
        { }
      
      explicit
      operator bool() const
        {
          return isValid();
        }
      
      
      /* === lumiera forward iterator concept === */
      
      reference
      operator*() const
        {
          _maybe_throw();
          return *p_;
        }
      
      pointer
      operator->() const
        {
          _maybe_throw();
          return &(*p_);
        }
      
      RangeIter&
      operator++()
        {
          _maybe_throw();
          ++p_;
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return (p_!= IT()) && (p_ != e_);
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
      
      const IT&  getPos()  const { return p_; }
      const IT&  getEnd()  const { return e_; }
      
      
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (RangeIter);
      
      
    private:
      
      void
      _maybe_throw()  const
        {
          if (!isValid())
            _throwIterExhausted();
        }
    };
  
  
  
  template<class I1, class I2>
  inline bool operator== (RangeIter<I1> const& il, RangeIter<I2> const& ir)  { return (!il && !ir) || (il.getPos() == ir.getPos()); }
  
  template<class I1, class I2>
  inline bool operator!= (RangeIter<I1> const& il, RangeIter<I2> const& ir)  { return !(il == ir); }
  
  
  
  
  
  template<typename INT>
  class NumIter
    {
      INT i_;
      INT e_;
      
    public:
      typedef INT* pointer;
      typedef INT& reference;
      typedef INT  value_type;
      
      NumIter (INT start, INT end)
        : i_(start)
        , e_(end)
        { }
      
      template<typename X>
      NumIter (X&& start, X&& end)
        : i_(std::forward<X>(start))
        , e_(std::forward<X>(end))
        { }
      
      NumIter ()
        : i_()
        , e_()
        { }
      
      // standard copy operations acceptable
      
      explicit
      operator bool() const
        {
          return isValid();
        }
      
      
      
      /* === lumiera forward iterator concept === */
      
      value_type
      operator*() const
        {
          _maybe_throw();
          return i_;
        }
      
      NumIter&
      operator++()
        {
          _maybe_throw();
          ++i_;
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return i_ < e_;     // NOTE: use comparison to detect iteration end
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
      
      INT&  getPos()  const { return i_; }
      INT&  getEnd()  const { return e_; }
      
      
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (NumIter);
      
      
      bool operator!= (NumIter const& o) const  { return not operator==(o); }
      bool operator== (NumIter const& o) const  { return (empty() and o.empty())    // empty iters must be equal (Lumiera iter requirement)
                                                      or (i_ == o.i_ and e_ == o.e_); }
      
    private:
      void
      _maybe_throw()  const
        {
          if (!isValid())
            _throwIterExhausted();
        }
    };
  
  
  
  
  
  
  template<typename INT>
  inline NumIter<INT>
  eachNum (INT start = std::numeric_limits<INT>::min()
          ,INT end   = std::numeric_limits<INT>::max())
  {
    return NumIter<INT> (start, end);
  }
  
  
  
  
  
  
  
  template<class TY>
  struct IterType;
  
  template<template<class,class> class Iter, class TY, class CON>
  struct IterType<Iter<TY,CON>>
    {
      typedef CON Container;
      typedef TY  ElemType;
      
      template<class T2>
      struct SimilarIter  
        {
          typedef Iter<T2,CON> Type;
        };
    };
  
  template<class IT>
  struct IterType<RangeIter<IT>>
    : IterType<IT>
    {
      template<class T2>
      struct SimilarIter  
        {
          typedef typename IterType<IT>::template SimilarIter<T2>::Type WrappedIter;
          typedef RangeIter<WrappedIter> Type;
        };
    };
  
  
  
  template<class IT>
  class ConstIter
    {
      IT i_;  
      
      
    public:
      typedef const typename IT::value_type value_type;
      typedef const typename IT::pointer    pointer;
      typedef const typename IT::reference  reference;
      
      ConstIter (IT srcIter)
        : i_(srcIter)
        { }
      
      explicit
      operator bool() const
        {
          return isValid();
        }
      
      
      
      /* === lumiera forward iterator concept === */
      
      reference
      operator*() const
        {
          return *i_;
        }
      
      pointer
      operator->() const
        {
          return i_.operator->();
        }
      
      ConstIter&
      operator++()
        {
          ++i_;
          return *this;
        }
      
      bool
      isValid ()  const
        {
          return bool(i_);
        }
      
      bool
      empty ()    const
        {
          return not isValid();
        }
      
      
      IT const&
      getBase()  const
        {
          return i_;
        }
      
      
      ENABLE_USE_IN_STD_RANGE_FOR_LOOPS (ConstIter);
    };
  
  
  template<class I1, class I2>
  inline bool operator== (ConstIter<I1> const& il, ConstIter<I2> const& ir)  { return il.getBase() == ir.getBase(); }
    
  template<class I1, class I2>
  inline bool operator!= (ConstIter<I1> const& il, ConstIter<I2> const& ir)  { return not (il == ir); }
  
  
  
}// namespace lib
#endif /*LIB_ITER_ADAPTER_H*/