Struct EncoderSession

Source

pub struct EncoderSession<'c> { /* private fields */ }

Expand description

One incremental frame borrowing its compressor.

Dropping a session before it finishes abandons the frame; the compressor is left ready for the next one either way.

§Examples

use mopenzl::{Compressor, Decompressor, EncoderStatus, InputSize, Operation};

let mut encoder = Compressor::default();
let payload = b"a payload compressed one chunk at a time".repeat(10);
let mut compressed = Vec::new();
let mut buffer = [0u8; 64];
let mut input = payload.as_slice();
{
    let mut session = encoder.start(InputSize::Exact(payload.len() as u64).into());
    loop {
        let progress = session.process(input, &mut buffer, Operation::End)?;
        input = &input[progress.consumed..];
        compressed.extend_from_slice(&buffer[..progress.produced]);
        if progress.status == EncoderStatus::Finished {
            break;
        }
    }
}
assert_eq!(compressed, encoder.compress(&payload)?);
assert_eq!(Decompressor::default().decompress(&compressed)?, payload);

Implementations§

Source §

impl<'c> EncoderSession<'c>

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, or when the frame ends short of it. EncodeError::InvalidState after a failure. A failed session encodes nothing further.

§Examples

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

let mut encoder = Compressor::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 or zeroing.

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] is initialized; nothing after it is written.

§Errors

As Self::process.

§Examples

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

let mut encoder = Compressor::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);
assert_eq!(out, Compressor::default().compress(b"data")?);

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 mopenzl::{Compressor, EncoderStatus, InputSize, Operation};

let mut encoder = Compressor::default();
let mut session = encoder.start(InputSize::Exact(30).into());
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 mopenzl::{Compressor, EncoderStatus, Operation};

let mut encoder = Compressor::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);