cabriolet 0.1.0

data/lib/cabriolet/huffman/encoder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module Huffman
+    # Encoder encodes symbols using Huffman codes for compression
+    class Encoder
+      # Maximum code length supported
+      MAX_BITS = 16
+
+      # Build Huffman codes from code lengths (RFC 1951 algorithm)
+      #
+      # This generates the actual Huffman code values from code lengths.
+      # The algorithm ensures canonical Huffman codes where codes of the
+      # same length are assigned sequentially.
+      #
+      # @param lengths [Array<Integer>] Code lengths for each symbol
+      # @param num_symbols [Integer] Number of symbols
+      # @return [Hash] Hash mapping symbol to {code: value, bits: length}
+      def self.build_codes(lengths, num_symbols)
+        # Count the number of codes for each length
+        bl_count = Array.new(MAX_BITS + 1, 0)
+        lengths[0, num_symbols].each do |len|
+          bl_count[len] += 1 if len.positive?
+        end
+
+        # Find the numerical value of the smallest code for each length
+        code = 0
+        bl_count[0] = 0
+        next_code = Array.new(MAX_BITS + 1, 0)
+
+        (1..MAX_BITS).each do |bits|
+          code = (code + bl_count[bits - 1]) << 1
+          next_code[bits] = code
+        end
+
+        # Assign codes to symbols
+        codes = {}
+        num_symbols.times do |symbol|
+          len = lengths[symbol]
+          next unless len.positive?
+
+          codes[symbol] = {
+            code: next_code[len],
+            bits: len,
+          }
+          next_code[len] += 1
+        end
+
+        codes
+      end
+
+      # Build fixed Huffman codes for DEFLATE (RFC 1951)
+      #
+      # @return [Hash] Hash with :literal and :distance code tables
+      def self.build_fixed_codes
+        # Fixed literal/length code lengths
+        literal_lengths = Array.new(288, 0)
+        (0...144).each { |i| literal_lengths[i] = 8 }
+        (144...256).each { |i| literal_lengths[i] = 9 }
+        (256...280).each { |i| literal_lengths[i] = 7 }
+        (280...288).each { |i| literal_lengths[i] = 8 }
+
+        # Fixed distance code lengths (all 5 bits)
+        distance_lengths = Array.new(32, 5)
+
+        {
+          literal: build_codes(literal_lengths, 288),
+          distance: build_codes(distance_lengths, 32),
+        }
+      end
+
+      # Encode a symbol using Huffman codes and write to bitstream
+      #
+      # Per RFC 1951 Section 3.1.1, Huffman codes are written LSB-first,
+      # so we must reverse the bits before writing to the bitstream.
+      #
+      # @param symbol [Integer] Symbol to encode
+      # @param codes [Hash] Code table mapping symbols to {code:, bits:}
+      # @param bitstream [Binary::BitstreamWriter] Output bitstream
+      # @return [void]
+      def self.encode_symbol(symbol, codes, bitstream)
+        entry = codes[symbol]
+        unless entry
+          raise Cabriolet::CompressionError,
+                "No code for symbol #{symbol}"
+        end
+
+        # Reverse bits for LSB-first writing per RFC 1951
+        reversed_code = reverse_bits(entry[:code], entry[:bits])
+        bitstream.write_bits(reversed_code, entry[:bits])
+      end
+
+      # Reverse bits for writing (some formats need reversed bit order)
+      #
+      # @param value [Integer] Value to reverse
+      # @param num_bits [Integer] Number of bits
+      # @return [Integer] Reversed value
+      def self.reverse_bits(value, num_bits)
+        result = 0
+        num_bits.times do
+          result = (result << 1) | (value & 1)
+          value >>= 1
+        end
+        result
+      end
+    end
+  end
+end

