iterable.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the module \alib_enumops of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace enumops{
 
//##################################################################################################
// struct IterableTraits
//##################################################################################################
 
 
//==================================================================================================
/// A simple type trait that - if specialized - enables standard and range-based C++ iteration of the
/// elements of an enumeration.
/// Specializations have to declare <c>constexpr</c> fields #Begin and #End, as documented with this
/// type.
///
/// \note
///    The unspecialized version of this struct is empty.
///
/// If specialized, the following entities become available:
/// - \alib{enumops::iterable;operator+}
/// - \alib{enumops::iterable;operator-}
/// - struct \alib{enumops;EnumIterator}
///
/// \attention
///   Likewise with the operators introduced with other type traits of this module,
///   this documentation "fakes" the operators into namespace
///   <c>alib::enumops::iterable</c>, while in fact they are defined in the global
///   namespace!<br>
///   See \ref alib_enums_arithmetic_standard "corresponding note" in the Programmer's Manual
///   for details.
///
/// <b>Restrictions</b><br>
/// For technical reasons, this concept is not applicable to enum types that are defined as
/// \c private or \c protected inner types of structs or classes.
///
/// \see
///   - Macros \ref ALIB_ENUMS_MAKE_ITERABLE and \ref ALIB_ENUMS_MAKE_ITERABLE_BEGIN_END, which
///     specialize this type trait for a given enumeration type.
///   - Type \alib{enumops;EnumIterator} used to perform iterations.
///   - For details and a source code sample see chapter \ref alib_enums_iter "3. Enum Iteration"
///     of the Programmer's Manual of the module \alib_enumops.
///
/// @tparam TEnum      The enum type to enable iteration for.
//==================================================================================================
template<typename TEnum>
requires std::is_enum_v<TEnum>
struct IterableTraits  : std::false_type
{
    #if DOXYGEN
        /// Specializations have to implement this static method to return the first enum element
        /// of the iteration.
        ///
        /// @return The first enumeration element.
        static constexpr   TEnum    Begin;
    #endif
 
    #if DOXYGEN
        /// Specializations have to implement this static method to return the element value after
        /// the last enum element of the iteration.
        ///
        /// @return The element after the last enumeration element.
        static constexpr   TEnum    End;
    #endif
};
 
ALIB_WARNINGS_IGNORE_DOCS
 
/// A concept to identify "iterable enum types".
/// These are types for which a specialization of type trait \alib{enumops;IterableTraits}
/// is defined.
/// @tparam TEnum   The type to be tested.
template <typename TEnum>
concept IsIterable =  std::same_as< const TEnum, decltype(IterableTraits<TEnum>::Begin) >;
 
ALIB_WARNINGS_RESTORE
 
}} // namespace [alib::enumops::]
 
//##################################################################################################
// Operators for iterable enums
//##################################################################################################
 
