Struct StreamingEncoder 

pub struct StreamingEncoder<W: Write, M: Matcher = MatchGeneratorDriver> { /* private fields */ }

Incremental frame encoder that implements Write.

Data can be provided with multiple write() calls. Full blocks are compressed automatically, flush() emits the currently buffered partial block as non-last, and finish() closes the frame and returns the wrapped writer.

Implementations

impl<W: Write> StreamingEncoder<W, MatchGeneratorDriver>

pub fn new(drain: W, compression_level: CompressionLevel) -> Self

Creates a streaming encoder backed by the default match generator.

The encoder writes compressed bytes into drain and applies compression_level to all subsequently written blocks.

pub fn set_parameters( &mut self, params: &CompressionParameters, ) -> Result<(), Error>

Configure fine-grained compression parameters (#27): resets the level to the parameters’ level and installs the per-knob overrides (window / hash / chain / search logs, strategy, long-distance matching) applied at the next frame. Mirrors [FrameCompressor::set_parameters]. Must be called before the first write. Only the built-in MatchGeneratorDriver exposes the override knobs, so this lives on the default-matcher impl.

impl<W: Write, M: Matcher> StreamingEncoder<W, M>

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

Creates a streaming encoder with an explicitly provided matcher implementation.

This constructor is primarily intended for tests and advanced callers that need custom match-window behavior.

pub fn set_target_block_size( &mut self, target: Option<u32>, ) -> Result<(), Error>

Set an upper bound on each physical block’s payload (semantics of upstream ZSTD_c_targetCBlockSize): every block carries at most target payload bytes, +3-byte block header on the wire — the upstream knob is likewise a convergence target for block sizing, not a cap on header-inclusive wire bytes. Clamped to [MIN_TARGET_BLOCK_SIZE, MAX_BLOCK_SIZE]; mirrors FrameCompressor::set_target_block_size. Must be set before the first write.

pub fn set_content_checksum(&mut self, emit: bool) -> Result<(), Error>

Enable or disable the trailing XXH64 content checksum (upstream ZSTD_c_checksumFlag). Default false, matching the upstream library default (ZSTD_c_checksumFlag = 0). Must be called before the first write; once the frame header is emitted the flag is fixed, so a late change returns an error rather than producing a header/trailer mismatch. Without the hash feature no checksum is emitted regardless.

pub fn set_magicless(&mut self, magicless: bool) -> Result<(), Error>

Enable or disable magicless frame format (ZSTD_f_zstd1_magicless).

When set to true, the frame header serialized by this encoder omits the 4-byte magic number prefix. Must be called BEFORE the first write call; calling it after the frame header has already been emitted returns an error so the caller can’t be misled into thinking they produced a magicless stream.

pub fn set_pledged_content_size(&mut self, size: u64) -> Result<(), Error>

Pledge the total uncompressed content size for this frame.

When set, the frame header will include a Frame_Content_Size field. This enables decoders to pre-allocate output buffers. The pledged size is also forwarded as a source-size hint to the matcher so small inputs can use smaller matching tables.

Must be called before the first write call; calling it after the frame header has already been emitted returns an error.

pub fn set_content_size_flag(&mut self, emit: bool) -> Result<(), Error>

Control whether the pledged size is written into the header’s Frame_Content_Size field (upstream ZSTD_c_contentSizeFlag, default on). With the flag off the header omits the field, but a pledge set via set_pledged_content_size is still enforced against the bytes actually written. Must be called before the first write.

pub fn set_source_size_hint(&mut self, size: u64) -> Result<(), Error>

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

Unlike set_pledged_content_size, this does not enforce that exactly size bytes are written; it may reduce matcher tables, advertised frame window, and block sizing for small inputs. Must be called before the first write.

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

Attach a serialized dictionary blob to the frame (donor ZSTD_CCtx_loadDictionary on a streaming context). The dictionary primes the match-finder and seeds the first block’s entropy tables + repeat offsets, and its ID is written into the frame header. Must be called before the first write; the parsed dictionary must have a non-zero ID and non-zero repeat offsets.

pub fn set_dictionary_id_flag(&mut self, emit: bool) -> Result<(), Error>

Whether the frame header records the dictionary ID when a dictionary is attached (upstream ZSTD_c_dictIDFlag semantics; default true). Mirrors [FrameCompressor::set_dictionary_id_flag]. Decoders can still decode such frames by supplying the dictionary explicitly.

pub fn set_encoder_dictionary( &mut self, dict: EncoderDictionary, ) -> Result<(), Error>

Attach an already-parsed EncoderDictionary to the frame. See set_dictionary_from_bytes; must be called before the first write.

pub fn get_ref(&self) -> &W

Returns an immutable reference to the wrapped output drain.

The drain remains available for the encoder lifetime; finish consumes the encoder and returns ownership of the drain.

pub fn heap_size(&self) -> usize

Total heap bytes this encoder’s allocations hold, excluding the inline struct and the drain W (whose footprint the owner can measure through get_ref): match-finder tables / history / recycled buffers, retained Huffman tables, the staging pending / encoded_scratch buffers, the retained dictionary content, and the cached dictionary entropy tables. Mirrors FrameCompressor::heap_size so a context can report its true footprint through ZSTD_sizeof_CCtx.

pub fn get_mut(&mut self) -> &mut W

Returns a mutable reference to the wrapped output drain.

It is inadvisable to directly write to the underlying writer, as doing so would corrupt the zstd frame being assembled by the encoder.

The drain remains available for the encoder lifetime; finish consumes the encoder and returns ownership of the drain.

pub fn finish(self) -> Result<W, Error>

Finalizes the current zstd frame and returns the wrapped output drain.

If no payload was written yet, this still emits a valid empty frame. Calling this method consumes the encoder.

Trait Implementations

impl<W: Write, M: Matcher> Write for StreamingEncoder<W, M>

fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Error>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.