bit_stream.hpp

#pragma once
 
#include "nalchi/character.hpp"
#include "nalchi/export.hpp"
#include "nalchi/make_unsigned_allow_bool.hpp"
#include "nalchi/shared_payload.hpp"
 
#include <algorithm>
#include <bit>
#include <concepts>
#include <cstdint>
#include <limits>
#include <span>
#include <string>
#include <string_view>
#include <type_traits>
 
#define NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(ret_val) \
    do \
    { \
        if (fail()) \
            return ret_val; \
    } while (false)
 
#define NALCHI_BIT_STREAM_WRITER_FAIL_IF_WRITE_AFTER_FINAL_FLUSH(ret_val) \
    do \
    { \
        if (_final_flushed) \
        { \
            _fail = true; \
            return ret_val; \
        } \
    } while (false)
 
#define NALCHI_BIT_STREAM_FAIL_IF_MIN_MAX_RANGE_INVALID(ret_val) \
    do \
    { \
        if (min >= max) \
        { \
            _fail = true; \
            return ret_val; \
        } \
    } while (false)
 
#define NALCHI_BIT_STREAM_WRITER_FAIL_IF_DATA_OUT_OF_RANGE(ret_val) \
    do \
    { \
        if (data < min || data > max) \
        { \
            _fail = true; \
            return ret_val; \
        } \
    } while (false)
 
#define NALCHI_BIT_STREAM_WRITER_FAIL_IF_STR_OVERFLOW(prefix_bytes, str_len_bytes) \
    do \
    { \
        if (_logical_used_bits + STR_LEN_PREFIX_PREFIX_BITS + (8 * (prefix_bytes)) + (8 * (str_len_bytes)) > \
            _logical_total_bits) \
        { \
            _fail = true; \
            return *this; \
        } \
    } while (false)
 
#define NALCHI_BIT_STREAM_READER_FAIL_IF_STR_OVERFLOW(str_len_bytes) \
    do \
    { \
        if (_logical_used_bits + (8 * (str_len_bytes)) > _logical_total_bits) \
        { \
            _fail = true; \
            return *this; \
        } \
    } while (false)
 
namespace nalchi
{
 
class bit_stream_writer final
{
public:
    using size_type = std::uint32_t; 
 
    using scratch_type = std::uint64_t; 
    using word_type = std::uint32_t;    
 
    static_assert(std::is_unsigned_v<scratch_type>);
    static_assert(std::is_unsigned_v<word_type>);
    static_assert(sizeof(scratch_type) == 2 * sizeof(word_type));
 
    static_assert(std::endian::native == std::endian::little || std::endian::native == std::endian::big,
                  "Mixed endian system is not supported");
 
public:
    // "prefix of string length prefix"
    // 0: u8 / 1: u16 / 2: u32 / 3: u64
    static constexpr size_type STR_LEN_PREFIX_PREFIX_BITS = 2u;
    static constexpr size_type MIN_STR_LEN_PREFIX_PREFIX = 0u;
    static constexpr size_type MAX_STR_LEN_PREFIX_PREFIX = 3u;
 
private:
    scratch_type _scratch;
    std::span<word_type> _words;
 
    int _scratch_index;
    int _words_index;
 
    // These fields are required, because logical user buffer size might differ from `_words` size.
    //
    // e.g. If user passed `shared_payload` whose size is 5 bytes,
    // the actual allocated buffer is 8 bytes, to avoid overrun writes.
    // But for the user's perspective, writing more than 5 bytes should be treated as an overflow.
    size_type _logical_total_bits;
    size_type _logical_used_bits;
 
    bool _init_fail;
    bool _fail;
 
    bool _final_flushed;
 
public:
    bit_stream_writer(const bit_stream_writer&) = delete;
 
    auto operator=(const bit_stream_writer&) -> bit_stream_writer& = delete;
 
    NALCHI_API bit_stream_writer();
 
    NALCHI_API bit_stream_writer(shared_payload buffer, size_type logical_bytes_length);
 
    NALCHI_API bit_stream_writer(std::span<word_type> buffer, size_type logical_bytes_length);
 
    NALCHI_API bit_stream_writer(word_type* begin, word_type* end, size_type logical_bytes_length);
 
    NALCHI_API bit_stream_writer(word_type* begin, size_type words_length, size_type logical_bytes_length);
 
public:
    NALCHI_API void set_fail()
    {
        _fail = true;
    }
 
