bits.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_lang of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {
#include "ALib.Lang.CIFunctions.H"
 
/// This namespace holds types and functions of the module \alib_lang, which are very close to
/// the C++ language itself.
/// The entities found here are always included in any \alibbuild and are accessed by
/// including the header #"F;ALib.Lang.H".
///
/// # Reference Documentation #
namespace lang {
/// The C++ language defines the right-hand-side argument of bit shift operations to be of
/// type <c>int</c>. To increase code readability we define this type explicitly.
using   ShiftOpRHS = int;
 
 
/// Like C++ keyword <c>sizeof</c> but returns the number of bits of the type of the given value.
/// The return type is <c>int</c> instead of <c>size_t</c>, which satisfies \alib code conventions.
///
/// \note To improve code readability, namely to a) indicate that this is an inlined, constant
///       expression and b) to indicate that this is just using keyword <c>sizeof</c>,
///       as an exception from the rules, this function is spelled in lower case.
///
/// \see Macro #"bitsof;bitsof(type)", which works directly on the type.
///
/// @param  val  The (sample) value to deduce the type from. Otherwise ignored.
/// @tparam T    The type to receive the size in bits from.
/// @return The size of \p{TIntegral} in bits.
template<typename T> inline constexpr int bitsofval(const T& val)
{ (void) val; return sizeof(T) * 8; }
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
/// Inline namespace function that returns a mask with bits set to \c 1 up to the given
/// binary digit, and bits above to \c 0.
/// If the parameter \p{TWidth} is greater or equal to the width of the given \p{TIntegral} type, then
/// all bits are set in the returned value.
///
/// \see While this is the fully templated version, with
///      #"LowerMask(ShiftOpRHS);LowerMask<TIntegral>(ShiftOpRHS)", a run-time version is given.
///
/// @tparam TWidth    The number of lower bits to set to \c 1.
/// @tparam TIntegral The integral type to operate on.
/// @return The requested mask.
template<ShiftOpRHS TWidth, typename TIntegral>
constexpr TIntegral LowerMask();
#else
template<ShiftOpRHS TWidth, typename TIntegral>
requires ( std::is_integral<TIntegral>::value  &&  TWidth < bitsof(TIntegral) )
constexpr TIntegral LowerMask() {
    ALIB_ALLOW_INTEGRAL_CONSTANT_OVERFLOW
    using TUnsigned= typename std::make_unsigned<TIntegral>::type;
    return TIntegral(~(TUnsigned(~TUnsigned(0)) << TWidth) );
    ALIB_POP_ALLOWANCE
}
 
template<ShiftOpRHS TWidth, typename TIntegral>
requires ( std::is_integral<TIntegral>::value  &&  TWidth >= bitsof(TIntegral) )
constexpr TIntegral LowerMask()                                 { return TIntegral(~TIntegral(0)); }
 
#endif
 
/// Inline namespace function that returns a mask with bits set to \c 1 up to the given
/// binary digit, and bits above to \c 0.
/// Parameter \p{width} <b>must not be greater or equal</b> to the width of the given
/// \p{TIntegral} type.
/// In debug-compilations, an #"alib_mod_assert;error is raised" in that case.
///
/// \see A fully templated version usable when the number of bits are known at compile time,
///      is given with #".LowerMask()".
///
/// @tparam TIntegral The integral type to operate on.
/// @param  width     The number of lower bits to set in the mask returned.
/// @return The requested mask.
template<typename TIntegral>
requires  std::integral<TIntegral>
constexpr TIntegral LowerMask( ShiftOpRHS width ) {
    ALIB_ASSERT_ERROR( width < bitsof(TIntegral), "LANG",
          "Requested mask width wider than integral: {} >= {}", width, bitsof(TIntegral) )
    using TUnsigned= typename std::make_unsigned<TIntegral>::type;
    return TIntegral(~(TUnsigned(~TUnsigned(0))  << width  ));
}
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
/// Inline namespace function that returns a mask with bits set to \c 0 up to the given
/// binary digit, and bits above to \c 1.
/// If the parameter \p{TWidth} is greater or equal to the width of the given \p{TIntegral} type, then
/// all bits are set in the returned value.
///
/// \see While this is the fully templated version, with
///      #"UpperMask(ShiftOpRHS);UpperMask<TIntegral>(ShiftOpRHS)", a run-time version is given.
///
/// @tparam TWidth    The number of lower bits to clear to \c 1.
/// @tparam TIntegral The integral type to operate on.
/// @return The requested mask.
template<ShiftOpRHS TWidth, typename TIntegral>
requires ( std::is_integral<TIntegral>::value  && TWidth < bitsof(TIntegral) )
constexpr TIntegral UpperMask();
#else
template<ShiftOpRHS TWidth, typename TIntegral>
requires ( std::is_integral<TIntegral>::value  && TWidth < bitsof(TIntegral) )
constexpr TIntegral UpperMask()
{
    using TUnsigned= typename std::make_unsigned<TIntegral>::type;
    return TIntegral((TUnsigned(~TUnsigned(0)) << TWidth));
}
 
template<ShiftOpRHS TWidth, typename TIntegral>
requires ( std::is_integral<TIntegral>::value  && TWidth >= bitsof(TIntegral) )
constexpr TIntegral UpperMask()                                             { return TIntegral(0); }
#endif
 
/// Inline namespace function that returns a mask with bits set to \c 0 up to the given
/// binary digit, and bits above to \c 1.
/// Parameter \p{width} <b>must not be greater or equal</b> to the width of the given
/// \p{TIntegral} type.
/// In debug compilations, an #"alib_mod_assert;error is raised" in that case.
///
/// \see A fully templated version usable when the number of bits are known at compile time,
///      is given with #".UpperMask()"
///
/// @tparam TIntegral The integral type to operate on.
/// @param  width     The number of lower bits to clear in the mask returned.
/// @return The requested mask.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr TIntegral UpperMask( ShiftOpRHS width ) {
    ALIB_ASSERT_ERROR( width < bitsof(TIntegral), "LANG",
          "Requested mask width wider than integral: {} >= {}", width, bitsof(TIntegral) )
    using TUnsigned= typename std::make_unsigned<TIntegral>::type;
    return TIntegral( (TUnsigned(~TUnsigned(0))  << width)  );
}
 
/// Inline namespace function that keeps the given number of lower bits and masks the higher ones
/// out of the given integral value.
/// If given \p{TWidth} is greater or equal to the width of the given \p{TIntegral} type, then
/// all bits are returned.
///
/// \see While this is the fully templated version and hence explicitly \c constexpr for the
///      reader of a code, with
///      #"LowerBits(ShiftOpRHS, TIntegral);LowerBits<TIntegral>(ShiftOpRHS, TIntegral)",
///      a version is given.
///
/// @param  value     The value to mask.
/// @tparam TWidth    The number of lower bits to keep.
/// @tparam TIntegral The integral type to operate on (deduced by the compiler).
/// @return The given value with the upper remaining bits cleared.
template<ShiftOpRHS TWidth, typename TIntegral>
requires std::integral<TIntegral>
constexpr TIntegral LowerBits( TIntegral value ) {
    if constexpr ( TWidth >= bitsof(TIntegral) )
        return value;
    return value & LowerMask<TWidth,TIntegral>( );
}
 
/// Inline namespace function that keeps the given number of lower bits and masks the higher ones
/// out of the given integral value.
/// Parameter \p{width} <b>must not be greater or equal</b> to the width of the given
/// \p{TIntegral} type. In debug compilations, an #"alib_mod_assert;error is raised".
///
/// \see A fully templated version, usable when the number of bits is known at compile time,
///      is given with #"LowerBits(TIntegral)".
///
/// @param  width     The number of lower bits to keep.
/// @param  value     The value to mask.
/// @tparam TIntegral The integral type to operate on (deduced by the compiler).
/// @return The given value with the upper remaining bits cleared.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr TIntegral LowerBits( ShiftOpRHS width, TIntegral value )
{ return value & LowerMask<TIntegral>( width ); }
 
/// Returns logarithm base 2 for the size in bits of the template given integral type.<p>
/// Precisely, this function returns:
/// - 3 for 8-bit types,
/// - 4 for 16-bit types,
/// - 5 for 32-bit types,
/// - 6 for 64-bit types, and
/// - 7 for 128-bit types.
/// @tparam TIntegral The integral type to count bits in.
/// @return The number of bits needed to count the bits of type \p{TIntegral}.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int
Log2OfSize() {
    static_assert(bitsof(TIntegral) <= 128, "Integrals larger than 128 are not supported.");
    if constexpr (bitsof(TIntegral) == 32) return 5;
    if constexpr (bitsof(TIntegral) == 64) return 7;
    if constexpr (bitsof(TIntegral) ==  8) return 3;
    if constexpr (bitsof(TIntegral) == 16) return 4;
    return 8;
}
 
/// Returns the number of bits set in an integral value.
/// Internally, this method uses C++20 library function <c>std::popcount</c>.
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test.
/// @return The number of bits set in a value.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int BitCount( TIntegral value )
{ return std::popcount( static_cast<typename std::make_unsigned<TIntegral>::type>( value ) ); }
 
/// Returns the number of the leading 0-bits in an integral type.
/// Internally, this method uses C++20 library function <c>std::countl_zero</c>.
///
/// \attention
///   This function must not be called with a \p{value} of <c>0</c>!
///   In debug-compilations, this method #"alib_mod_assert;raises an ALib error" in this case,
///   while in release-compilations, the result is <em>'undefined'</em>.
///   With function #"MSB0", an alternative is given which returns \c 0 if the input is \c 0.
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. Must not be \c 0.
/// @return The highest bit set in \p{value}.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int CLZ( TIntegral value ) {
    #if ALIB_DEBUG && !ALIB_DEBUG_ASSERTION_PRINTABLES
      ALIB_ASSERT_ERROR( value != 0, "LANG",
                "Illegal value 0 passed to MSB(). Use MSB0() if 0 values need to be handled." )
    #endif
    return std::countl_zero( static_cast<typename std::make_unsigned<TIntegral>::type>( value ) );
}
 
 
/// Variant of #"CLZ" which tests the given parameter \p{value} on \c 0 and returns
/// <c>sizeof(TIntegral) * 8</c> in this case.
/// Otherwise, returns the result of #"CLZ".
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. May be \c 0, which results to the number of bits in
///                   \p{TIntegral}.
/// @return The number of leading zero-bits in \p{value}.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int CLZ0( TIntegral value) {
    if( value == 0 )
        return bitsof(TIntegral);
    return CLZ(value);
}
 
