Struct StreamingEncoder 

pub struct StreamingEncoder<W: Write, M: Matcher = MatchGeneratorDriver, C: BorrowMut<CompressionContext<M>> = CompressionContext<M>> { /* 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.

One encoder writes one frame into the drain it owns, through a CompressionContext it owns (new) or borrows (with_context). Borrowing is how frame after frame is compressed with the same settings, dictionary and match-finder allocations: the context outlives each encoder and is ready for the next frame once finish returns.

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.

impl<W: Write, C: BorrowMut<CompressionContext>> StreamingEncoder<W, MatchGeneratorDriver, C>

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

Configure fine-grained compression parameters; see CompressionContext::set_parameters. Must be called before the first write.

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.

impl<W: Write, M: Matcher, C: BorrowMut<CompressionContext<M>>> StreamingEncoder<W, M, C>

pub fn with_context(drain: W, context: C) -> Self

Write one frame into drain through context: owned, or borrowed from a caller that keeps it for the next frame with every setting, the dictionary and the allocations it has.

Examples

use std::io::Write;
use structured_zstd::encoding::{CompressionContext, CompressionLevel, StreamingEncoder};

let mut context = CompressionContext::new(CompressionLevel::Default);
for payload in [&b"first frame"[..], b"second frame"] {
    let mut encoder = StreamingEncoder::with_context(Vec::new(), &mut context);
    encoder.write_all(payload).unwrap();
    let frame = encoder.finish().unwrap();
    assert!(!frame.is_empty());
}

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

Bound each block’s payload; see CompressionContext::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; see CompressionContext::set_content_checksum. Must be called before the first write.

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

Enable or disable the magicless frame format; see CompressionContext::set_magicless. Must be called before the first write.

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

Pledge the total uncompressed content size of the frame; see CompressionContext::set_pledged_content_size. Must be called before the first write.

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

Control whether a pledged size reaches the header; see CompressionContext::set_content_size_flag. Must be called before the first write.

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

Provide an advisory size for the frame; see CompressionContext::set_source_size_hint. Must be called before the first write.

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

Attach a dictionary blob to the frame; see CompressionContext::set_dictionary_from_bytes. Must be called before the first write.

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

Whether the header records the dictionary ID; see CompressionContext::set_dictionary_id_flag. Must be set before the first write.

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

Attach an already-parsed EncoderDictionary to the frame; see CompressionContext::set_encoder_dictionary. 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); see CompressionContext::heap_size.

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; a borrowed context is then ready for the next frame, also when this fails: the frame goes with the drain (see CompressionContext::abandon_frame).

Trait Implementations

impl<W: Write, M: Matcher, C: BorrowMut<CompressionContext<M>>> Drop for StreamingEncoder<W, M, C>

The frame belongs to the drain this encoder writes into: an encoder that goes without finishing it (dropped mid-frame, or a finish that failed) takes it along, so a borrowed context starts the next encoder’s frame afresh instead of continuing this one into another drain.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<W: Write, M: Matcher, C: BorrowMut<CompressionContext<M>>> Write for StreamingEncoder<W, M, C>

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.