    NALCHI_API bool fail() const noexcept
    {
        return _fail;
    }
 
    NALCHI_API bool operator!() const noexcept
    {
        return fail();
    }
 
    NALCHI_API operator bool() const noexcept
    {
        return !fail();
    }
 
public:
    NALCHI_API auto total_bytes() const -> size_type
    {
        return _logical_total_bits / 8;
    }
 
    NALCHI_API auto total_bits() const -> size_type
    {
        return _logical_total_bits;
    }
 
    NALCHI_API auto used_bytes() const -> size_type;
 
    NALCHI_API auto used_bits() const -> size_type
    {
        return _logical_used_bits;
    }
 
    NALCHI_API auto unused_bytes() const -> size_type
    {
        return total_bytes() - used_bytes();
    }
 
    NALCHI_API auto unused_bits() const -> size_type
    {
        return total_bits() - used_bits();
    }
 
public:
    NALCHI_API void restart();
 
    NALCHI_API void reset();
 
    NALCHI_API void reset_with(shared_payload buffer, size_type logical_bytes_length);
 
    NALCHI_API void reset_with(std::span<word_type> buffer, size_type logical_bytes_length);
 
    NALCHI_API void reset_with(word_type* begin, word_type* end, size_type logical_bytes_length);
 
    NALCHI_API void reset_with(word_type* begin, size_type words_length, size_type logical_bytes_length);
 
    NALCHI_API auto flush_final() -> bit_stream_writer&;
 
    NALCHI_API bool flushed() const
    {
        return _final_flushed;
    }
 
public:
    NALCHI_API auto write(const void* data, size_type size) -> bit_stream_writer&;
 
    template <std::integral SInt>
        requires(sizeof(SInt) <= sizeof(word_type))
    auto write(SInt data, SInt min = std::numeric_limits<SInt>::min(), SInt max = std::numeric_limits<SInt>::max())
        -> bit_stream_writer&
    {
        return do_write<true>(data, min, max);
    }
 
    template <std::integral BInt>
        requires(sizeof(BInt) > sizeof(word_type))
    auto write(BInt data, BInt min = std::numeric_limits<BInt>::min(), BInt max = std::numeric_limits<BInt>::max())
        -> bit_stream_writer&
    {
        return do_write<true>(data, min, max);
    }
 
    NALCHI_API auto write(float data) -> bit_stream_writer&;
 
    NALCHI_API auto write(double data) -> bit_stream_writer&;
 
    template <character CharT, typename CharTraits>
    auto write(std::basic_string_view<CharT, CharTraits> str) -> bit_stream_writer&
    {
        NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
        NALCHI_BIT_STREAM_WRITER_FAIL_IF_WRITE_AFTER_FINAL_FLUSH(*this);
 
        // Get the length of the string.
        const auto len = str.length();
 
        // Write a "prefix of length prefix" + length prefix.
        // 0: u8 / 1: u16 / 2: u32 / 3: u64
        if (len <= std::numeric_limits<std::uint8_t>::max())
        {
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_STR_OVERFLOW(sizeof(std::uint8_t), len * sizeof(CharT));
            do_write<false>(size_type(0), MIN_STR_LEN_PREFIX_PREFIX,
                            MAX_STR_LEN_PREFIX_PREFIX);      // prefix of length prefix
            do_write<false>(static_cast<std::uint8_t>(len)); // length prefix
        }
        else if (len <= std::numeric_limits<std::uint16_t>::max())
        {
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_STR_OVERFLOW(sizeof(std::uint16_t), len * sizeof(CharT));
            do_write<false>(size_type(1), MIN_STR_LEN_PREFIX_PREFIX,
                            MAX_STR_LEN_PREFIX_PREFIX);       // prefix of length prefix
            do_write<false>(static_cast<std::uint16_t>(len)); // length prefix
        }
        else if (len <= std::numeric_limits<std::uint32_t>::max())
        {
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_STR_OVERFLOW(sizeof(std::uint32_t), len * sizeof(CharT));
            do_write<false>(size_type(2), MIN_STR_LEN_PREFIX_PREFIX,
                            MAX_STR_LEN_PREFIX_PREFIX);       // prefix of length prefix
            do_write<false>(static_cast<std::uint32_t>(len)); // length prefix
        }
        else // len <= std::numeric_limits<std::uint64_t>::max()
        {
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_STR_OVERFLOW(sizeof(std::uint64_t), len * sizeof(CharT));
            do_write<false>(size_type(3), MIN_STR_LEN_PREFIX_PREFIX,
                            MAX_STR_LEN_PREFIX_PREFIX);       // prefix of length prefix
            do_write<false>(static_cast<std::uint64_t>(len)); // length prefix
        }
 
        // Just write every character one by one.
        for (const auto ch : str)
            do_write<false>(ch);
 
        return *this;
    }
 
