From b4b80b7ec69ce2ed2b9ec68da9776ced89bc595f Mon Sep 17 00:00:00 2001 From: Tim Schumacher Date: Mon, 26 Dec 2022 14:32:01 +0100 Subject: [PATCH] LibCore: Add `{Big,Little}EndianOutputBitStream` Also add some tests that ensure that the input and output streams match each other, because I can't wrap my head around what the internal representation looks like. --- Tests/LibCore/TestLibCoreStream.cpp | 115 +++++++++++++++++ Userland/Libraries/LibCore/BitStream.h | 166 +++++++++++++++++++++++++ 2 files changed, 281 insertions(+) diff --git a/Tests/LibCore/TestLibCoreStream.cpp b/Tests/LibCore/TestLibCoreStream.cpp index 945302791a6..f5c7b660441 100644 --- a/Tests/LibCore/TestLibCoreStream.cpp +++ b/Tests/LibCore/TestLibCoreStream.cpp @@ -6,6 +6,7 @@ #include #include +#include #include #include #include @@ -559,3 +560,117 @@ TEST_CASE(allocating_memory_stream_10kb) offset += file_span.size(); } } + +// Bit stream tests + +// Note: This does not do any checks on the internal representation, it just ensures that the behavior of the input and output streams match. +TEST_CASE(little_endian_bit_stream_input_output_match) +{ + auto memory_stream = make(); + + // Note: The bit stream only ever reads from/writes to the underlying stream in one byte chunks, + // so testing with sizes that will not trigger a write will yield unexpected results. + auto bit_write_stream = MUST(Core::Stream::LittleEndianOutputBitStream::construct(Core::Stream::Handle(*memory_stream))); + auto bit_read_stream = MUST(Core::Stream::LittleEndianInputBitStream::construct(Core::Stream::Handle(*memory_stream))); + + // Test two mirrored chunks of a fully mirrored pattern to check that we are not dropping bits. + { + MUST(bit_write_stream->write_bits(0b1111u, 4)); + MUST(bit_write_stream->write_bits(0b1111u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1111u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1111u, result); + } + { + MUST(bit_write_stream->write_bits(0b0000u, 4)); + MUST(bit_write_stream->write_bits(0b0000u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0000u, result); + } + + // Test two mirrored chunks of a non-mirrored pattern to check that we are writing bits within a pattern in the correct order. + { + MUST(bit_write_stream->write_bits(0b1000u, 4)); + MUST(bit_write_stream->write_bits(0b1000u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + } + + // Test two different chunks to check that we are not confusing their order. + { + MUST(bit_write_stream->write_bits(0b1000u, 4)); + MUST(bit_write_stream->write_bits(0b0100u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0100u, result); + } + + // Test a pattern that spans multiple bytes. + { + MUST(bit_write_stream->write_bits(0b1101001000100001u, 16)); + auto result = MUST(bit_read_stream->read_bits(16)); + EXPECT_EQ(0b1101001000100001u, result); + } +} + +// Note: This does not do any checks on the internal representation, it just ensures that the behavior of the input and output streams match. +TEST_CASE(big_endian_bit_stream_input_output_match) +{ + auto memory_stream = make(); + + // Note: The bit stream only ever reads from/writes to the underlying stream in one byte chunks, + // so testing with sizes that will not trigger a write will yield unexpected results. + auto bit_write_stream = MUST(Core::Stream::BigEndianOutputBitStream::construct(Core::Stream::Handle(*memory_stream))); + auto bit_read_stream = MUST(Core::Stream::BigEndianInputBitStream::construct(Core::Stream::Handle(*memory_stream))); + + // Test two mirrored chunks of a fully mirrored pattern to check that we are not dropping bits. + { + MUST(bit_write_stream->write_bits(0b1111u, 4)); + MUST(bit_write_stream->write_bits(0b1111u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1111u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1111u, result); + } + { + MUST(bit_write_stream->write_bits(0b0000u, 4)); + MUST(bit_write_stream->write_bits(0b0000u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0000u, result); + } + + // Test two mirrored chunks of a non-mirrored pattern to check that we are writing bits within a pattern in the correct order. + { + MUST(bit_write_stream->write_bits(0b1000u, 4)); + MUST(bit_write_stream->write_bits(0b1000u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + } + + // Test two different chunks to check that we are not confusing their order. + { + MUST(bit_write_stream->write_bits(0b1000u, 4)); + MUST(bit_write_stream->write_bits(0b0100u, 4)); + auto result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b1000u, result); + result = MUST(bit_read_stream->read_bits(4)); + EXPECT_EQ(0b0100u, result); + } + + // Test a pattern that spans multiple bytes. + { + MUST(bit_write_stream->write_bits(0b1101001000100001u, 16)); + auto result = MUST(bit_read_stream->read_bits(16)); + EXPECT_EQ(0b1101001000100001u, result); + } +} diff --git a/Userland/Libraries/LibCore/BitStream.h b/Userland/Libraries/LibCore/BitStream.h index f78877508a5..e1067c95145 100644 --- a/Userland/Libraries/LibCore/BitStream.h +++ b/Userland/Libraries/LibCore/BitStream.h @@ -237,4 +237,170 @@ private: Handle m_stream; }; +/// A stream wrapper class that allows you to write arbitrary amounts of bits +/// in big-endian order to another stream. +class BigEndianOutputBitStream : public Stream { +public: + static ErrorOr> construct(Handle stream) + { + return adopt_nonnull_own_or_enomem(new BigEndianOutputBitStream(move(stream))); + } + + virtual ErrorOr read(Bytes) override + { + return Error::from_errno(EBADF); + } + + virtual ErrorOr write(ReadonlyBytes bytes) override + { + VERIFY(m_bit_offset == 0); + return m_stream->write(bytes); + } + + template + ErrorOr write_bits(T value, size_t bit_count) + { + VERIFY(m_bit_offset <= 7); + + while (bit_count > 0) { + u8 next_bit = (value >> (bit_count - 1)) & 1; + bit_count--; + + m_current_byte <<= 1; + m_current_byte |= next_bit; + m_bit_offset++; + + if (m_bit_offset > 7) { + TRY(m_stream->write({ &m_current_byte, sizeof(m_current_byte) })); + m_bit_offset = 0; + m_current_byte = 0; + } + } + + return {}; + } + + virtual bool is_eof() const override + { + return true; + } + + virtual bool is_open() const override + { + return m_stream->is_open(); + } + + virtual void close() override + { + } + + size_t bit_offset() const + { + return m_bit_offset; + } + + ErrorOr align_to_byte_boundary() + { + if (m_bit_offset == 0) + return {}; + + TRY(write_bits(0u, 8 - m_bit_offset)); + VERIFY(m_bit_offset == 0); + return {}; + } + +private: + BigEndianOutputBitStream(Handle stream) + : m_stream(move(stream)) + { + } + + Handle m_stream; + u8 m_current_byte { 0 }; + size_t m_bit_offset { 0 }; +}; + +/// A stream wrapper class that allows you to write arbitrary amounts of bits +/// in little-endian order to another stream. +class LittleEndianOutputBitStream : public Stream { +public: + static ErrorOr> construct(Handle stream) + { + return adopt_nonnull_own_or_enomem(new LittleEndianOutputBitStream(move(stream))); + } + + virtual ErrorOr read(Bytes) override + { + return Error::from_errno(EBADF); + } + + virtual ErrorOr write(ReadonlyBytes bytes) override + { + VERIFY(m_bit_offset == 0); + return m_stream->write(bytes); + } + + template + ErrorOr write_bits(T value, size_t bit_count) + { + VERIFY(m_bit_offset <= 7); + + size_t input_offset = 0; + while (input_offset < bit_count) { + u8 next_bit = (value >> input_offset) & 1; + input_offset++; + + m_current_byte |= next_bit << m_bit_offset; + m_bit_offset++; + + if (m_bit_offset > 7) { + TRY(m_stream->write({ &m_current_byte, sizeof(m_current_byte) })); + m_bit_offset = 0; + m_current_byte = 0; + } + } + + return {}; + } + + virtual bool is_eof() const override + { + return true; + } + + virtual bool is_open() const override + { + return m_stream->is_open(); + } + + virtual void close() override + { + } + + size_t bit_offset() const + { + return m_bit_offset; + } + + ErrorOr align_to_byte_boundary() + { + if (m_bit_offset == 0) + return {}; + + TRY(write_bits(0u, 8 - m_bit_offset)); + VERIFY(m_bit_offset == 0); + return {}; + } + +private: + LittleEndianOutputBitStream(Handle stream) + : m_stream(move(stream)) + { + } + + Handle m_stream; + u8 m_current_byte { 0 }; + size_t m_bit_offset { 0 }; +}; + }