Class: Omnizip::Algorithms::Zstandard

Inherits:
Omnizip::Algorithm show all
Defined in:
lib/omnizip/algorithms/zstandard.rb,
lib/omnizip/algorithms/zstandard/fse.rb,
lib/omnizip/algorithms/zstandard/ldm.rb,
lib/omnizip/algorithms/zstandard/frame.rb,
lib/omnizip/algorithms/zstandard/xxhash.rb,
lib/omnizip/algorithms/zstandard/decoder.rb,
lib/omnizip/algorithms/zstandard/encoder.rb,
lib/omnizip/algorithms/zstandard/huffman.rb,
lib/omnizip/algorithms/zstandard/literals.rb,
lib/omnizip/algorithms/zstandard/constants.rb,
lib/omnizip/algorithms/zstandard/fse/table.rb,
lib/omnizip/algorithms/zstandard/sequences.rb,
lib/omnizip/algorithms/zstandard/dictionary.rb,
lib/omnizip/algorithms/zstandard/frame/block.rb,
lib/omnizip/algorithms/zstandard/fse/encoder.rb,
lib/omnizip/algorithms/zstandard/frame/header.rb,
lib/omnizip/algorithms/zstandard/match_finder.rb,
lib/omnizip/algorithms/zstandard/fse/bitstream.rb,
lib/omnizip/algorithms/zstandard/fse/interleaved.rb,
lib/omnizip/algorithms/zstandard/huffman_encoder.rb,
lib/omnizip/algorithms/zstandard/literals_encoder.rb,
lib/omnizip/algorithms/zstandard/sequences_encoder.rb,
lib/omnizip/algorithms/zstandard/fse/table_description.rb

Overview

Zstandard compression algorithm

Zstandard (or Zstd) is a fast lossless compression algorithm developed by Facebook (now Meta). It provides:

  • Excellent compression ratios comparable to zlib/deflate
  • Very fast compression and decompression speeds
  • Wide range of compression levels (1-22)
  • Dictionary support for small data compression
  • Streaming and frame modes

This implementation uses the zstd-ruby gem which provides Ruby bindings to the official Zstandard C library. This ensures compatibility with the reference implementation and excellent performance.

Zstandard is particularly effective for:

  • Real-time compression needs
  • Network protocol compression
  • Database compression
  • Log file compression
  • General-purpose compression with speed priority

Defined Under Namespace

Modules: Constants, FSE, Frame, HuffmanEncoder, LiteralsEncoder, MatchFinder, SequencesEncoder, XXHash64 Classes: Decoder, Dictionary, Encoder, Huffman, HuffmanTableReader, LdmHashTable, LiteralsDecoder, SequenceExecutor, SequencesDecoder

Instance Attribute Summary

Attributes inherited from Omnizip::Algorithm

#filter, #options

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Omnizip::Algorithm

compress, decompress, inherited, #initialize, #with_filter

Constructor Details

This class inherits a constructor from Omnizip::Algorithm

Class Method Details

.compress_with_dict(data, dict, **options) ⇒ String

Class-level convenience mirrors of the dictionary API.

Returns:

  • (String) —

    compressed frame / decompressed plaintext



139
140
141
142
143
144
145
146
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 139

def self.compress_with_dict(data, dict, **options)
  output = StringIO.new
  output.set_encoding(Encoding::BINARY)
  new(options).compress_with_dict(
    StringIO.new(data.to_s.b), output, dict, options
  )
  output.string
end

.decompress_with_dict(data, dict) ⇒ Object 



148
149
150
151
152
153
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 148

def self.decompress_with_dict(data, dict)
  output = StringIO.new
  output.set_encoding(Encoding::BINARY)
  new.decompress_with_dict(StringIO.new(data.to_s.b), output, dict)
  output.string
end

.metadata ⇒ AlgorithmMetadata

Get algorithm metadata

Returns:

  • (AlgorithmMetadata) —

    Algorithm information



73
74
75
76
77
78
79
80
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 73

def self.metadata
  Models::AlgorithmMetadata.new.tap do |meta|
    meta.name = "zstandard"
    meta.description = "Zstandard fast compression with " \
                       "excellent ratios"
    meta.version = "1.0.0"
  end
end

Instance Method Details

#compress(input_stream, output_stream, options = nil) ⇒ void

This method returns an undefined value.

Compress data using Zstandard algorithm

Parameters:

  • input_stream (IO) —

    Input stream to compress

  • output_stream (IO) —

    Output stream for compressed data

  • options (Models::CompressionOptions) (defaults to: nil) —

    Compression options



88
89
90
91
92
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 88

def compress(input_stream, output_stream, options = nil)
  input_data = input_stream.read
  encoder = Encoder.new(output_stream, build_encoder_options(options))
  encoder.encode_stream(input_data)
end

#compress_with_dict(input_stream, output_stream, dict, options = {}) ⇒ void

This method returns an undefined value.

Compress data primed with a dictionary prefix: the dictionary content acts as shared history the match finder can reference, dramatically improving ratios on small inputs. The resulting frame carries the dictionary's ID and requires decompress_with_dict to decode.

Parameters:

  • input_stream (IO) —

    plaintext

  • output_stream (IO) —

    compressed frame

  • dict (Dictionary)
  • options (Hash) (defaults to: {}) —

    :level, :checksum



118
119
120
121
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 118

def compress_with_dict(input_stream, output_stream, dict, options = {})
  encoder = Encoder.new(output_stream, build_encoder_options(options))
  encoder.encode_stream_with_dict(input_stream.read, dict)
end

#decompress(input_stream, output_stream, _options = nil) ⇒ void

This method returns an undefined value.

Decompress Zstandard-compressed data

Parameters:

  • input_stream (IO) —

    Input stream of compressed data

  • output_stream (IO) —

    Output stream for decompressed data

  • options (Models::CompressionOptions) —

    Decompression options



100
101
102
103
104
105
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 100

def decompress(input_stream, output_stream, _options = nil)
  output_stream.set_encoding(Encoding::BINARY)
  decoder = Decoder.new(input_stream)
  decompressed = decoder.decode_stream
  output_stream.write(decompressed)
end

#decompress_with_dict(input_stream, output_stream, dict) ⇒ void

This method returns an undefined value.

Decompress a frame produced by compress_with_dict. The frame's dictionary ID is verified against dict before decoding.

Parameters:

  • input_stream (IO) —

    compressed frame

  • output_stream (IO) —

    plaintext

  • dict (Dictionary) 


130
131
132
133
134
 
# File 'lib/omnizip/algorithms/zstandard.rb', line 130

def decompress_with_dict(input_stream, output_stream, dict)
  output_stream.set_encoding(Encoding::BINARY)
  decoder = Decoder.new(input_stream)
  output_stream.write(decoder.decode_stream_with_dict(dict))
end