    template <character CharT, typename CharTraits, typename Allocator>
    auto write(const std::basic_string<CharT, CharTraits, Allocator>& str) -> bit_stream_writer&
    {
        return write(std::basic_string_view<CharT, CharTraits>(str));
    }
 
    template <character CharT>
    auto write(const CharT* str) -> bit_stream_writer&
    {
        return write(std::basic_string_view<CharT>(str));
    }
 
private:
    template <bool Checked, std::integral SInt>
        requires(sizeof(SInt) <= sizeof(word_type))
    auto do_write(SInt data, SInt min = std::numeric_limits<SInt>::min(), SInt max = std::numeric_limits<SInt>::max())
        -> bit_stream_writer&
    {
        if constexpr (Checked)
        {
            NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_WRITE_AFTER_FINAL_FLUSH(*this);
            NALCHI_BIT_STREAM_FAIL_IF_MIN_MAX_RANGE_INVALID(*this);
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_DATA_OUT_OF_RANGE(*this);
        }
 
        using UInt = make_unsigned_allow_bool_t<SInt>;
 
        // Convert `data` to `value` to actually write.
        const scratch_type value = static_cast<UInt>(((UInt)data) - ((UInt)min));
        const int bits = std::bit_width(static_cast<UInt>(((UInt)max) - ((UInt)min)));
 
        if constexpr (Checked)
        {
            // Fail if user buffer overflows.
            if (_logical_used_bits + bits > _logical_total_bits)
            {
                _fail = true;
                return *this;
            }
        }
 
        // Write `value` to `_scratch`, and flush if scratch overflow.
        _scratch |= (value << _scratch_index);
        _scratch_index += bits;
        flush_if_scratch_overflow();
 
        // Adjust used bits
        _logical_used_bits += bits;
 
        return *this;
    }
 
    template <bool Checked, std::integral BInt>
        requires(sizeof(BInt) > sizeof(word_type))
    auto do_write(BInt data, BInt min = std::numeric_limits<BInt>::min(), BInt max = std::numeric_limits<BInt>::max())
        -> bit_stream_writer&
    {
        if constexpr (Checked)
        {
            NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_WRITE_AFTER_FINAL_FLUSH(*this);
            NALCHI_BIT_STREAM_FAIL_IF_MIN_MAX_RANGE_INVALID(*this);
            NALCHI_BIT_STREAM_WRITER_FAIL_IF_DATA_OUT_OF_RANGE(*this);
        }
 
        // Current logic assumes the only size here is 64 bits, but hey who wouldn't?
        static_assert(sizeof(BInt) == 2 * sizeof(word_type));
 
        using UInt = make_unsigned_allow_bool_t<BInt>;
 
        // Convert `data` to `value`.
        const scratch_type value = static_cast<UInt>(((UInt)data) - ((UInt)min));
        const int bits = std::bit_width(static_cast<UInt>(((UInt)max) - ((UInt)min)));
 
        if constexpr (Checked)
        {
            // Fail if user buffer overflows.
            if (_logical_used_bits + bits > _logical_total_bits)
            {
                _fail = true;
                return *this;
            }
        }
 
        // Split lower half of `value`
        const scratch_type low = (value << (8 * sizeof(word_type))) >> (8 * sizeof(word_type));
        const int low_bits = std::min(bits, static_cast<int>(8 * sizeof(word_type)));
 
        // Write lower half to `_scratch`, and flush if scratch overflow.
        _scratch |= (low << _scratch_index);
        _scratch_index += low_bits;
        flush_if_scratch_overflow();
 
        const int high_bits = bits - low_bits;
        if (high_bits > 0)
        {
            // Split higher half of `value`
            const scratch_type high = (value >> (8 * sizeof(word_type)));
 
            // Write higher half to `_scratch`, and flush if scratch overflow.
            _scratch |= (high << _scratch_index);
            _scratch_index += high_bits;
            flush_if_scratch_overflow();
        }
 
        // Adjust used bits
        _logical_used_bits += bits;
 
        return *this;
    }
 
private:
    NALCHI_API void flush_if_scratch_overflow();
 
