iterators.h

Go to the documentation of this file.

 
#include "elementa/license.inc"
#include "elementa/checks.inc"
 
#ifndef ELEMENTA_BASE_ITERATORS_H
#define ELEMENTA_BASE_ITERATORS_H
 
#include <memory>
#include <iterator>
#include <type_traits>
#include <limits>
#include <functional>
#include "elementa/base/definitions.h"
#include "elementa/base/fundamentaltypes.h"
#include "elementa/base/exceptions.h"
#include "elementa/patterns/validatable.h"
#include "elementa/patterns/clonable.h"
 
#include "elementa/base/debugging.h"
 
namespace elementa
{
 
namespace base
{
 
/* ====================================================================== 
 
            MULTIPLE-BEHAVIOUR ITERATORS
 
========================================================================= */
 
 
/* ***************************************************************************
 
    Abstract base template class: MultItImpl
    
*******************************************************************************/
 
 
template <class Data>
class MultItImpl: ELE_CLASS_VALIDATABLE, 
                  public elementa::patterns::ClonableShared<MultItImpl<Data>>
{
 public:
 
    using Ptr = std::shared_ptr<MultItImpl>;
 
    MultItImpl(void) {}
 
    MultItImpl(const MultItImpl & oth): Validatable{oth} 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"oth. valid = " << oth.valid());}
 
    MultItImpl & operator=(const MultItImpl & oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");  
            if (this != &oth) Validatable::operator=(oth); 
            return(*this); }
 
    MultItImpl(MultItImpl && oth):Validatable{std::move(oth)} 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); }
 
    MultItImpl & operator=(MultItImpl && oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");  
            if (this != &oth) Validatable::operator=(std::move(oth)); 
            return(*this); }
 
    virtual ~MultItImpl(void) = default;
 
 
    virtual Data & operator*(void) = 0;
 
 
    virtual Data * pointedData(void) const = 0;
 
 
    virtual MultItImpl & operator++(void) = 0;
 
 
    virtual bool isEnd(void) const 
        { return(valid() && (pointedData()==nullptr)); }
 
 
    void invalidate(void) { setInvalid(); }
 
    virtual MultItImpl & operator--(void) 
        { ELE_CODE_UNIMPLEMENTED; }
 
 
    virtual bool operator==(const MultItImpl & oth) const
        { return(valid() && oth.valid() && 
                 (pointedData() == oth.pointedData())); } 
 
 
    virtual bool operator!=(const MultItImpl & oth) const
        { return(!operator==(oth)); } 
 
 
    virtual std::string to_string(void) const 
        { return(std::string{"MultItImpl("} + 
                 std::to_string(to_number(this)) +
                 "; valid = " + 
                 kYesNoCString(elementa::patterns::Validatable::valid()) +
                 (elementa::patterns::Validatable::valid() ? 
                    "; pointed = " +
                    std::to_string(to_number(pointedData())) :
                    "") + 
                 ")" ); }
 
 static_assert( !std::is_void<Data>::value, 
                "MultItImpl cannot work with void Data" );
 
};
 
 
/* ***************************************************************************
 
    Template class: MultIterator
    
*******************************************************************************/
 
 
template <class Data, bool BIDIR = false>
class MultIterator final
{
 public:
 
    using Category = std::forward_iterator_tag;
 
    using T = Data;
 
    using Distance = std::ptrdiff_t;
 
    using Pointer = T*;
 
    using Reference = T&;
 