data/lib/cabriolet/huffman/tree.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module Huffman
+    # Tree builds Huffman decoding trees from code lengths
+    class Tree
+      attr_reader :lengths, :num_symbols, :table
+
+      # Maximum code length supported
+      MAX_BITS = 16
+
+      # Initialize a new Huffman tree
+      #
+      # @param lengths [Array<Integer>] Code lengths for each symbol
+      # @param num_symbols [Integer] Number of symbols
+      def initialize(lengths, num_symbols)
+        @lengths = lengths
+        @num_symbols = num_symbols
+        @table = nil
+      end
+
+      # Build the fast decode table from code lengths
+      #
+      # This implements a canonical Huffman decoding table based on
+      # the algorithm from libmspack (readhuff.h make_decode_table).
+      # The table has two levels:
+      # 1. Direct lookup for codes <= table_bits length
+      # 2. Linked entries for longer codes
+      #
+      # @param table_bits [Integer] Number of bits for table lookup (typically 6-12)
+      # @return [Boolean] true if successful, false on error
+      def build_table(table_bits)
+        # Allocate table: (1 << table_bits) entries for direct lookup
+        # Plus space for longer codes (up to num_symbols * 2)
+        table_size = (1 << table_bits) + (num_symbols * 2)
+        @table = Array.new(table_size, 0xFFFF)
+
+        pos = 0
+        table_mask = 1 << table_bits
+        bit_mask = table_mask >> 1
+
+        # Fill entries for codes short enough for direct mapping (LSB ordering)
+        (1..table_bits).each do |bit_num|
+          (0...num_symbols).each do |sym|
+            next unless lengths[sym] == bit_num
+
+            # Reverse the significant bits for LSB ordering
+            fill = lengths[sym]
+            reverse = pos >> (table_bits - fill)
+            leaf = 0
+            fill.times do
+              leaf <<= 1
+              leaf |= reverse & 1
+              reverse >>= 1
+            end
+
+            pos += bit_mask
+            return false if pos > table_mask
+
+            # Fill all possible lookups of this symbol
+            fill = bit_mask
+            next_symbol = 1 << bit_num
+            while fill.positive?
+              @table[leaf] = sym
+              leaf += next_symbol
+              fill -= 1
+            end
+          end
+          bit_mask >>= 1
+        end
+
+        # Exit with success if table is complete
+        return true if pos == table_mask
+
+        # Mark remaining entries as unused
+        (pos...table_mask).each do |sym_idx|
+          reverse = sym_idx
+          leaf = 0
+          fill = table_bits
+          fill.times do
+            leaf <<= 1
+            leaf |= reverse & 1
+            reverse >>= 1
+          end
+          @table[leaf] = 0xFFFF
+        end
+
+        # next_symbol = base of allocation for long codes
+        next_symbol = [(table_mask >> 1), num_symbols].max
+
+        # Process longer codes (table_bits + 1 to MAX_BITS)
+        pos <<= 16
+        table_mask <<= 16
+        bit_mask = 1 << 15
+
+        ((table_bits + 1)..MAX_BITS).each do |bit_num|
+          (0...num_symbols).each do |sym|
+            next unless lengths[sym] == bit_num
+
+            return false if pos >= table_mask
+
+            # leaf = the first table_bits of the code, reversed (LSB)
+            reverse = pos >> 16
+            leaf = 0
+            fill = table_bits
+            fill.times do
+              leaf <<= 1
+              leaf |= reverse & 1
+              reverse >>= 1
+            end
+
+            # Build the tree path for this long code
+            (0...(bit_num - table_bits)).each do |fill_idx|
+              # If this path hasn't been taken yet, allocate two entries
+              if @table[leaf] == 0xFFFF
+                @table[next_symbol << 1] = 0xFFFF
+                @table[(next_symbol << 1) + 1] = 0xFFFF
+                @table[leaf] = next_symbol
+                next_symbol += 1
+              end
+
+              # Follow the path and select either left or right for next bit
+              leaf = @table[leaf] << 1
+              leaf += 1 if (pos >> (15 - fill_idx)).anybits?(1)
+            end
+
+            @table[leaf] = sym
+            pos += bit_mask
+          end
+          bit_mask >>= 1
+        end
+
+        # Full table?
+        pos == table_mask
+      end
+    end
+  end
+end