    NALCHI_API void do_flush_word_unchecked();
};
 
class bit_stream_measurer final
{
public:
    using size_type = bit_stream_writer::size_type; 
 
private:
    size_type _logical_used_bits = 0;
 
public:
    bit_stream_measurer(const bit_stream_measurer&) = delete;
 
    auto operator=(const bit_stream_measurer&) -> bit_stream_measurer& = delete;
 
    NALCHI_API bit_stream_measurer() = default;
 
public:
    NALCHI_API auto used_bytes() const -> size_type;
 
    NALCHI_API auto used_bits() const -> size_type
    {
        return _logical_used_bits;
    }
 
public:
    NALCHI_API void restart()
    {
        _logical_used_bits = 0;
    }
 
public:
    NALCHI_API auto write([[maybe_unused]] const void* data, size_type size) -> bit_stream_measurer&
    {
        _logical_used_bits += 8 * size;
        return *this;
    }
 
    template <std::integral Int>
    auto write([[maybe_unused]] Int data, Int min = std::numeric_limits<Int>::min(),
               Int max = std::numeric_limits<Int>::max()) -> bit_stream_measurer&
    {
        using UInt = make_unsigned_allow_bool_t<Int>;
 
        // Convert `data` to `value`.
        const int bits = std::bit_width(static_cast<UInt>(((UInt)max) - ((UInt)min)));
 
        // Adjust used bits
        _logical_used_bits += static_cast<size_type>(bits);
 
        return *this;
    }
 
    NALCHI_API auto write(float data) -> bit_stream_measurer&
    {
        _logical_used_bits += static_cast<size_type>(8 * sizeof(data));
        return *this;
    }
 
    NALCHI_API auto write(double data) -> bit_stream_measurer&
    {
        _logical_used_bits += static_cast<size_type>(8 * sizeof(data));
        return *this;
    }
 
    template <character CharT, typename CharTraits>
    auto write(std::basic_string_view<CharT, CharTraits> str) -> bit_stream_measurer&
    {
        // Fake-write a prefix of length prefix.
        _logical_used_bits += bit_stream_writer::STR_LEN_PREFIX_PREFIX_BITS;
 
        // Get the length of the string.
        const auto len = str.length();
 
        // Fake-write a length prefix.
        if (len <= std::numeric_limits<std::uint8_t>::max())
        {
            _logical_used_bits += (8 * sizeof(std::uint8_t));
        }
        else if (len <= std::numeric_limits<std::uint16_t>::max())
        {
            _logical_used_bits += (8 * sizeof(std::uint16_t));
        }
        else if (len <= std::numeric_limits<std::uint32_t>::max())
        {
            _logical_used_bits += (8 * sizeof(std::uint32_t));
        }
        else // len <= std::numeric_limits<std::uint64_t>::max()
        {
            _logical_used_bits += (8 * sizeof(std::uint64_t));
        }
 
        // Fake-write the string payload.
        _logical_used_bits += static_cast<size_type>(8 * len * sizeof(CharT));
 
        return *this;
    }
 
    template <character CharT, typename CharTraits, typename Allocator>
    auto write(const std::basic_string<CharT, CharTraits, Allocator>& str) -> bit_stream_measurer&
    {
        return write(std::basic_string_view<CharT, CharTraits>(str));
    }
 
    template <character CharT>
    auto write(const CharT* str) -> bit_stream_measurer&
    {
        return write(std::basic_string_view<CharT>(str));
    }
};
 
class bit_stream_reader final
{
public:
    using size_type = bit_stream_writer::size_type;   
    using ssize_type = std::make_signed_t<size_type>; 
 
    using scratch_type =
        bit_stream_writer::scratch_type;            
    using word_type = bit_stream_writer::word_type; 
 
private:
    scratch_type _scratch;
    std::span<const word_type> _words;
 
    int _scratch_bits;
    int _words_index;
 
    size_type _logical_total_bits;
    size_type _logical_used_bits;
 
    bool _init_fail;
    bool _fail;
 
public:
    bit_stream_reader(const bit_stream_reader&) = delete;
 