    using ImplementationPtr = typename MultItImpl<Data>::Ptr;
 
 
    MultIterator(ImplementationPtr impl = ImplementationPtr{}): 
                                                                    impl_{impl} 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"Creating new multiterator with "
                                              << (impl_.get() == nullptr ?
                                                    "null impl." :
                                                    impl_->to_string())); }
 
    MultIterator(const MultIterator & oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); copyFrom(oth); }
 
    MultIterator & operator=(const MultIterator & oth) 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");copyFrom(oth);return(*this);}
 
    MultIterator(MultIterator && oth) 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); copyFrom(oth); } 
 
    MultIterator & operator=(MultIterator && oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");copyFrom(oth);return(*this);}
 
    ~MultIterator(void) {}
 
    bool valid(void) const { return(impl_->valid()); }
 
    Reference operator*(void) const { return(impl_->operator*()); }
 
    MultIterator & operator++(void) 
        { impl_->operator++(); return(*this);}
 
    MultIterator & operator++(int) 
        { MultIterator copyme{*this}; impl_->operator++(); return(copyme); }
 
    bool operator==(const MultIterator & oth) const
        { return( impl_->operator==(*(oth.impl_)) ); } 
 
    bool operator!=(const MultIterator & oth) const
        { return( impl_->operator!=(*(oth.impl_)) ); }
 
    bool operator<(const MultIterator & oth) const
        { return( ((impl_->valid()) && (oth.impl_->valid()) &&
                  (impl_->pointedData() < oth.impl_->pointedData())) ); }
 
    void swap(MultIterator & oth) { std::swap(impl_,oth.impl_); }
 
    bool isEnd(void) const { return(impl_->isEnd()); }
 
    std::string to_string(void) const 
        { return(std::string{"FMultIterator(valid = "} +
                 kYesNoCString(impl_->valid()) + ", isend = " +
                 kYesNoCString(isEnd()) + ", " + 
                 (impl_.get() != nullptr ? impl_->to_string() : "null impl.") +
                 " )"); }
 
    ImplementationPtr implementation(void) const { return(impl_); }
    
 private:
 
    ImplementationPtr impl_;
 
    void copyFrom(const MultIterator & oth) 
        {ELE_CODE_TRACE_OFF; 
            ELE_CODE_TRACE({},"Cloning to this the impl of " <<oth.to_string());
            impl_ = oth.impl_->clone(); 
            ELE_CODE_TRACE({},"Cloned: " << to_string());}
    
 static_assert( !std::is_void<Data>::value, 
                "MultIterator cannot work with void Data" );
 
};
 
 
 
template <class Data>
class MultIterator<Data,true> final
{
 public:
 
    using Category = std::bidirectional_iterator_tag;
 
    using T = Data;
 
    using Distance = std::ptrdiff_t;
 
    using Pointer = T*;
 
    using Reference = T&;
 
    using ImplementationPtr = typename MultItImpl<Data>::Ptr;
 
 
    MultIterator(ImplementationPtr impl = ImplementationPtr{}): 
                                                                    impl_{impl} 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"Creating new multiterator with "
                                              << (impl_.get() == nullptr ?
                                                    "null impl." :
                                                    impl_->to_string())); }
 
    MultIterator(const MultIterator & oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); copyFrom(oth); }
 
    MultIterator & operator=(const MultIterator & oth) 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");copyFrom(oth);return(*this);}
 
    MultIterator(MultIterator && oth) 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); copyFrom(oth); } 
 
    MultIterator & operator=(MultIterator && oth)
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");copyFrom(oth);return(*this);}
 
    ~MultIterator(void) {}
 
    bool valid(void) const { return(impl_->valid()); }
 
    Reference operator*(void) const { return(impl_->operator*()); }
 
    MultIterator & operator++(void) 
        { impl_->operator++(); return(*this);}
 
    MultIterator & operator++(int) 
        { MultIterator copyme{*this}; impl_->operator++(); return(copyme); }
 
    MultIterator & operator--(void) 
        { impl_->operator--(); return(*this);}
 
    MultIterator & operator--(int) 
        { MultIterator copyme{*this}; impl_->operator--(); return(copyme); }
 
    bool operator==(const MultIterator & oth) const
        {   return( ((impl_->valid()) && (oth.impl_->valid()) &&
                     (impl_->pointedData() == oth.impl_->pointedData())) ); } 
 
    bool operator!=(const MultIterator & oth) const
        { return(!operator==(oth)); }
 
    bool operator<(const MultIterator & oth) const
        { return( ((impl_->valid()) && (oth.impl_->valid()) &&
                  (impl_->pointedData() < oth.impl_->pointedData())) ); }
 
    void swap(MultIterator & oth)
        { std::swap(impl_,oth.impl_); }
 
    bool isEnd(void) const 
        { return((impl_->valid())&&(impl_->pointedData()==nullptr)); }
 
    std::string to_string(void) const 
        { return(std::string{"BMultIterator( isend = "} +
                 kYesNoCString(isEnd()) + ", " + 
                 (impl_.get() != nullptr ? impl_->to_string() : "null impl.") +
                 " )"); }
 
    ImplementationPtr implementation(void) const { return(impl_); }
 
 private:
 
    ImplementationPtr impl_;
 
    void copyFrom(const MultIterator & oth) 
        {ELE_CODE_TRACE_OFF; 
            ELE_CODE_TRACE({},"Cloning to this the impl of " <<oth.to_string());
            impl_ = oth.impl_->clone(); 
            ELE_CODE_TRACE({},"Cloned: " << to_string());}
    
 static_assert( !std::is_void<Data>::value, 
                "MultIterator cannot work with void Data" );
};
 
 
template <class Data, bool BIDIR>
void swap(MultIterator<Data,BIDIR> & it1, MultIterator<Data,BIDIR> & it2) 
    { it1.swap(it2); }
 
 
 