/// Returns the number of the trailing 0-bits in an integral type.
/// Internally, this method uses C++20 library function <c>std::countr_zero</c>.
///
/// \attention
///   This function must not be called with a \p{value} of <c>0</c>!
///   In debug-compilations, this method #"alib_mod_assert;raises an ALib error" in this case,
///   while in release-compilations, the result is <em>'undefined'</em>.
///   With function #"CTZ0", an alternative is given which returns \c 0 if the input is \c 0.
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. Must not be \c 0.
/// @return The lowest bit set in \p{value}.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int CTZ( TIntegral value ) {
    ALIB_ASSERT_ERROR( value != 0, "LANG",
              "Illegal value 0 passed to MSB(). Use MSB0() if 0 values need to be handled." )
    return std::countr_zero( static_cast<typename std::make_unsigned<TIntegral>::type>( value ) );
}
 
/// Variant of #"CTZ" which tests given parameter \p{value} on \c 0 and returns
/// <c>sizeof(TIntegral) * 8</c> in this case.
/// Otherwise, returns the result of #"CLZ".
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. May be \c 0, which results to the number of bits in
///                   \p{TIntegral}.
/// @return The number of trailing zero-bits in \p{value}. In case the given value is \c 0,
///         <c>sizeof(Tintegral) * 8</c> is returned.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int CTZ0( TIntegral value ) {
    if( value == 0 )
        return bitsof(TIntegral);
    return CTZ(value);
}
 
