omnizip 0.3.13 → 0.3.15

data/lib/omnizip/algorithms/zstandard/fse/bitstream.rb

@@ -24,160 +24,157 @@ module Omnizip
   module Algorithms
     class Zstandard
       module FSE
-        # FSE bitstream reader (RFC 8878 Section 4.1)
+        # Reverse-direction bit reader matching the zstd C reference
+        # `BIT_DStream` (lib/common/bitstream.h).
         #
-        # Reads FSE-encoded bitstreams which are read in reverse order
-        # (from end to beginning) according to RFC 8878.
+        # The bitstream is written forward by the encoder but read
+        # BACKWARDS: bytes are consumed from the last toward the first,
+        # and within each byte bits are consumed MSB-first. The reader
+        # keeps a 64-bit container (little-endian window onto 8 bytes)
+        # and takes bits from the high end after `bits_consumed`.
         #
-        # The bitstream is consumed from the end toward the beginning,
-        # with bits read from LSB to MSB within each byte.
+        # The last byte holds a 1 end-mark bit with 0-7 padding zero
+        # bits above it; the last byte can therefore never be 0x00.
         class BitStream
-          # @return [String] The compressed data
-          attr_reader :data
+          MASK64 = 0xFFFFFFFFFFFFFFFF
 
-          # @return [Integer] Current bit position (from end)
-          attr_reader :bit_position
+          # Reload statuses mirroring C's BIT_DStream_status.
+          UNFINISHED = :unfinished
+          END_OF_BUFFER = :end_of_buffer
+          COMPLETED = :completed
+          OVERFLOW = :overflow
 
-          # Initialize bitstream with data
-          #
-          # @param data [String] The compressed bitstream data
+          attr_reader :data
+
+          # @param data [String] the full bitstream bytes (binary)
           def initialize(data)
-            @data = data.dup.force_encoding(Encoding::BINARY)
-            @bit_position = data.bytesize * 8
+            @data = data
+            n = data.bytesize
+            last = n.positive? ? data.getbyte(n - 1) : 0
+            end_mark = last.positive? ? 8 - Constants.highbit32(last) : 0
+
+            if n >= 8
+              @ptr = n - 8
+              @container = read_le64(@ptr)
+              @bits_consumed = end_mark
+            else
+              @ptr = 0
+              @container = 0
+              n.times { |i| @container |= data.getbyte(i) << (i * 8) }
+              @bits_consumed = end_mark + ((8 - n) * 8)
+            end
           end
 
-          # Read bits from the stream (in reverse order)
-          #
-          # Bits are read from LSB to MSB, starting from the end of the stream.
+          # Read `count` bits, first-read bit becoming the value's MSB
+          # (little-endian value semantics per RFC 8878 §4.1).
           #
-          # @param count [Integer] Number of bits to read
-          # @return [Integer] The read bits
+          # @param count [Integer] 0..32
+          # @return [Integer]
           def read_bits(count)
             return 0 if count.zero?
 
-            result = 0
-            count.times do |i|
-              bit = read_single_bit
-              result |= (bit << i)
-            end
-            result
+            shift_left = @bits_consumed & 63
+            shift_right = (64 - count) & 63
+            result = ((@container << shift_left) & MASK64) >> shift_right
+            @bits_consumed += count
+            result & ((1 << count) - 1)
           end
 
-          # Peek at bits without consuming them
-          #
-          # @param count [Integer] Number of bits to peek
-          # @return [Integer] The peeked bits
+          # Peek `count` bits without consuming.
           def peek_bits(count)
-            saved_position = @bit_position
+            saved_ptr = @ptr
+            saved_container = @container
+            saved_consumed = @bits_consumed
             result = read_bits(count)
-            @bit_position = saved_position
+            @ptr = saved_ptr
+            @container = saved_container
+            @bits_consumed = saved_consumed
             result
           end
 
-          # Check if bitstream is exhausted
-          #
-          # @return [Boolean]
-          def exhausted?
-            @bit_position <= 0
+          # Reload the container after enough bits have been consumed,
+          # mirroring C's BIT_reloadDStream.
+          def reload
+            return if @bits_consumed < 8
+
+            if @ptr >= 8
+              bytes_consumed = @bits_consumed >> 3
+              @ptr -= bytes_consumed
+              @ptr = 0 if @ptr.negative?
+              @bits_consumed &= 7
+              load_container
+            elsif @ptr.zero?
+              # No earlier bytes to load; leave the container as is.
+            else
+              nb_bytes = @bits_consumed >> 3
+              actual_bytes = [nb_bytes, @ptr].min
+              @ptr -= actual_bytes
+              @bits_consumed -= actual_bytes * 8
+              load_container
+            end
           end
 