/* ====================================================================== 
 
            RANGE EXTENSIONS
 
            Ranges are included in C++20. Here is a simple version of them
            that minimalistically respects their concepts and behaviours.
 
            The best explanations of ranges/views pre-C++20 final publication
            are:
 
            https://hannes.hauswedell.net/post/2018/04/11/view1/
            https://ezoeryou.github.io/blog/article/2019-01-10-range-view.html
 
            An existing range-library pre-C++20 final publication is:
 
            https://github.com/ericniebler/range-v3         
 
========================================================================= */
 
/* *****************************************************************************
 
    Abstract template class: Range
    
*******************************************************************************/
 
 
template <class It>
class Range
{
 public:
 
 
    virtual It begin(void) const = 0;
 
    virtual It end(void) const = 0;
};
 
 
/* *****************************************************************************
 
    Template class: SubView
    
*******************************************************************************/
 
 
template <class It>
class SubView: public Range<It>
{
 public:
 
 
    SubView(const It & itbeg, const It & itend):itbeg_{itbeg},itend_{itend} {}
 
    It begin(void) const { return(itbeg_); }
 
    It end(void) const { return(itend_); }
    
 private:
 
    It itbeg_;
    It itend_;
};
 
 
/* *****************************************************************************
 
    Template class: IotaView
    
*******************************************************************************/
 
 
template <typename IT = int>
class IotaView
{
 public:
 
    struct iterator_t
    {
        friend IotaView;
 
            iterator_t & operator++(void)
                { if ((!alwaysend_) && 
                      ((unbounded_) || (value_ < bound_))) 
                  {
                    if (value_ == std::numeric_limits<IT>::max()) 
                        alwaysend_ = true;
                    else ++value_; 
                  }
                  return(*this); }
 
            IT operator*(void) const { checkderef(); return(value_); }
 
            bool operator==(const iterator_t & oth) const noexcept
                { if (isend()) return(oth.isend());
                  else if (oth.isend()) return(false);
                  return(value_ == oth.value_); }
 
            bool operator!=(const iterator_t & oth) const noexcept
                { return(!operator==(oth)); }
 
        private:
 
            iterator_t(IT value, IT bound) noexcept:
                                            value_{value},bound_{bound},
                                            unbounded_{false},alwaysend_{false}
                {}
 
            iterator_t(IT value) noexcept:  value_{value},
                                            unbounded_{true},alwaysend_{false} 
                {}
 
            iterator_t(void) noexcept: alwaysend_{true},unbounded_{true} 
                {}
 
            bool isend(void) const noexcept 
                {ELE_CODE_TRACE_OFF; 
                 ELE_CODE_TRACE({},"returning " << 
                                    ((alwaysend_) || 
                                     ((!unbounded_) && (value_ == bound_))) <<
                                    " for " << to_number(this));
                 return((alwaysend_) || 
                         ((!unbounded_) && (value_ == bound_))); }
            void checkderef(void) const 
                { if (isend()) ELE_CODE_INVSTATE("Dereferencing end iterator");}
 
            IT value_;
            IT bound_;
            const bool unbounded_;
            bool alwaysend_;
    };
 
    IotaView(IT start, IT finish) noexcept: start_{start},finish_{finish},
                                            bounded_{true},alwaysend_{false} 
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"Created iotaview[" << start_ <<
                                              ", " << finish_ << "]"); }
 
    IotaView(IT start) noexcept:    start_{start},
                                    bounded_{false},alwaysend_{false}
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"Created iotaview[" << start_ <<
                                              ", infinity]"); }
 
    IotaView(void) noexcept: alwaysend_{true}
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"Created always end iotaview"); }
 
    iterator_t begin(void) const noexcept
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},"");
         return(alwaysend_ ? iterator_t{}:
                            (bounded_ ? iterator_t{start_,finish_} : 
                                        iterator_t{start_})); }
 
    iterator_t end(void) const noexcept
        {ELE_CODE_TRACE_OFF; ELE_CODE_TRACE({},""); return(iterator_t{}); }
 
 private:
 
    IT start_;
    IT finish_;
    bool bounded_;
    bool alwaysend_;
 
 static_assert( std::is_integral<IT>::value,
                "IotaView only works with integral types" );
};
 
  // Iterators
 
 
} // end namespace base
 
} // end namespace elementa
 
#endif