bit_operations.h

Go to the documentation of this file.

 
 
#pragma once
 
#include "mjolnir/core/fundamental_types.h"
 
#include <concepts>
#include <limits>
 
 
namespace mjolnir
{
 
 
template <typename T_Type>
inline constexpr UST num_bits = sizeof(T_Type) * CHAR_BIT;
 
 
template <std::unsigned_integral T_Type, UST... t_bit_values>
[[nodiscard]] consteval auto bit_construct([[maybe_unused]] bool left_is_low = false) noexcept -> T_Type;
 
 
template <UST t_num_int_bits, std::unsigned_integral T_Type, UST... t_integers>
[[nodiscard]] consteval auto bit_construct_from_ints(bool left_is_low = false) noexcept -> T_Type;
 
 
template <std::unsigned_integral T_Type, UST t_num_bits>
[[nodiscard]] constexpr auto bit_construct_set_first_n_bits() noexcept -> T_Type;
 
 
template <std::unsigned_integral T_Type>
constexpr void clear_bit(T_Type& integer, UST index) noexcept;
 
 
template <UST t_num_bits, std::unsigned_integral T_Type>
constexpr void clear_bits(T_Type& integer, UST index) noexcept;
 
 
template <UST                    t_index,
          I32                    t_shift      = 0,
          std::unsigned_integral T_Type       = UST,
          std::unsigned_integral T_ReturnType = T_Type>
[[nodiscard]] constexpr auto get_bit(T_Type integer) noexcept -> T_ReturnType;
 
 
template <std::unsigned_integral T_Type = UST, std::unsigned_integral T_ReturnType = T_Type>
[[nodiscard]] constexpr auto get_bit(T_Type integer, UST index, I32 shift = 0) noexcept -> T_ReturnType;
 
 
template <UST                    t_index,
          bool                   t_shift_right = true,
          std::unsigned_integral T_Type        = UST,
          std::unsigned_integral T_ReturnType  = T_Type>
[[nodiscard]] constexpr auto get_bit_shift_max(T_Type integer) noexcept -> T_ReturnType;
 
 
template <bool t_shift_right = true, std::unsigned_integral T_Type = UST, std::unsigned_integral T_ReturnType = T_Type>
[[nodiscard]] constexpr auto get_bit_shift_max(T_Type integer, UST index) noexcept -> T_ReturnType;
 
 
template <UST                    t_index,
          UST                    t_num_bits,
          I32                    t_shift      = 0,
          std::unsigned_integral T_Type       = UST,
          std::unsigned_integral T_ReturnType = T_Type>
[[nodiscard]] constexpr auto get_bits(T_Type integer) noexcept -> T_ReturnType;
 
 
template <UST t_num_bits, std::unsigned_integral T_Type = UST, std::unsigned_integral T_ReturnType = T_Type>
[[nodiscard]] constexpr auto get_bits(T_Type integer, UST index, I32 shift = 0) noexcept -> T_ReturnType;
 
 
template <UST                    t_index,
          UST                    t_num_bits,
          bool                   t_shift_right = true,
          std::unsigned_integral T_Type        = UST,
          std::unsigned_integral T_ReturnType  = T_Type>
[[nodiscard]] constexpr auto get_bits_shift_max(T_Type integer) noexcept -> T_ReturnType;
 
 
template <UST                    t_num_bits,
          bool                   t_shift_right = true,
          std::unsigned_integral T_Type        = UST,
          std::unsigned_integral T_ReturnType  = T_Type>
[[nodiscard]] constexpr auto get_bits_shift_max(T_Type integer, UST index) noexcept -> T_ReturnType;
 
template <typename T_Type>
[[nodiscard]] constexpr auto is_bit_set(T_Type integer, UST index) noexcept -> bool;
 
 
template <std::unsigned_integral T_Type>
constexpr void set_bit(T_Type& integer, UST index) noexcept;
 
 
template <UST t_value, std::unsigned_integral T_Type>
constexpr void set_bit_to(T_Type& integer, UST index) noexcept;
 
 
template <UST t_num_bits, std::unsigned_integral T_Type>
constexpr void set_bits(T_Type& integer, UST index) noexcept;
 
 
template <UST t_num_bits, bool t_clear_bits = true, std::unsigned_integral T_Type>
constexpr void set_bits_with_int(T_Type& integer, UST index, UST value) noexcept;
 
 
} // namespace mjolnir
 
 
// ====================================================================================================================
 
 
#include <initializer_list>
 