    auto operator=(const bit_stream_reader&) -> bit_stream_reader& = delete;
 
    NALCHI_API bit_stream_reader();
 
    NALCHI_API bit_stream_reader(std::span<const word_type> buffer, size_type logical_bytes_length);
 
    NALCHI_API bit_stream_reader(const word_type* begin, const word_type* end, size_type logical_bytes_length);
 
    NALCHI_API bit_stream_reader(const word_type* begin, size_type words_length, size_type logical_bytes_length);
 
public:
    NALCHI_API void set_fail()
    {
        _fail = true;
    }
 
    NALCHI_API bool fail() const noexcept
    {
        return _fail;
    }
 
    NALCHI_API bool operator!() const noexcept
    {
        return fail();
    }
 
    NALCHI_API operator bool() const noexcept
    {
        return !fail();
    }
 
public:
    NALCHI_API auto total_bytes() const -> size_type
    {
        return _logical_total_bits / 8;
    }
 
    NALCHI_API auto total_bits() const -> size_type
    {
        return _logical_total_bits;
    }
 
    NALCHI_API auto used_bytes() const -> size_type;
 
    NALCHI_API auto used_bits() const -> size_type
    {
        return _logical_used_bits;
    }
 
    NALCHI_API auto unused_bytes() const -> size_type
    {
        return total_bytes() - used_bytes();
    }
 
    NALCHI_API auto unused_bits() const -> size_type
    {
        return total_bits() - used_bits();
    }
 
public:
    NALCHI_API void restart();
 
    NALCHI_API void reset();
 
    NALCHI_API void reset_with(std::span<const word_type> buffer, size_type logical_bytes_length);
 
    NALCHI_API void reset_with(const word_type* begin, const word_type* end, size_type logical_bytes_length);
 
    NALCHI_API void reset_with(const word_type* begin, size_type words_length, size_type logical_bytes_length);
 
public:
    NALCHI_API auto read(void* data, size_type size) -> bit_stream_reader&;
 
    template <std::integral SInt>
        requires(sizeof(SInt) <= sizeof(word_type))
    auto read(SInt& data, SInt min = std::numeric_limits<SInt>::min(), SInt max = std::numeric_limits<SInt>::max())
        -> bit_stream_reader&
    {
        return do_read<true>(data, min, max);
    }
 
    template <std::integral BInt>
        requires(sizeof(BInt) > sizeof(word_type))
    auto read(BInt& data, BInt min = std::numeric_limits<BInt>::min(), BInt max = std::numeric_limits<BInt>::max())
        -> bit_stream_reader&
    {
        return do_read<true>(data, min, max);
    }
 
    NALCHI_API auto read(float& data) -> bit_stream_reader&;
 
    NALCHI_API auto read(double& data) -> bit_stream_reader&;
 
    template <character CharT, typename CharTraits, typename Allocator>
    auto read(std::basic_string<CharT, CharTraits, Allocator>& str, size_type max_length) -> bit_stream_reader&
    {
        NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
 
        // Read the length of the string.
        ssize_type len = read_string_length();
        if (len < 0 || static_cast<size_type>(len) > max_length)
        {
            _fail = true;
            return *this;
        }
 
        NALCHI_BIT_STREAM_READER_FAIL_IF_STR_OVERFLOW(len * sizeof(CharT));
 
        // Resize and read every character one by one.
        str.resize(len);
        for (auto& ch : str)
            do_read<false>(ch);
 
        return *this;
    }
 
    template <character CharT>
    auto read(CharT* str, size_type max_length) -> bit_stream_reader&
    {
        NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
 
        // Read the length of the string.
        ssize_type len = read_string_length();
        if (len < 0 || static_cast<size_type>(len) > max_length)
        {
            _fail = true;
            return *this;
        }
 
        NALCHI_BIT_STREAM_READER_FAIL_IF_STR_OVERFLOW(len * sizeof(CharT));
 
        // Read every character one by one.
        for (ssize_type i = 0; i < len; ++i)
            do_read<false>(str[i]);
 
        // Insert final null character.
        str[len] = CharT(0);
 
        return *this;
    }
 
    NALCHI_API auto peek_string_length() -> ssize_type;
 
private:
    NALCHI_API auto read_string_length() -> ssize_type;
 
