Struct FrameCompressor 

pub struct FrameCompressor<R: Read, W: Write, M: Matcher> { /* private fields */ }

An interface for compressing arbitrary data with the ZStandard compression algorithm.

FrameCompressor will generally be used by:

1. Initializing a compressor by providing a buffer of data using FrameCompressor::new()
2. Starting compression and writing that compression into a vec using FrameCompressor::begin

Examples

use structured_zstd::encoding::{FrameCompressor, CompressionLevel};
let mock_data: &[_] = &[0x1, 0x2, 0x3, 0x4];
let mut output = std::vec::Vec::new();
// Initialize a compressor.
let mut compressor = FrameCompressor::new(CompressionLevel::Uncompressed);
compressor.set_source(mock_data);
compressor.set_drain(&mut output);

// `compress` writes the compressed output into the provided buffer.
compressor.compress();

Implementations

impl<R: Read, W: Write> FrameCompressor<R, W, MatchGeneratorDriver>

pub fn new(compression_level: CompressionLevel) -> Self

Create a new FrameCompressor

impl<R: Read, W: Write, M: Matcher> FrameCompressor<R, W, M>

pub fn new_with_matcher(matcher: M, compression_level: CompressionLevel) -> Self

Create a new FrameCompressor with a custom matching algorithm implementation

pub fn set_magicless(&mut self, magicless: bool)

Enable or disable magicless frame format (ZSTD_f_zstd1_magicless).

When set to true, emitted frames omit the 4-byte magic number prefix. The matching decoder must be configured to expect a magicless stream — wire-format only round-trips with a magicless-aware decoder.

pub fn set_source(&mut self, uncompressed_data: R) -> Option<R>

Before calling FrameCompressor::compress you need to set the source.

This is the data that is compressed and written into the drain.

pub fn set_drain(&mut self, compressed_data: W) -> Option<W>

Before calling FrameCompressor::compress you need to set the drain.

As the compressor compresses data, the drain serves as a place for the output to be writte.

pub fn set_source_size_hint(&mut self, size: u64)

Provide a hint about the total uncompressed size for the next frame.

When set, the encoder selects smaller hash tables and windows for small inputs, matching the C zstd source-size-class behavior.

This hint applies only to frame payload bytes (size). Dictionary history is primed separately and does not inflate the hinted size or advertised frame window. Must be called before compress.

pub fn compress(&mut self)

Compress the uncompressed data from the provided source as one Zstd frame and write it to the provided drain

This will repeatedly call Read::read on the source to fill up blocks until the source returns 0 on the read call. All compressed blocks are buffered in memory so that the frame header can include the Frame_Content_Size field (which requires knowing the total uncompressed size). The entire frame — header, blocks, and optional checksum — is then written to the drain at the end. This means peak memory usage is O(compressed_size).

To avoid endlessly encoding from a potentially endless source (like a network socket) you can use the Read::take function

pub fn last_frame_emit_info(&self) -> Option<&FrameEmitInfo>

Available on crate feature lsm only.

Layout of the most recently emitted frame.

Returns None if compress has not been called yet on this compressor. After a successful compress() the returned FrameEmitInfo describes the frame header range, every emitted block’s offset / size / type, and the optional trailing content-checksum range — all in frame-absolute byte offsets matching the bytes written to the drain.

Behind the lsm Cargo feature.

pub fn enable_per_block_checksums(&mut self)

Available on crate features lsm and hash only.

Opt in to per-block XXH64 checksum computation during compress. Default off; zero cost when disabled. The captured digests are accessible via last_frame_block_checksums.

One checksum is emitted per physical FrameBlock written to the drain: 1:1 cardinality with last_frame_emit_info’s blocks vector. On the post-split optimization path (Level 16-22 with large window) the per-partition decompressed range is hashed inside the partition loop so the digest count still matches the emitted block count. The decoder collects per-physical-block digests on the same granularity, so element-wise equality holds round-trip.

Behind all(feature = "lsm", feature = "hash") — the XXH64 primitive lives behind the hash feature, so this method only compiles when both are enabled.

pub fn last_frame_block_checksums(&self) -> Option<&[u32]>

Available on crate features lsm and hash only.

Per-block XXH64 (low 32 bits) digests captured during the most recent compress() call. None unless enable_per_block_checksums was called before compress().

Behind all(feature = "lsm", feature = "hash").

pub fn source_mut(&mut self) -> Option<&mut R>

Get a mutable reference to the source

pub fn drain_mut(&mut self) -> Option<&mut W>

Get a mutable reference to the drain

pub fn source(&self) -> Option<&R>

Get a reference to the source

pub fn drain(&self) -> Option<&W>

Get a reference to the drain

pub fn take_source(&mut self) -> Option<R>

Retrieve the source

pub fn take_drain(&mut self) -> Option<W>

Retrieve the drain

pub fn replace_matcher(&mut self, match_generator: M) -> M

Before calling FrameCompressor::compress you can replace the matcher

pub fn set_compression_level( &mut self, compression_level: CompressionLevel, ) -> CompressionLevel

Before calling FrameCompressor::compress you can replace the compression level

pub fn compression_level(&self) -> CompressionLevel

Get the current compression level

pub fn set_dictionary( &mut self, dictionary: Dictionary, ) -> Result<Option<Dictionary>, DictionaryDecodeError>

Attach a pre-parsed dictionary to be used for subsequent compressions.

In compressed modes, the dictionary id is written only when the active matcher supports dictionary priming. Uncompressed mode and non-priming matchers ignore the attached dictionary at encode time.

pub fn set_dictionary_from_bytes( &mut self, raw_dictionary: &[u8], ) -> Result<Option<Dictionary>, DictionaryDecodeError>

Parse and attach a serialized dictionary blob.

pub fn clear_dictionary(&mut self) -> Option<Dictionary>

Remove the attached dictionary.