bit_stream.h

Go to the documentation of this file.

 
/******************************************************************************
The MIT License(MIT)
Embedded Template Library.
https://github.com/ETLCPP/etl
https://www.etlcpp.com
Copyright(c) 2018 John Wellbelove
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files(the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions :
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
******************************************************************************/
 
#ifndef ETL_BIT_STREAM_INCLUDED
#define ETL_BIT_STREAM_INCLUDED
 
#include "platform.h"
#include "type_traits.h"
#include "nullptr.h"
#include "endianness.h"
#include "integral_limits.h"
#include "binary.h"
#include "algorithm.h"
#include "iterator.h"
#include "memory.h"
#include "delegate.h"
#include "span.h"
#include "optional.h"
#include "exception.h"
#include "error_handler.h"
 
#include <stdint.h>
#include <limits.h>
 
#include "private/minmax_push.h"
 
namespace etl
{
  //***************************************************************************
  //***************************************************************************
  class bit_stream
  {
  public:
 
    typedef const unsigned char* const_iterator;
 
    //***************************************************************************
    //***************************************************************************
    bit_stream()
      : pdata(ETL_NULLPTR)
      , length_chars(0U)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream(void* begin_, void* end_)
      : pdata(reinterpret_cast<unsigned char*>(begin_))
      , length_chars(etl::distance(reinterpret_cast<unsigned char*>(begin_), reinterpret_cast<unsigned char*>(end_)))
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream(void* begin_, size_t length_)
      : pdata(reinterpret_cast<unsigned char*>(begin_))
      , length_chars(length_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    void set_stream(void* begin_, size_t length_)
    {
      pdata  = reinterpret_cast<unsigned char*>(begin_);
      length_chars = length_;
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    void set_stream(void* begin_, void* end_)
    {
      set_stream(begin_, etl::distance(reinterpret_cast<unsigned char*>(begin_), reinterpret_cast<unsigned char*>(end_)));
    }
 
    //***************************************************************************
    //***************************************************************************
    void restart()
    {
      bits_available_in_char = CHAR_BIT;
      char_index     = 0U;
      bits_available = CHAR_BIT * length_chars;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool at_end() const
    {
      return (bits_available == 0U);
    }
 
    //***************************************************************************
    //***************************************************************************
    bool put(bool value)
    {
      bool success = false;
 
      if (pdata != ETL_NULLPTR)
      {
        if (bits_available > 0)
        {
          unsigned char chunk = value ? 1 : 0;
          put_integral(uint32_t(chunk), 1);
          success = true;
        }
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value, bool>::type
      put(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      return put_integral(static_cast<uint32_t>(value), nbits);
    }
 
#if ETL_USING_64BIT_TYPES
    //***************************************************************************
    //***************************************************************************
    bool put(int64_t value, uint_least8_t nbits = CHAR_BIT * sizeof(int64_t))
    {
      return put_integral(uint64_t(value), nbits);
    }
 
    //***************************************************************************
    //***************************************************************************
    bool put(uint64_t value, uint_least8_t nbits = CHAR_BIT * sizeof(uint64_t))
    {
      return put_integral(value, nbits);
    }
#endif
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_floating_point<T>::value, bool>::type
      put(T value)
    {
      bool success = true;
 
      unsigned char data[sizeof(T)];
      to_bytes(value, data);
 
      for (size_t i = 0UL; i < sizeof(T); ++i)
      {
        if (!put_integral(uint32_t(data[i]), CHAR_BIT))
        {
          success = false;
        }
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool get(bool& value)
    {
      bool success = false;
 
      if (pdata != ETL_NULLPTR)
      {
        // Do we have enough bits?
        if (bits_available > 0U)
        {
          value = get_bit();
          success = true;
        }
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value, bool>::type
      get(T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      bool success = false;
      uint_least8_t bits = nbits;
 
      if (pdata != ETL_NULLPTR)
      {
        // Do we have enough bits?
        if (bits_available >= nbits)
        {
          value = 0;
 
          // Get the bits from the stream.
          while (nbits != 0)
          {
            unsigned char mask_width = static_cast<unsigned char>(etl::min(nbits, bits_available_in_char));
 
            typedef typename etl::make_unsigned<T>::type chunk_t;
            chunk_t chunk = get_chunk(mask_width);
 
            nbits -= mask_width;
            value |= static_cast<T>(chunk << nbits);
          }
 
          success = true;
        }
      }
 
      // Sign extend if signed type and not already full bit width.
      if (etl::is_signed<T>::value && (bits != (CHAR_BIT * sizeof(T))))
      {
        typedef typename etl::make_signed<T>::type ST;
        value = etl::sign_extend<ST, ST>(value, bits);
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_floating_point<T>::value, bool>::type
      get(T& value)
    {
      bool success = false;
 
      if (pdata != ETL_NULLPTR)
      {
        uint_least8_t nbits = CHAR_BIT * sizeof(T);
 
        // Do we have enough bits?
        if (bits_available >= nbits)
        {
          // Temporary storage.
          etl::uninitialized_buffer_of<T, 1U> data;
 
          for (size_t i = 0UL; i < sizeof(T); ++i)
          {
             get(data.raw[i], CHAR_BIT);
          }
 
          from_bytes(reinterpret_cast<const unsigned char*>(data.raw), value);
 
          success = true;
        }
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t size() const
    {
      size_t s = char_index;
 
      // Current byte is used?
      if (bits_available_in_char != CHAR_BIT)
      {
        ++s;
      }
 
      return s;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t bits() const
    {
      return (length_chars * CHAR_BIT) - bits_available;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator begin() const
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator end() const
    {
      return pdata + size();
    }
 
  private:
 
    //***************************************************************************
    //***************************************************************************
    bool put_integral(uint32_t value, uint_least8_t nbits)
    {
      bool success = false;
 
      if (pdata != ETL_NULLPTR)
      {
        // Do we have enough bits?
        if (bits_available >= nbits)
        {
          // Send the bits to the stream.
          while (nbits != 0)
          {
            unsigned char mask_width = static_cast<unsigned char>(etl::min(nbits, bits_available_in_char));
            nbits -= mask_width;
            uint32_t mask = ((1U << mask_width) - 1U) << nbits;
            //uint32_t mask = ((uint32_t(1U) << mask_width) - 1U) << nbits;
 
            // Move chunk to lowest char bits.
            // Chunks are never larger than one char.
            uint32_t chunk = ((value & mask) >> nbits) << (bits_available_in_char - mask_width);
 
            put_chunk(static_cast<unsigned char>(chunk), mask_width);
          }
 
          success = true;
        }
      }
 
      return success;
    }
 
#if ETL_USING_64BIT_TYPES
    //***************************************************************************
    //***************************************************************************
    bool put_integral(uint64_t value, uint_least8_t nbits)
    {
      bool success = false;
 
      if (pdata != ETL_NULLPTR)
      {
        // Do we have enough bits?
        if (bits_available >= nbits)
        {
          // Send the bits to the stream.
          while (nbits != 0)
          {
            unsigned char mask_width = static_cast<unsigned char>(etl::min(nbits, bits_available_in_char));
            nbits -= mask_width;
            uint64_t mask = ((uint64_t(1U) << mask_width) - 1U) << nbits;
 
            // Move chunk to lowest char bits.
            // Chunks are never larger than one char.
            uint64_t chunk = ((value & mask) >> nbits) << (bits_available_in_char - mask_width);
 
            put_chunk(static_cast<unsigned char>(chunk), mask_width);
          }
 
          success = true;
        }
      }
 
      return success;
    }
#endif
 
    //***************************************************************************
    //***************************************************************************
    void put_chunk(unsigned char chunk, unsigned char nbits)
    {
      // Clear if new byte.
      if (bits_available_in_char == 8U)
      {
        pdata[char_index] = 0U;
      }
 
      pdata[char_index] |= chunk;
      step(nbits);
    }
 
    //***************************************************************************
    //***************************************************************************
    unsigned char get_chunk(unsigned char nbits)
    {
      unsigned char value = pdata[char_index];
 
      value >>= (bits_available_in_char - nbits);
 
      unsigned char mask;
 
      if (nbits == CHAR_BIT)
      {
        mask = etl::integral_limits<unsigned char>::max;
      }
      else
      {
        mask = (1U << nbits) - 1;
      }
 
      value &= mask;
 
      step(nbits);
 
      return value;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool get_bit()
    {
      bool result = (pdata[char_index] & (1U << (bits_available_in_char - 1U))) != 0U;
 
      step(1U);
 
      return result;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    void from_bytes(const unsigned char* data, T& value)
    {
      etl::uninitialized_buffer_of<T, 1U> temp;
 
      // Network to host.
      if (etl::endianness::value() == etl::endian::little)
      {
        etl::reverse_copy(data, data + sizeof(T), temp.raw);
      }
      else
      {
        etl::copy(data, data + sizeof(T), temp.raw);
      }
 
      value = *reinterpret_cast<T*>(temp.raw);
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    void to_bytes(T value, unsigned char* data)
    {
      unsigned char* pf = reinterpret_cast<unsigned char*>(&value);
 
      // Host to network.
      if (etl::endianness::value() == etl::endian::little)
      {
        etl::reverse_copy(pf, pf + sizeof(T), data);
      }
      else
      {
        etl::copy(pf, pf + sizeof(T), data);
      }
    }
 
    //***************************************************************************
    //***************************************************************************
    void step(unsigned char nbits)
    {
      bits_available_in_char -= nbits;
 
      if (bits_available_in_char == 0)
      {
        ++char_index;
        bits_available_in_char = 8;
      }
 
      bits_available -= nbits;
    }
 
    unsigned char *pdata;                 
    size_t        length_chars;           
    unsigned char bits_available_in_char; 
    size_t        char_index;             
    size_t        bits_available;         
  };
 
  //***************************************************************************
  //***************************************************************************
  class bit_stream_writer
  {
  public:
 
    typedef char value_type;
    typedef value_type* iterator;
    typedef const value_type* const_iterator;
    typedef etl::span<value_type> callback_parameter_type;
    typedef etl::delegate<void(callback_parameter_type)> callback_type;
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_writer(const etl::span<char, Length>& span_, etl::endian stream_endianness_, callback_type callback_ = callback_type())
      : pdata(span_.begin())
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
      , callback(callback_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_writer(const etl::span<unsigned char, Length>& span_, etl::endian stream_endianness_, callback_type callback_ = callback_type())
      : pdata(reinterpret_cast<char*>(span_.begin()))
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
      , callback(callback_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream_writer(void* begin_, void* end_, etl::endian stream_endianness_, callback_type callback_ = callback_type())
      : pdata(reinterpret_cast<char*>(begin_))
      , length_chars(etl::distance(reinterpret_cast<unsigned char*>(begin_), reinterpret_cast<unsigned char*>(end_)))
      , stream_endianness(stream_endianness_)
      , callback(callback_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream_writer(void* begin_, size_t length_chars_, etl::endian stream_endianness_, callback_type callback_ = callback_type())
      : pdata(reinterpret_cast<char*>(begin_))
      , length_chars(length_chars_)
      , stream_endianness(stream_endianness_)
      , callback(callback_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    void restart()
    {
      bits_available_in_char = CHAR_BIT;
      char_index = 0U;
      bits_available = capacity_bits();
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t capacity_bytes() const
    {
      return length_chars;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t capacity_bits() const
    {
      return length_chars * CHAR_BIT;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool empty() const
    {
      return (available_bits() == capacity_bits());
    }
 
    //***************************************************************************
    //***************************************************************************
    bool full() const
    {
      return (available_bits() == 0U);
    }
 
    //***************************************************************************
    //***************************************************************************
    void write_unchecked(bool value)
    {
      unsigned char chunk = value ? 1 : 0;
      write_data<unsigned char>(chunk, 1);
    }
 
    //***************************************************************************
    //***************************************************************************
    bool write(bool value)
    {
      bool success = (available<1U>() > 0U);
 
      if (success)
      {
        write_unchecked(value);
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value, void>::type
      write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      typedef typename etl::unsigned_type<T>::type unsigned_t;
 
      write_data<unsigned_t>(static_cast<unsigned_t>(value), nbits);
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value, bool>::type
      write(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      bool success = (available(nbits) > 0U);
 
      if (success)
      {
        write_unchecked(value, nbits);
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool skip(size_t nbits)
    {
      bool success = (nbits <= available_bits());
 
      if (success)
      {
        while (nbits > bits_available_in_char)
        {
          step(bits_available_in_char);
          nbits -= bits_available_in_char;
        }
 
        if (nbits != 0U)
        {
          step(static_cast<unsigned char>(nbits));
        }
      }
 
      return success;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t size_bytes() const
    {
      size_t s = char_index;
 
      // Is the current byte partially used?
      if (bits_available_in_char != CHAR_BIT)
      {
        ++s;
      }
 
      return s;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t size_bits() const
    {
      return capacity_bits() - available_bits();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Nbits>
    size_t available() const
    {
      return bits_available / Nbits;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    size_t available() const
    {
      return available<CHAR_BIT * sizeof(T)>();
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t available(size_t nbits) const
    {
      return bits_available / nbits;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t available_bits() const
    {
      return bits_available;
    }
 
    //***************************************************************************
    //***************************************************************************
    iterator begin()
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator begin() const
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator cbegin() const
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    iterator end()
    {
      return pdata + size_bytes();
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator end() const
    {
      return pdata + size_bytes();
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator cend() const
    {
      return pdata + size_bytes();
    }
 
    //***************************************************************************
    //***************************************************************************
    etl::span<char> used_data()
    {
      return etl::span<char>(pdata, pdata + size_bytes());
    }
 
    //***************************************************************************
    //***************************************************************************
    etl::span<const char> used_data() const
    {
      return etl::span<const char>(pdata, pdata + size_bytes());
    }
 
    //***************************************************************************
    //***************************************************************************
    etl::span<char> data()
    {
      return etl::span<char>(pdata, pdata + length_chars);
    }
 
    //***************************************************************************
    //***************************************************************************
    etl::span<const char> data() const
    {
      return etl::span<const char>(pdata, pdata + length_chars);
    }
 
    //***************************************************************************
    //***************************************************************************
    void flush()
    {
      if (callback.is_valid())
      {
        if (bits_available_in_char != 0U)
        {
          char_index = 1U; // Indicate that the first char is actually 'full'.
          flush_full_bytes();
        }
 
        restart();
      }
    }
 
    //***************************************************************************
    //***************************************************************************
    void set_callback(callback_type callback_)
    {
      callback = callback_;
    }
 
    //***************************************************************************
    //***************************************************************************
    callback_type get_callback() const
    {
      return callback;
    }
 
  private:
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    void write_data(T value, uint_least8_t nbits)
    {
      // Make sure that we are not writing more bits than should be available.
      nbits = (nbits > (CHAR_BIT * sizeof(T))) ? (CHAR_BIT * sizeof(T)) : nbits;
 
      if (stream_endianness == etl::endian::little)
      {
        value = etl::reverse_bits(value);
        value = value >> ((CHAR_BIT * sizeof(T)) - nbits);
      }
 
      // Send the bits to the stream.
      while (nbits != 0)
      {
        unsigned char mask_width = static_cast<unsigned char>(etl::min(nbits, bits_available_in_char));
        nbits -= mask_width;
        T mask = ((T(1U) << mask_width) - 1U) << nbits;
 
        // Move chunk to lowest char bits.
        // Chunks are never larger than one char.
        T chunk = ((value & mask) >> nbits) << (bits_available_in_char - mask_width);
 
        write_chunk(static_cast<char>(chunk), mask_width);
      }
 
      if (callback.is_valid())
      {
        flush_full_bytes();
      }
    }
 
    //***************************************************************************
    //***************************************************************************
    void write_chunk(char chunk, unsigned char nbits)
    {
      // Clear if new byte.
      if (bits_available_in_char == CHAR_BIT)
      {
        pdata[char_index] = 0U;
      }
 
      pdata[char_index] |= chunk;
      step(nbits);
    }
 
    //***************************************************************************
    //***************************************************************************
    void flush_full_bytes()
    {
      // Is the first byte fully filled?
      if (char_index > 0U)
      {
        callback(callback_parameter_type(pdata, pdata + char_index));
 
        bits_available = CHAR_BIT * length_chars;
 
        if (bits_available_in_char != 0U)
        {
          // Move a partially filled last byte to the start of the buffer.
          pdata[0] = pdata[char_index];
          bits_available -= (CHAR_BIT - bits_available_in_char);
        }
 
        char_index = 0U;
      }
    }
 
    //***************************************************************************
    //***************************************************************************
    void step(unsigned char nbits)
    {
      bits_available_in_char -= nbits;
 
      if (bits_available_in_char == 0)
      {
        ++char_index;
        bits_available_in_char = CHAR_BIT;
      }
 
      bits_available -= nbits;
    }
 
    char* const       pdata;                  
    const size_t      length_chars;           
    const etl::endian stream_endianness;      
    unsigned char     bits_available_in_char; 
    size_t            char_index;             
    size_t            bits_available;         
    callback_type     callback;               
  };
 
  //***************************************************************************
  //***************************************************************************
  inline void write_unchecked(etl::bit_stream_writer& stream, bool value)
  {
    stream.write_unchecked(value);
  }
 
  //***************************************************************************
  //***************************************************************************
  inline bool write(etl::bit_stream_writer& stream, bool value)
  {
    return stream.write(value);
  }
 
  //***************************************************************************
  //***************************************************************************
  template <typename T>
  typename etl::enable_if<etl::is_integral<T>::value, void>::type
    write_unchecked(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
  {
    stream.write_unchecked(value, nbits);
  }
 
  //***************************************************************************
  //***************************************************************************
  template <typename T>
  typename etl::enable_if<etl::is_integral<T>::value, bool>::type
    write(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
  {
    return stream.write(value, nbits);
  }
 
  //***************************************************************************
  //***************************************************************************
  class bit_stream_reader
  {
  public:
 
    typedef char value_type;
    typedef const char* const_iterator;
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_reader(const etl::span<char, Length>& span_, etl::endian stream_endianness_)
      : pdata(span_.begin())
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_reader(const etl::span<unsigned char, Length>& span_, etl::endian stream_endianness_)
      : pdata(reinterpret_cast<const char*>(span_.begin()))
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_reader(const etl::span<const char, Length>& span_, etl::endian stream_endianness_)
      : pdata(span_.begin())
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <size_t Length>
    bit_stream_reader(const etl::span<const unsigned char, Length>& span_, etl::endian stream_endianness_)
      : pdata(reinterpret_cast<const char*>(span_.begin()))
      , length_chars(span_.size_bytes())
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream_reader(const void* begin_, const void* end_, etl::endian stream_endianness_)
      : pdata(reinterpret_cast<const char*>(begin_))
      , length_chars(etl::distance(reinterpret_cast<const char*>(begin_), reinterpret_cast<const char*>(end_)))
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    bit_stream_reader(const void* begin_, size_t length_, etl::endian stream_endianness_)
      : pdata(reinterpret_cast<const char*>(begin_))
      , length_chars(length_)
      , stream_endianness(stream_endianness_)
    {
      restart();
    }
 
    //***************************************************************************
    //***************************************************************************
    void restart()
    {
      bits_available_in_char = CHAR_BIT;
      char_index = 0U;
      bits_available = CHAR_BIT * length_chars;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_same<bool, T>::value, bool>::type
      read_unchecked()
    {
      return get_bit();
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_same<bool, T>::value, etl::optional<bool> >::type
      read()
    {
      etl::optional<bool> result;
 
      if (bits_available > 0U)
      {
        result = read_unchecked<bool>();
      }
 
      return result;
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value && !etl::is_same<bool, T>::value, T>::type
      read_unchecked(uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      typedef typename etl::unsigned_type<T>::type unsigned_t;
 
      T value = read_value<unsigned_t>(nbits, etl::is_signed<T>::value);
 
      return static_cast<T>(value);
    }
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    typename etl::enable_if<etl::is_integral<T>::value && !etl::is_same<bool, T>::value, etl::optional<T> >::type
      read(uint_least8_t nbits = CHAR_BIT * sizeof(T))
    {
      etl::optional<T> result;
 
      // Do we have enough bits?
      if (bits_available >= nbits)
      {
        result = read_unchecked<T>(nbits); 
      }
 
      return result;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t size_bytes() const
    {
      return length_chars;
    }
 
    //***************************************************************************
    //***************************************************************************
    size_t size_bits() const
    {
      return length_chars * CHAR_BIT;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator begin() const
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator cbegin() const
    {
      return pdata;
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator end() const
    {
      return pdata + size_bytes();
    }
 
    //***************************************************************************
    //***************************************************************************
    const_iterator cend() const
    {
      return pdata + size_bytes();
    }
 
    //***************************************************************************
    //***************************************************************************
    etl::span<const char> data() const
    {
      return etl::span<const char>(pdata, pdata + length_chars);
    }
 
    //***************************************************************************
    //***************************************************************************
    bool skip(size_t nbits)
    {
      bool success = (nbits <= bits_available);
 
      if (success)
      {
        while (nbits > bits_available_in_char)
        {
          nbits -= bits_available_in_char;
          step(bits_available_in_char);
        }
 
        if (nbits != 0U)
        {
          step(static_cast<unsigned char>(nbits));
        }
      }
 
      return success;
    }
 
  private:
 
    //***************************************************************************
    //***************************************************************************
    template <typename T>
    T read_value(uint_least8_t nbits, bool is_signed)
    {
      // Make sure that we are not reading more bits than should be available.
      nbits = (nbits > (CHAR_BIT * sizeof(T))) ? (CHAR_BIT * sizeof(T)) : nbits;
 
      T value = 0;
      uint_least8_t bits = nbits;
 
      // Get the bits from the stream.
      while (nbits != 0)
      {
        unsigned char mask_width = static_cast<unsigned char>(etl::min(nbits, bits_available_in_char));
 
        T chunk = get_chunk(mask_width);
 
        nbits -= mask_width;
        value |= static_cast<T>(chunk << nbits);
      }
 
      if (stream_endianness == etl::endian::little)
      {
        value = value << ((CHAR_BIT * sizeof(T)) - bits);
        value = etl::reverse_bits(value);
      }
 
      if (is_signed && (bits != (CHAR_BIT * sizeof(T))))
      {
        value = etl::sign_extend<T, T>(value, bits);
      }
 
      return value;
    }
 
    //***************************************************************************
    //***************************************************************************
    unsigned char get_chunk(unsigned char nbits)
    {
      unsigned char value = pdata[char_index];
      value >>= (bits_available_in_char - nbits);
 
      unsigned char mask;
 
      if (nbits == CHAR_BIT)
      {
        mask = etl::integral_limits<unsigned char>::max;
      }
      else
      {
        mask = (1U << nbits) - 1;
      }
 
      value &= mask;
 
      step(nbits);
 
      return value;
    }
 
    //***************************************************************************
    //***************************************************************************
    bool get_bit()
    {
      bool result = (pdata[char_index] & (1U << (bits_available_in_char - 1U))) != 0U;
 
      step(1U);
 
      return result;
    }
 
    //***************************************************************************
    //***************************************************************************
    void step(unsigned char nbits)
    {
      bits_available_in_char -= nbits;
 
      if (bits_available_in_char == 0)
      {
        ++char_index;
        bits_available_in_char = 8;
      }
 
      bits_available -= nbits;
    }
 
    const char*       pdata;                  
    size_t            length_chars;           
    const etl::endian stream_endianness;      
    unsigned char     bits_available_in_char; 
    size_t            char_index;             
    size_t            bits_available;         
  };
 
  //***************************************************************************
  //***************************************************************************
  template <typename T>
  T read_unchecked(etl::bit_stream_reader& stream)
  {
    return stream.read_unchecked<T>();
  }
 
  template <typename T>
  T read_unchecked(etl::bit_stream_reader& stream, uint_least8_t nbits)
  {
    return stream.read_unchecked<T>(nbits);
  }
 
  //***************************************************************************
  //***************************************************************************
  template <typename T>
  etl::optional<T> read(etl::bit_stream_reader& stream)
  {
    return stream.read<T>();
  }
 
  template <typename T>
  etl::optional<T> read(etl::bit_stream_reader& stream, uint_least8_t nbits)
  {
    return stream.read<T>(nbits);
  }
 
  //***************************************************************************
  //***************************************************************************
  template <>
  inline bool read_unchecked<bool>(etl::bit_stream_reader& stream)
  {
    return stream.read_unchecked<bool>();
  }
 
  //***************************************************************************
  //***************************************************************************
  template <>
  inline etl::optional<bool> read<bool>(etl::bit_stream_reader& stream)
  {
    return stream.read<bool>();
  }
}
 
#include "private/minmax_pop.h"
 
#endif