tbx/include/core/ring_iterator.h

/*!
 * \file cont/ring_iterator.h
 * \brief
 *      A ring/circular iterator.
 *
 * \copyright Copyright (C) 2021 Christos Choutouridis <christos@choutouridis.net>
 *
 * <dl class=\"section copyright\"><dt>License</dt><dd>
 * The MIT License (MIT)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 * </dd></dl>
 */

#ifndef TBX_CORE_RING_ITERATOR_H_
#define TBX_CORE_RING_ITERATOR_H_

#include <core/core.h>

#include <iterator>
#include <type_traits>

namespace tbx {

template<typename Iter_t, size_t N>
class ring_iterator {
    //! \name STL iterator traits "forwarding"
    //! @{
    protected:
        using traits_type = std::iterator_traits<Iter_t>;

    public:
        using iterator_type     = Iter_t;
        using iterator_category = typename traits_type::iterator_category;
        using value_type        = typename traits_type::value_type;
        using difference_type   = typename traits_type::difference_type;
        using reference         = typename traits_type::reference;
        using pointer           = typename traits_type::pointer;
    //! @}


    //! \name Constructor / Destructor
    //! @{
    public:
        ring_iterator(const Iter_t base =nullptr) noexcept :
            base_(base), iter_(base) { }

        ring_iterator(const Iter_t base, size_t elem) noexcept :
            base_(base), iter_(base + elem) { }

        ring_iterator(const ring_iterator& it) noexcept :
            base_(it.base_), iter_(it.iter_) { }

        ring_iterator& operator= (const ring_iterator& it) noexcept {
            base_ = it.base_;
            iter_ = it.iter_;
            return *this;
        }
    //! @}

    //! \name Forward iterator requirements
    //! @{
    public:
        reference operator*() const noexcept {
            return *iter_;
        }
        pointer operator->() const noexcept {
            return iter_;
        }
        ring_iterator& operator++() noexcept {
            if (static_cast<size_t>(++iter_ - base_) >= N)
                iter_ = base_;
            return *this;
        }
        ring_iterator operator++(int) noexcept {
            ring_iterator it = *this;
            if (static_cast<size_t>(++iter_ - base_) >= N)
                iter_ = base_;
            return it;
        }
    //! @}

    //! \name Bidirectional iterator requirements
    //! @{
    public:
        ring_iterator& operator--() noexcept {
            if (--iter_ < base_)
                iter_ = base_ + N -1;
            return *this;
        }
        ring_iterator operator--(int) noexcept {
            ring_iterator it = *this;
            if (--iter_ < base_)
                iter_ = base_ + N -1;
            return it;
        }
    //! @}

    //! \name Random access iterator requirements
    //! @{
        reference operator[](difference_type n) const noexcept {
            difference_type k = iter_ - base_;          // ptrdiff from base_
            return (static_cast<size_t>(k + n) < N) ?
                base_[k + n] :      // on range
                base_[k + n - N];   // out of range, loop
        }
        ring_iterator& operator+=(difference_type n) noexcept {
            difference_type k = iter_ - base_;          // ptrdiff from base_
            iter_ += (static_cast<size_t>(k + n) < N) ?
                n :                 // on range
                n - N;              // out of range, loop
            return *this;
        }
        ring_iterator operator+(difference_type n) const noexcept {
            difference_type k = iter_ - base_;          // ptrdiff from base_
            return (static_cast<size_t>(k + n) < N) ?
                ring_iterator(base_, k + n) :           // on range
                ring_iterator(base_, k + n - N);        // out of range, loop
        }
        ring_iterator& operator-=(difference_type n) noexcept {
            difference_type k = iter_ - base_;          // ptrdiff from base_
            iter_ -= ((k - n) < 0)?
                n - N:                                  // out of range, loop
                n;                                      // on range
            return *this;
        }
        ring_iterator operator-(difference_type n) const noexcept {
            difference_type k = iter_ - base_;          // ptrdiff from base_
            return ((k - n) < 0) ?
                ring_iterator(base_, k - n + N) :       // out of range, loop
                ring_iterator(base_, k - n);            // on range
        }
    //! @}

    //! \name Data members and access
    //! @{
        const Iter_t& base() const noexcept {
            return base_;
        }
        const Iter_t& iter() const noexcept {
            return iter_;
        }
        size_t size() noexcept {
            return N;
        }

    protected:
        Iter_t base_;
        Iter_t iter_;
    //! @}
};

// Forward iterator requirements
template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator==(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() == rhs.iter();
}

template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator!=(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() != rhs.iter();
}

// Random access iterator requirements
template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator<(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() < rhs.iter();
}

template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator<=(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() <= rhs.iter();
}

template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator>(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() > rhs.iter();
}

template<typename Iter_L, typename Iter_R, size_t N>
inline bool operator>=(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept {
    return lhs.iter() >= rhs.iter();
}

template<typename Iter_L, typename Iter_R, size_t N>
inline auto operator-(const ring_iterator<Iter_L, N>& lhs, const ring_iterator<Iter_R, N>& rhs)
noexcept
-> decltype(lhs.iter() - rhs.iter()) {
    auto diff = lhs.iter() - rhs.iter();
    return diff < 0 ?
            diff + N :  // loop
            diff;       // no loop
}

template<typename Iter, size_t N>
inline ring_iterator<Iter, N> operator+(std::ptrdiff_t lhs, const ring_iterator<Iter, N>& rhs)
noexcept {
    ring_iterator<Iter, N> it(rhs.iter());
    return it += lhs;
}


} //namespace tbx;

#endif /* TBX_CORE_RING_ITERATOR_H_ */