/// Returns the number of the most significant bit in an integral type.
/// Internally, this method uses #"CLZ" and returns
///
///      int(sizeof(TIntegral)) * 8 - CLZ(value)
///
/// \attention
///   This function must not be called with a \p{value} of <c>0</c>!
///   In debug-compilations, this method #"alib_mod_assert;raises an ALib error" in this case,
///   while in release-compilations, the result is <em>'undefined'</em>.
///   With function #"MSB0", an alternative is given which returns \c 0 if the input is \c 0.
///
/// \note A corresponding function "LSB", to receive the least significant bit is not given.
///       Instead, use <c>CTZ() + 1</c>.
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. Must not be \c 0.
/// @return The highest bit set in \p{value}. The numbering starts with \c 1 and ends with
///         <c>sizeof(Tintegral) * 8</c>.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int MSB( TIntegral value) {
    #if ALIB_DEBUG && !ALIB_DEBUG_ASSERTION_PRINTABLES
      ALIB_ASSERT_ERROR( value != 0, "LANG",
               "Illegal value 0 passed to MSB(). Use MSB0() if 0 values need to be handled." )
    #endif
    return  bitsof(TIntegral) - CLZ(value);
}
 
/// Variant of #"MSB" which tests given parameter \p{value} on \c 0 and returns \c 0 in this
/// case. Otherwise, returns the result of #"MSB".
///
/// @tparam TIntegral The integral type to operate on.
/// @param  value     The value to test. May be \c 0, which results to \c 0.
/// @return The highest bit set in \p{value}. The numbering starts with \c 1 and ends with
///         <c>sizeof(Tintegral)* 8</c>. If \p{value} is \c 0, hence no bit is set,
///         \c 0 is returned.
template<typename TIntegral>
requires std::integral<TIntegral>
constexpr int MSB0( TIntegral value) {
    if( value == 0 )
        return 0;
    return MSB(value);
}
#include "ALib.Lang.CIMethods.H"
}} // namespace [alib::lang]