-          # Get remaining bits
+          # Full reload that also reports the C reload status.
           #
-          # @return [Integer]
-          def remaining_bits
-            @bit_position
+          # @return [Symbol] one of UNFINISHED, END_OF_BUFFER, COMPLETED,
+          #   OVERFLOW
+          def reload_status
+            return OVERFLOW if @bits_consumed > 64
+
+            if @ptr >= 8
+              bytes_consumed = @bits_consumed >> 3
+              @ptr -= bytes_consumed
+              @ptr = 0 if @ptr.negative?
+              @bits_consumed &= 7
+              load_container
+              return UNFINISHED
+            end
+            return END_OF_BUFFER if @ptr.zero?
+
+            nb_bytes = @bits_consumed >> 3
+            actual_bytes = [nb_bytes, @ptr].min
+            @ptr -= actual_bytes
+            @bits_consumed -= actual_bytes * 8
+            load_container
+            actual_bytes < nb_bytes ? END_OF_BUFFER : UNFINISHED
           end
 
-          # Align to byte boundary (skip remaining bits in current byte)
+          # Skip to the next byte boundary (toward the stream start).
           def align_to_byte
-            @bit_position = ((@bit_position + 7) / 8) * 8
-          end
-
-          private
+            remainder = @bits_consumed % 8
+            return if remainder.zero?
 
-          # Read a single bit from the stream
-          #
-          # @return [Integer] 0 or 1
-          def read_single_bit
-            return 0 if @bit_position <= 0
-
-            @bit_position -= 1
-            byte_index = @bit_position / 8
-            bit_index = @bit_position % 8
-
-            return 0 if byte_index.negative? || byte_index >= @data.bytesize
-
-            byte = @data.getbyte(byte_index)
-            (byte >> bit_index) & 1
+            @bits_consumed += 8 - remainder
+            reload if @bits_consumed >= 8
           end
-        end
 
-        # Forward bitstream reader (for Huffman decoding)
-        #
-        # Reads bits in normal forward order from a starting position.
-        class ForwardBitStream
-          # @return [String] The compressed data
-          attr_reader :data
-
-          # @return [Integer] Current bit position
-          attr_reader :bit_position
-
-          # Initialize bitstream with data
-          #
-          # @param data [String] The compressed bitstream data
-          # @param start_byte [Integer] Starting byte position
-          def initialize(data, start_byte = 0)
-            @data = data.dup.force_encoding(Encoding::BINARY)
-            @bit_position = start_byte * 8
-          end
-
-          # Read bits from the stream (in forward order)
-          #
-          # Bits are read from MSB to LSB within each byte.
-          #
-          # @param count [Integer] Number of bits to read
-          # @return [Integer] The read bits
-          def read_bits(count)
-            return 0 if count.zero?
-
-            result = 0
-            count.times do
-              result = (result << 1) | read_single_bit
-            end
-            result
+          # Bits not yet consumed, counting from the end of the data.
+          def remaining_bits
+            total = @data.bytesize * 8
+            consumed = bits_consumed_so_far
+            total >= consumed ? total - consumed : 0
           end
 
-          # Check if bitstream is exhausted
-          #
-          # @return [Boolean]
           def exhausted?
-            @bit_position >= @data.bytesize * 8
-          end
-
-          # Get current byte position
-          #
-          # @return [Integer]
-          def byte_position
-            @bit_position / 8
+            remaining_bits.zero?
           end
 
           private
 
-          # Read a single bit from the stream
-          #
-          # @return [Integer] 0 or 1
-          def read_single_bit
-            return 0 if exhausted?
-
-            byte_index = @bit_position / 8
-            bit_index = 7 - (@bit_position % 8) # MSB first
-
-            @bit_position += 1
+          def bits_consumed_so_far
+            bytes_after_window = @data.bytesize - (@ptr + 8)
+            bytes_after_window = 0 if bytes_after_window.negative?
+            (bytes_after_window * 8) + @bits_consumed
+          end
 
-            return 0 if byte_index >= @data.bytesize
+          def read_le64(offset)
+            v = 0
+            8.times { |i| v |= @data.getbyte(offset + i) << (i * 8) }
+            v
+          end
 
-            byte = @data.getbyte(byte_index)
-            (byte >> bit_index) & 1
+          def load_container
+            @container = read_le64(@ptr)
           end
         end
       end