// For documentation, all operators and enum-related template functions are faked into namespace
// alib::enumops.
#if DOXYGEN
namespace alib {  namespace enumops{
/// Operators available to elements of enumerations if \alib{enumops;IterableTraits} is
/// specialized.
///
/// \note
///   This namespace exits only in the documentation to collect the operators.
///   When parsed by a C++ compiler, <b>the operators reside in the global namespace</b>.
namespace iterable {
#endif
 
/// Add operator usable with scoped enum types and integral values.
///
/// Selected by the compiler only if \alib{enumops;IterableTraits} is specialized for
/// enum type \p{TEnum}.
///
/// @tparam TEnum      Enumeration type.
/// @tparam TRhs       The type of the summand.
/// @param  element    First operand of \p{TEnum} type.
/// @param  summand    The summand.
/// @return The <em>"summand-th"</em> enum element after \p{element} .
ALIB_EXPORT
template<typename TEnum, typename TRhs= int>
requires (  alib::enumops::IsIterable<TEnum>  &&  std::integral<TRhs> )
constexpr TEnum operator+  (TEnum element, TRhs summand)                                  noexcept {
    return TEnum(   alib::UnderlyingIntegral(element)
                  + static_cast<typename std::underlying_type<TEnum>::type>(summand) );
}
 
/// Subtract operator usable with scoped enum types and integral values.
///
/// Selected by the compiler only if \alib{enumops;IterableTraits} is specialized for
/// enum type \p{TEnum}.
///
/// @tparam TEnum      Enumeration type.
/// @tparam TRhs       The type of the subtrahend.
/// @param  element    First operand of \p{TEnum} type.
/// @param  subtrahend The subtrahend.
/// @return The <em>"subtrahend-th"</em> enum element before \p{element} .
ALIB_EXPORT
template<typename TEnum, typename TRhs= int>
requires (  alib::enumops::IsIterable<TEnum>  &&  std::integral<TRhs> )
constexpr TEnum operator-  (TEnum                                      element,
                            typename std::underlying_type<TEnum>::type subtrahend)        noexcept {
    return TEnum(   alib::UnderlyingIntegral(element)
                  - static_cast<typename std::underlying_type<TEnum>::type>(subtrahend) );
}
 
 
// Faking all operators and enum-related template functions to namespace alib::enumops
#if DOXYGEN
}
#else
ALIB_EXPORT namespace alib {  namespace enumops {
#endif
 
//##################################################################################################
// EnumIterator
//##################################################################################################
/// Implements a \c std::iterator_traits class for scoped and non-scoped enum types.
/// The documentation is found with the type trait \alib{enumops;IterableTraits}, which needs
/// to be specialized for template type \p{TEnum}.
/// For other types, this class is not constructible.
/// @tparam TEnum  The enum type to iterate over.
template<typename TEnum>
requires alib::enumops::IsIterable<TEnum>
struct EnumIterator
{
    /// Default constructor.
    EnumIterator()                                                                         =default;
 
    /// Implementation of \c std::iterator_traits for enum type \p{TEnum}. This class exposes
    /// #ConstIterator which uses <c>const TEnum*</c> and <c>const TEnum&</c> as
    /// pointer and reference types.
    ///
    /// As the name of the class indicates, this iterator satisfies the C++ standard library concept
    /// \https{RandomAccessIterator,en.cppreference.com/w/cpp/concept/RandomAccessIterator}.
    template<typename TPointer, typename TReference>
    class TRandomAccessIterator
    {
        using iterator_category = std::random_access_iterator_tag;  ///< Implementation of <c>std::iterator_traits</c>.
        using value_type        = TEnum                          ;  ///< Implementation of <c>std::iterator_traits</c>.
        using difference_type   = std::ptrdiff_t                 ;  ///< Implementation of <c>std::iterator_traits</c>.
        using pointer           = TPointer                       ;  ///< Implementation of <c>std::iterator_traits</c>.
        using reference         = TReference                     ;  ///< Implementation of <c>std::iterator_traits</c>.
 
      protected:
        /// The actual enum element.
        TEnum p;
 
            /// The underlying integer type.
            using TIntegral= typename std::underlying_type<TEnum>::type;
 
      public:
        /// Constructor.
        /// @param pp Our initial value
        constexpr
        explicit TRandomAccessIterator( TEnum pp = TEnum(0) ) : p(pp)                             {}
 
      //############################ To satisfy concept of  InputIterator ##########################
 
        /// Prefix increment operator.
        /// @return A reference to ourselves.
        TRandomAccessIterator& operator++() {
            if constexpr( !IsBitwise<TEnum> )
                p= p + 1;
            else
                p= TEnum( UnderlyingIntegral( p ) << 1 );
 
            return *this;
        }
 
        /// Postfix increment operator.
        /// @return A reference to ourselves.
        TRandomAccessIterator operator++(typename std::underlying_type<TEnum>::type) {
            if constexpr( !IsBitwise<TEnum> )
                return TRandomAccessIterator(p= p + 1);
            else
                return TRandomAccessIterator(p= TEnum( UnderlyingIntegral( p ) << 1) );
        }
 
        /// Comparison operator.
        /// @param other  The iterator to compare ourselves to.
        /// @return \c true if this and given iterator are equal, \c false otherwise.
        constexpr
        bool operator==(TRandomAccessIterator other)                  const { return p == other.p; }
 
        /// Comparison operator.
        /// @param other  The iterator to compare ourselves to.
        /// @return \c true if this and given iterator are not equal, \c false otherwise.
        constexpr
        bool operator!=(TRandomAccessIterator other)             const { return !(*this == other); }
 
        /// Retrieves the enum element that this iterator references.
        /// @return The enum element.
        constexpr
        TEnum  operator*()                                                       const { return p; }
 
 
      //######################## To satisfy concept of  BidirectionalIterator ######################
 
        /// Prefix decrement operator.
        /// @return A reference to ourselves.
        TRandomAccessIterator& operator--() {
            if constexpr( !IsBitwise<TEnum> )
                p= p + 1;
            else
                p= TEnum(  );
            return *this;
        }
 
 
        /// Postfix decrement operator.
        /// @return An iterator that with the old value.
        TRandomAccessIterator operator--(typename std::underlying_type<TEnum>::type) {
            if constexpr( !IsBitwise<TEnum> )
                return TRandomAccessIterator(p= p - 1);
            else
                return TRandomAccessIterator(p= TEnum( UnderlyingIntegral( p ) >> 1) );
        }
 
 
      //######################## To satisfy concept of  RandomAccessIterator #######################
 
        /// Addition assignment.
        /// @param n The value to subtract.
        /// @return A reference to ourselves.
        TRandomAccessIterator& operator+=(TIntegral n) {
            if constexpr( !IsBitwise<TEnum> )
                p= p + n;
            else
                p= TEnum( UnderlyingIntegral( p ) << n );
            return *this;
        }
 
        /// Subtraction assignment.
        /// @param n The value to subtract.
        /// @return A reference to ourselves.
        TRandomAccessIterator& operator-=(TIntegral n) {
            if constexpr( !IsBitwise<TEnum> )
                p= p - n;
            else
                p= TEnum( UnderlyingIntegral( p ) >> n );
        }
 
        /// Addition.
        /// @param n The value to subtract.
        /// @return A reference to the new iterator.
        TRandomAccessIterator operator+(TIntegral n)                                         const {
            if constexpr( !IsBitwise<TEnum> )
                return TRandomAccessIterator( p + n );
            else
                return TRandomAccessIterator( TEnum( UnderlyingIntegral( p ) << n ) );
        }
 
        /// Subtraction.
        /// @param n The value to subtract.
        /// @return A reference to the new iterator.
        TRandomAccessIterator operator-(TIntegral n)                                         const {
            if constexpr( !IsBitwise<TEnum> )
                return TRandomAccessIterator( p - n );
            else
                return TRandomAccessIterator( TEnum( UnderlyingIntegral( p ) >> n ) );
        }
 
        /// Difference (distance) from this iterator to the given one.
        /// @param other  The iterator to subtract
        /// @return The iterator to subtract.
        std::ptrdiff_t operator-(TRandomAccessIterator other)                                const {
            if constexpr( !IsBitwise<TEnum> )
                return static_cast<std::ptrdiff_t>(UnderlyingIntegral(p) - UnderlyingIntegral(other.p));
            else
                 return   static_cast<std::ptrdiff_t>(lang::MSB(UnderlyingIntegral( p )       ))
                        - static_cast<std::ptrdiff_t>(lang::MSB(UnderlyingIntegral( other.p ) ));
        }
 
        /// Subscript operator.
        /// @param n  The iterator to subtract
        /// @return <c>*( (*this) + n )</c>.
        TEnum operator[]( std::ptrdiff_t n )                                                 const {
            if constexpr( !IsBitwise<TEnum> )
                return ( p + static_cast<TIntegral>( n ) );
            else
                return TEnum( UnderlyingIntegral( p ) << n );
        }
 
        //#### Comparison operators (also needed to satisfy concept of RandomAccessIterator) ###
 
        /// Compares this iterator with the given one.
        /// @param other  The iterator to compare
        /// @return \c true if this iterator is \e smaller than \p{other},
        ///         \c false otherwise.
        bool operator<(TRandomAccessIterator other)                    const { return p < other.p; }
 
        /// Compares this iterator with the given one.
        /// @param other  The iterator to compare
        /// @return \c true if this iterator is \e smaller than or equal to \p{other},
        ///         \c false otherwise.
        bool operator<=(TRandomAccessIterator other)                  const { return p <= other.p; }
 
 
        /// Compares this iterator with the given one.
        /// @param other  The iterator to compare
        /// @return \c true if this iterator is \e greater than \p{other},
        ///         \c false otherwise.
        bool operator>(TRandomAccessIterator other)                    const { return p > other.p; }
 
        /// Compares this iterator with the given one.
        /// @param other  The iterator to compare
        /// @return \c true if this iterator is \e greater than or equal to \p{other},
        ///         \c false otherwise.
        bool operator>=(TRandomAccessIterator other)                  const { return p >= other.p; }
    };
 
/// The constant iterator exposed by this class. A Mutable version is not available.
using ConstIterator= TRandomAccessIterator<const TEnum*, const TEnum&>;
 
 
    /// Returns an iterator referring to the start of enumeration \p{TEnum}.
    /// @return The start of the enumeration.
    ConstIterator begin()                                                                    const {
        return ConstIterator(   IsBitwise<TEnum>
                             && UnderlyingIntegral( IterableTraits<TEnum>::Begin ) == 0
                                ? TEnum(1)
                                : IterableTraits<TEnum>::Begin );
    }
 
    /// Returns an iterator referring the first illegal value of enumeration \p{TEnum}.
    /// @return The end of the enumeration.
    ConstIterator end()                                                                        const
    { return ConstIterator( TEnum(0) + UnderlyingIntegral( IterableTraits<TEnum>::End ) ); }
};  // struct EnumIterator
 
 
 
 
} // namespace alib[::enumops::]
 
/// Type alias in namespace \b alib.
template<typename TEnum>
requires enumops::IsIterable<TEnum>
using  EnumIterator=     enumops::EnumIterator<TEnum>;
 
} // namespace [alib]