Struct EncoderSessionOwned

Source

pub struct EncoderSessionOwned<D = PreparedDictionary> { /* private fields */ }

Expand description

One incremental frame that owns its compressor.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut session = Compressor::new(Default::default())?.into_session(Default::default());
let mut out = [0u8; 64];
assert_eq!(session.process(b"x", &mut out, Operation::End)?.status, EncoderStatus::Finished);
let compressor = session.into_compressor();
assert!(compressor.retained_bytes() > 0);

A session started with Compressor::into_session_with_dictionary also owns its dictionary, of any type D that borrows as a PreparedDictionary (the dictionary itself, a Box or an Arc of one).

Implementations§

Source §

impl<D: AsRef<PreparedDictionary>> EncoderSessionOwned<D>

Source

pub fn process( &mut self, input: &[u8], output: &mut [u8], operation: Operation, ) -> Result<Progress, EncodeError>

Moves the frame forward by one step: takes what it can from input, writes what it can into output, and reports exactly how much of each it moved and what it needs next.

An Operation::End that returns EncoderStatus::NeedsOutput must be repeated until it reports EncoderStatus::Finished; afterwards calls are idempotent.

§Errors

EncodeError::InputSizeMismatch when the input contradicts a declared size: when more arrives than was declared, when the frame ends short of it, or when a first Operation::End call carries any other length. EncodeError::InvalidState after a failure. A failed session encodes nothing further.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut encoder = Compressor::new(Default::default())?;
let mut session = encoder.start(Default::default());
let mut out = [0u8; 64];
let progress = session.process(b"", &mut out, Operation::End)?;
assert_eq!(progress.status, EncoderStatus::Finished);
assert!(progress.produced > 0);

Source

pub fn process_uninit( &mut self, input: &[u8], output: &mut [MaybeUninit<u8>], operation: Operation, ) -> Result<Progress, EncodeError>

Self::process into uninitialized memory, such as Vec::spare_capacity_mut, without a temporary buffer.

It produces the same bytes, consumed and produced counts, statuses and errors as Self::process, and calls of the two may be mixed on one frame. On success exactly output[..produced] holds compressed bytes. As with Self::process, the encoder may also have written scratch bytes after them, so treat only output[..produced] as initialized, and none of output after an error.

§Errors

As Self::process.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut encoder = Compressor::new(Default::default())?;
let mut session = encoder.start(Default::default());
let mut out: Vec<u8> = Vec::with_capacity(64);
let progress = session.process_uninit(b"data", out.spare_capacity_mut(), Operation::End)?;
// SAFETY: `process_uninit` initialized the first `produced` bytes.
unsafe { out.set_len(progress.produced) };
assert_eq!(progress.status, EncoderStatus::Finished);

Source

pub fn flush(&mut self, output: &mut [u8]) -> Result<Progress, EncodeError>

Makes everything accepted so far decodable, without taking input.

§Errors

As Self::process.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut encoder = Compressor::new(Default::default())?;
let mut session = encoder.start(Default::default());
let mut out = [0u8; 256];
session.process(b"flushed payload", &mut out, Operation::Continue)?;
let progress = session.flush(&mut out)?;
assert_eq!(progress.status, EncoderStatus::NeedsInput);
assert!(progress.produced > 0);

Source

pub fn finish(&mut self, output: &mut [u8]) -> Result<Progress, EncodeError>

Ends the frame, without taking input.

§Errors

As Self::process.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut encoder = Compressor::new(Default::default())?;
let mut session = encoder.start(Default::default());
let mut out = [0u8; 256];
session.process(b"payload", &mut out, Operation::Continue)?;
assert_eq!(session.finish(&mut out)?.status, EncoderStatus::Finished);

Source

pub fn is_finished(&self) -> bool

Whether the frame has been completed and delivered.

Source

pub fn reinit(&mut self, stream: StreamConfig)

Starts a new frame on the same compressor.

§Examples

use mzstd::{Compressor, EncoderStatus, Operation};

let mut session = Compressor::new(Default::default())?.into_session(Default::default());
let mut out = [0u8; 64];
session.process(b"one", &mut out, Operation::End)?;
session.reinit(Default::default());
assert!(!session.is_finished());

Source

pub fn into_parts(self) -> (Compressor, Option<D>)

Returns the compressor and the dictionary, if any, abandoning an unfinished frame.

§Examples

use mzstd::dictionary::DictionaryBuilder;
use mzstd::Compressor;

let dictionary = DictionaryBuilder::new(b"history").build()?;
let session = Compressor::default().into_session_with_dictionary(dictionary, Default::default())?;
let (_compressor, dictionary) = session.into_parts();
assert_eq!(dictionary.map(|dictionary| dictionary.as_bytes().len()), Some(7));