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_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 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.