bitwise_iterable_conversion.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of module \alib_enums of the \aliblong.
 *
 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_ALIB_ENUMS_BW_IT_CONVERSION
#define HPP_ALIB_ENUMS_BW_IT_CONVERSION 1
 
#if !defined(HPP_ALIB) && !defined(ALIB_DOX)
#   include "alib/alib.hpp"
#endif
 
ALIB_ASSERT_MODULE(ENUMS)
 
#if !defined (HPP_ALIB_ENUMS_ITERABLE)
#   include "alib/enums/iterable.hpp"
#endif
 
#if !defined(HPP_ALIB_LANG_BITS)
#   include "alib/lang/bits.hpp"
#endif
 
#if defined(ALIB_DOX)
namespace alib::enums::bitwise {
#else
namespace alib {
#endif
 
#if defined(ALIB_DOX)
/**
 * Returns the bitwise enumeration element of \p TEnum from a given sequential enumeration.
 *
 * Selected by the compiler only if \alib{enums;T_EnumIsBitwise} is specialized for
 * template enum type \p{TEnum} to inherit \c std::true_type.
 *
 * \see The reverse function #ToSequentialEnumeration.
 *
 * @tparam TEnum An enumeration type which is defined to be "bitwise".
 * @param number A sequentially enumerated number, for which the corresponding bitwise
 *               enumeration element is requested.
 *               \ref alib_enums_arithmetic_bitwise "bitwise enumeration".
 * @return Returns <c>1 << number</c>.
 */
template<typename TEnum>
constexpr inline
TEnum ToBitwiseEnumeration(typename std::underlying_type<TEnum>::type number );
 
#else
 
template<typename TEnum>
constexpr
ATMP_T_IF(TEnum, alib::enums::T_EnumIsBitwise<TEnum>::value)
ToBitwiseEnumeration(typename std::underlying_type<TEnum>::type number )
{
    #if !defined (HPP_ALIB_ENUMS_ITERABLE)
        ALIB_ASSERT_ERROR( number >= 0
                           && (   !enums::T_EnumIsIterable<TEnum>::value
                                || enums::T_EnumIsIterable<TEnum>::End  > TEnum( 1 << number ) ),
                                "ENUMS",  "Number out of bounds."                                      )
    #endif
    return TEnum( 1 << number );
}
#endif
 
#if defined(ALIB_DOX)
 
/**
 * Returns the sequentially enumerated number derived from the given bitwise enumeration
 * value.
 * In other words, the positon of the most significant bit set in the underlying integral of the
 * given enum \p element is returned.<br>
 * In debug-compilations an \alib assertion is raised in case that the given value is not a
 * single enum element but a combination of bits.
 *
 * Selected by the compiler only if \alib{enums;T_EnumIsBitwise} is specialized for
 * template enum type \p{TEnum} to inherit \c std::true_type.
 *
 * \see The reverse function #ToBitwiseEnumeration.
 * @tparam TEnum  A bitwise defined enumeration type. Deduced by the compiler.
 * @param element An enumeration value.
 * @return The sequential number of an element of an enum type which is defined bitwise.
 */
template<typename TEnum>
static constexpr inline
typename std::underlying_type<TEnum>::type
ToSequentialEnumeration( TEnum element );
#else
template<typename TEnum>
constexpr
ATMP_T_IF(typename std::underlying_type<TEnum>::type, alib::enums::T_EnumIsBitwise<TEnum>::value)
ToSequentialEnumeration( TEnum element )
{
    ALIB_ASSERT_ERROR(               UnderlyingIntegral(element)  != 0, "ENUMS",
                       "No bits set in given enum value"  )
    ALIB_ASSERT_ERROR( lang::BitCount(UnderlyingIntegral(element)) == 1, "ENUMS",
                       "Multiple bits given with enum value"  )
    return static_cast<typename std::underlying_type<TEnum>::type>(
           lang::MSB( UnderlyingIntegral(element) ) - 1    );
}
#endif
 
 
} // namespace [alib]  (doxygen [alib::enums::bitwise])
 
#endif // HPP_ALIB_ENUMS_BW_IT_CONVERSION