#include <algorithm>
#include <cassert>
#include <limits>
 
namespace mjolnir
{
// ---internal definitions --------------------------------------------------------------------------------------------
 
namespace internal
{
template <std::integral T_Type>
[[nodiscard]] constexpr auto abs(T_Type value) noexcept -> T_Type
{
    if constexpr (std::is_unsigned_v<T_Type>)
    {
        return value;
    }
    else
    {
        // source: https://stackoverflow.com/a/9772647/6700329
        // regarding nolint: https://stackoverflow.com/a/58845898/6700329
        int const mask = value >> (sizeof(T_Type) * CHAR_BIT - 1); // NOLINT(hicpp-signed-bitwise)
        return (value + mask) ^ mask;                              // NOLINT(hicpp-signed-bitwise)
    }
}
 
 
} // namespace internal
 
 
// --- public definitions ---------------------------------------------------------------------------------------------
 
 
template <std::unsigned_integral T_Type, UST... t_bit_values>
[[nodiscard]] consteval auto bit_construct([[maybe_unused]] bool left_is_low) noexcept -> T_Type
{
    static_assert(sizeof...(t_bit_values) <= num_bits<T_Type>, "Number of bit values exceeds number of type bits.");
 
    T_Type integer = 0;
    if constexpr (sizeof...(t_bit_values) != 0)
    {
        if (left_is_low)
        {
            UST bit_index = 0;
            (void) std::initializer_list<I32>{(set_bit_to<t_bit_values>(integer, bit_index++), 0)...};
        }
        else
        {
            UST bit_index = sizeof...(t_bit_values) - 1;
            (void) std::initializer_list<I32>{(set_bit_to<t_bit_values>(integer, bit_index--), 0)...};
        }
    }
    return integer; // NOLINT(readability-misleading-indentation) --- clang-tidy bug
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <std::unsigned_integral T_Type, UST t_num_bits>
[[nodiscard]] constexpr auto bit_construct_set_first_n_bits() noexcept -> T_Type
{
    // INFO:
    // The static_cast for the `true` case is actually needed because the `~` operator seems to perform a promotion to
    // `int`. See the following link: https://stackoverflow.com/q/30473958/6700329
    if constexpr (t_num_bits >= num_bits<T_Type>)
        return static_cast<T_Type>(~(T_Type(0)));
    else
        return static_cast<T_Type>(((UST(1)) << t_num_bits) - 1);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_int_bits, std::unsigned_integral T_Type, UST... t_integers>
[[nodiscard]] consteval auto bit_construct_from_ints(bool left_is_low) noexcept -> T_Type
{
    static_assert(sizeof...(t_integers) * t_num_int_bits <= num_bits<T_Type>,
                  "Totoal number of provided bits exceeds number of type bits.");
 
    T_Type integer = 0;
    if (left_is_low)
    {
        UST bit_index = 0;
        (void) std::initializer_list<I32>{(set_bits_with_int<t_num_int_bits, false>(integer, bit_index, t_integers),
                                           bit_index += t_num_int_bits,
                                           0)...};
    }
    else
    {
        UST bit_index = (sizeof...(t_integers) - 1) * t_num_int_bits;
        (void) std::initializer_list<I32>{(set_bits_with_int<t_num_int_bits, false>(integer, bit_index, t_integers),
                                           bit_index -= t_num_int_bits,
                                           0)...};
    }
 
    return integer;
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <std::unsigned_integral T_Type>
constexpr void clear_bit(T_Type& integer, UST index) noexcept
{
    assert(index < num_bits<T_Type> && "Index exceeds number of bits."); // NOLINT
 
    integer &= static_cast<T_Type>(~(UST(1) << index));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_bits, std::unsigned_integral T_Type>
constexpr void clear_bits(T_Type& integer, UST index) noexcept
{
    assert(index + t_num_bits <= num_bits<T_Type>); // NOLINT
 
    constexpr UST bits = bit_construct_set_first_n_bits<UST, t_num_bits>();
    integer &= static_cast<T_Type>(~(bits << index));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_index, I32 t_shift, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bit(T_Type integer) noexcept -> T_ReturnType
{
    static_assert(t_index < num_bits<T_Type>, "Index exceeds number of bits");
 
    T_ReturnType bit = (integer & static_cast<T_Type>(UST(1) << t_index));
 
    if constexpr (t_shift == 0)
        return bit;
    else if constexpr (t_shift > 0)
    {
        static_assert(t_index + t_shift < num_bits<T_ReturnType>, "Shift exceeds highest bit.");
        return bit << static_cast<UST>(t_shift);
    }
    else
    {
        static_assert(t_index >= -t_shift, "Shift exceeds lowest bit");
        return bit >> static_cast<UST>(internal::abs(t_shift));
    }
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
 
template <std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bit(T_Type integer, UST index, I32 shift) noexcept -> T_ReturnType
{
    assert(index < num_bits<T_Type>); // NOLINT
 
    T_ReturnType bit = (integer & static_cast<T_Type>(UST(1) << index));
 
    if (shift >= 0)
    {
        assert(index + shift < num_bits<T_ReturnType>); // NOLINT
        return bit << static_cast<UST>(shift);
    }
 
    assert(index >= internal::abs(shift)); // NOLINT // LCOV_EXCL_LINE
    return bit >> static_cast<UST>(internal::abs(shift));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_index, bool t_shift_right, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bit_shift_max(T_Type integer) noexcept -> T_ReturnType
{
    // cppcheck-suppress unreadVariable // false positive
    constexpr I32 shift =
            t_shift_right ? -static_cast<I32>(t_index) : static_cast<I32>(num_bits<T_ReturnType> - t_index - 1);
    return get_bit<t_index, shift, T_Type, T_ReturnType>(integer);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <bool t_shift_right, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bit_shift_max(T_Type integer, UST index) noexcept -> T_ReturnType
{
    if constexpr (t_shift_right)
        return get_bit<T_Type, T_ReturnType>(integer, index, -static_cast<I32>(index));
    else
        return get_bit<T_Type, T_ReturnType>(integer, index, static_cast<I32>(num_bits<T_ReturnType> - index - 1));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_index, UST t_num_bits, I32 t_shift, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bits(T_Type integer) noexcept -> T_ReturnType
{
    static_assert(t_num_bits > 1, "Number of bits must be larger than 0.");
    static_assert(t_index + t_num_bits <= num_bits<T_Type>, "Required bits exceed maximum number of bits.");
 
    constexpr UST mask = bit_construct_set_first_n_bits<UST, t_num_bits>() << t_index;
    auto          bits = static_cast<T_ReturnType>(integer & mask);
 
    if constexpr (t_shift == 0)
    {
        static_assert(t_index + t_num_bits <= num_bits<T_ReturnType>, "Shifted bits exceed highest bit.");
        return bits;
    }
    else if constexpr (t_shift > 0)
    {
        static_assert(t_index + t_num_bits + t_shift <= num_bits<T_ReturnType>, "Shifted bits exceed highest bit.");
        return bits << static_cast<UST>(t_shift);
    }
    else
    {
        static_assert(t_index >= -t_shift, "Shifted bits exceed lowest bit.");
        return bits >> static_cast<UST>(internal::abs(t_shift));
    }
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_bits, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bits(T_Type integer, UST index, I32 shift) noexcept -> T_ReturnType
{
    static_assert(t_num_bits > 1, "Number of bits must be larger than 0.");
    assert(index + t_num_bits <= num_bits<T_Type>); // NOLINT
 
    UST  mask = bit_construct_set_first_n_bits<UST, t_num_bits>() << index;
    auto bits = static_cast<T_ReturnType>(integer & mask);
 
    if (shift >= 0)
    {
        assert(index + t_num_bits + shift <= num_bits<T_ReturnType>); // NOLINT // LCOV_EXCL_LINE
        return bits << static_cast<UST>(shift);
    }
 
    assert(index >= internal::abs(shift)); // NOLINT // LCOV_EXCL_LINE
    return bits >> static_cast<UST>(internal::abs(shift));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST                    t_index,
          UST                    t_num_bits,
          bool                   t_shift_right,
          std::unsigned_integral T_Type,
          std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bits_shift_max(T_Type integer) noexcept -> T_ReturnType
{
    // cppcheck-suppress unreadVariable // false positive
    constexpr I32 shift = t_shift_right ? -static_cast<I32>(t_index)
                                        : static_cast<I32>(num_bits<T_ReturnType> - t_index - t_num_bits);
    return get_bits<t_index, t_num_bits, shift, T_Type, T_ReturnType>(integer);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_bits, bool t_shift_right, std::unsigned_integral T_Type, std::unsigned_integral T_ReturnType>
[[nodiscard]] constexpr auto get_bits_shift_max(T_Type integer, UST index) noexcept -> T_ReturnType
{
    if constexpr (t_shift_right)
        return get_bits<t_num_bits, T_Type, T_ReturnType>(integer, index, -static_cast<I32>(index));
    else
        return get_bits<t_num_bits, T_Type, T_ReturnType>(
                integer, index, static_cast<I32>(num_bits<T_ReturnType> - index - t_num_bits));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <typename T_Type>
[[nodiscard]] constexpr auto is_bit_set(T_Type integer, UST index) noexcept -> bool
{
    return static_cast<bool>(get_bit(integer, index));
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <std::unsigned_integral T_Type>
constexpr void set_bit(T_Type& integer, UST index) noexcept
{
    assert(index < num_bits<T_Type> && "Index exceeds number of bits."); // NOLINT
 
    integer |= static_cast<T_Type>(UST(1) << index);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_value, std::unsigned_integral T_Type>
constexpr void set_bit_to(T_Type& integer, UST index) noexcept
{
    static_assert(t_value <= 1UL, "Bit value must either be 0 or 1.");
 
    if constexpr (t_value == 1UL)
        set_bit(integer, index);
    else
        clear_bit(integer, index);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_bits, std::unsigned_integral T_Type>
constexpr void set_bits(T_Type& integer, UST index) noexcept
{
    assert(index + t_num_bits <= num_bits<T_Type>); // NOLINT
 
    constexpr UST bits = bit_construct_set_first_n_bits<UST, t_num_bits>();
    integer |= static_cast<T_Type>(bits << index);
}
 
 
// --------------------------------------------------------------------------------------------------------------------
 
template <UST t_num_bits, bool t_clear_bits, std::unsigned_integral T_Type>
constexpr void set_bits_with_int(T_Type& integer, UST index, UST value) noexcept
{
    [[maybe_unused]] constexpr UST max_value = bit_construct_set_first_n_bits<UST, t_num_bits>();
 
    assert(value <= max_value && "Value doesn't fit into specified number of bits."); // NOLINT
    assert(index + t_num_bits <= num_bits<T_Type>);                                   // NOLINT
 
    if constexpr (t_clear_bits)
        clear_bits<t_num_bits>(integer, index);
 
    integer |= static_cast<T_Type>(value << index);
}
 
 
} // namespace mjolnir