    template <bool Checked, std::integral SInt>
        requires(sizeof(SInt) <= sizeof(word_type))
    auto do_read(SInt& data, SInt min = std::numeric_limits<SInt>::min(), SInt max = std::numeric_limits<SInt>::max())
        -> bit_stream_reader&
    {
        if constexpr (Checked)
        {
            NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
            NALCHI_BIT_STREAM_FAIL_IF_MIN_MAX_RANGE_INVALID(*this);
        }
 
        using UInt = make_unsigned_allow_bool_t<SInt>;
 
        // Calculate bits to read.
        const int bits = std::bit_width(static_cast<UInt>(((UInt)max) - ((UInt)min)));
 
        if constexpr (Checked)
        {
            // Fail if no more data to be read in `_words`.
            if (_logical_used_bits + bits > _logical_total_bits)
            {
                _fail = true;
                return *this;
            }
        }
 
        // Load more bits to `_scratch` if needed.
        if (bits > _scratch_bits)
            do_fetch_word_unchecked();
 
        // Read raw `value` from `_scratch`.
        UInt value = static_cast<UInt>(_scratch & ((((scratch_type)1) << bits) - 1));
 
        // Remove read bits from `_scratch`.
        _scratch >>= bits;
        _scratch_bits -= bits;
 
        // Convert to original range.
        const SInt conv = static_cast<SInt>(((SInt)value) + min);
 
        if constexpr (Checked)
        {
            // Fail if it exceeds `max`.
            if (conv > max)
            {
                _fail = true;
                return *this;
            }
        }
 
        // Load `conv` to `data`.
        data = conv;
 
        // Adjust used bits
        _logical_used_bits += bits;
 
        return *this;
    }
 
    template <bool Checked, std::integral BInt>
        requires(sizeof(BInt) > sizeof(word_type))
    auto do_read(BInt& data, BInt min = std::numeric_limits<BInt>::min(), BInt max = std::numeric_limits<BInt>::max())
        -> bit_stream_reader&
    {
        if constexpr (Checked)
        {
            NALCHI_BIT_STREAM_RETURN_IF_STREAM_ALREADY_FAILED(*this);
            NALCHI_BIT_STREAM_FAIL_IF_MIN_MAX_RANGE_INVALID(*this);
        }
 
        // Current logic assumes the only size here is 64 bits, but hey who wouldn't?
        static_assert(sizeof(BInt) == 2 * sizeof(word_type));
 
        using UInt = make_unsigned_allow_bool_t<BInt>;
 
        // Calculate bits to read.
        const int bits = std::bit_width(static_cast<UInt>(((UInt)max) - ((UInt)min)));
 
        if constexpr (Checked)
        {
            // Fail if no more data to be read in `_words`.
            if (_logical_used_bits + bits > _logical_total_bits)
            {
                _fail = true;
                return *this;
            }
        }
 
        const int low_bits = std::min(bits, static_cast<int>(8 * sizeof(word_type)));
 
        // Load more bits to `_scratch` if needed.
        if (low_bits > _scratch_bits)
            do_fetch_word_unchecked();
 
        // Read low bits from `_scratch`.
        UInt value = static_cast<UInt>(_scratch & ((((scratch_type)1) << low_bits) - 1));
 
        // Remove read bits from `_scratch`.
        _scratch >>= low_bits;
        _scratch_bits -= low_bits;
 
        const int high_bits = bits - low_bits;
        if (high_bits > 0)
        {
            // Load more bits to `_scratch` if needed.
            if (high_bits > _scratch_bits)
                do_fetch_word_unchecked();
 
            // Read high bits from `_scratch`.
            value |= (static_cast<UInt>(_scratch & ((((scratch_type)1) << high_bits) - 1)) << low_bits);
 
            // Remove read bits from `_scratch`.
            _scratch >>= high_bits;
            _scratch_bits -= high_bits;
        }
 
        // Convert to original range.
        const BInt conv = static_cast<BInt>(((BInt)value) + min);
 
        if constexpr (Checked)
        {
            // Fail if it exceeds `max`.
            if (conv > max)
            {
                _fail = true;
                return *this;
            }
        }
 
        // Load `conv` to `data`.
        data = conv;
 
        // Adjust used bits
        _logical_used_bits += bits;
 
        return *this;
    }
 
private:
    NALCHI_API void do_fetch_word_unchecked();
};
 
} // namespace nalchi