Struct Inflater 

pub struct Inflater { /* private fields */ }

A streaming raw DEFLATE decoder (RFC 1951).

Push compressed input and pull decompressed output through buffers you own. Memory is fixed when the inflater is built: the decode tables (about 11 KiB) and a history window of 2^window_bits bytes. Every limit in Limits is checked before output is written.

Examples

use compress_lib::deflate::{Inflater, Status};

// "hello" compressed with fixed Huffman codes.
let compressed = [0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00];
let mut inflater = Inflater::new();
let mut out = [0u8; 64];
let p = inflater.finish(&compressed, &mut out)?;
assert_eq!(p.status, Status::Done);
assert_eq!(&out[..p.produced], b"hello");

Implementations

impl Inflater

pub fn new() -> Self

An inflater with window bits 15 and the default Limits.

Examples

let inflater = compress_lib::deflate::Inflater::new();
assert_eq!(inflater.window_bits(), 15);

pub fn with_window_bits(self, bits: u8) -> Result<Self, Error>

Sets the window size to 2^bits bytes, 8 to 15. A back-reference further than the window is DistanceTooFar (RFC 7692 negotiates these sizes). Memory: the window shrinks with it.

Errors

ErrorKind::InvalidWindowBits outside 8 to 15.

Examples

use compress_lib::deflate::Inflater;

let inflater = Inflater::new().with_window_bits(9)?;
assert_eq!(inflater.window_bits(), 9);
assert!(Inflater::new().with_window_bits(16).is_err());

pub fn with_limits(self, limits: Limits) -> Self

Sets the limits checked while decoding.

Examples

use compress_lib::{Limits, deflate::Inflater};

let inflater = Inflater::new().with_limits(Limits::new().with_max_output(1 << 20));
assert_eq!(inflater.limits().max_output(), 1 << 20);

pub fn window_bits(&self) -> u8

The window size in bits.

Examples

assert_eq!(compress_lib::deflate::Inflater::new().window_bits(), 15);

pub fn limits(&self) -> Limits

The limits in force.

Examples

use compress_lib::{Limits, deflate::Inflater};

assert_eq!(Inflater::new().limits(), Limits::new());

pub fn is_done(&self) -> bool

true once the final block has ended.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
assert!(!inflater.is_done());
inflater.finish(&[0x03, 0x00], &mut [])?; // an empty stream
assert!(inflater.is_done());

pub fn total_in(&self) -> u64

Compressed bytes consumed since the inflater was built or reset.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
inflater.finish(&[0x03, 0x00], &mut [])?;
assert_eq!(inflater.total_in(), 2);

pub fn total_out(&self) -> u64

Decompressed bytes produced since the inflater was built or reset.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
let mut out = [0u8; 8];
inflater.finish(&[0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00], &mut out)?;
assert_eq!(inflater.total_out(), 5);

pub fn memory_in_use(&self) -> usize

Heap bytes this inflater holds: the tables and the window.

Examples

use compress_lib::deflate::Inflater;

let small = Inflater::new().with_window_bits(9)?;
assert!(small.memory_in_use() < Inflater::new().memory_in_use());

pub fn reset(&mut self)

Forgets the stream and its history, keeping the allocations, so the inflater can decode an unrelated stream.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
inflater.finish(&[0x03, 0x00], &mut [])?;
inflater.reset();
assert!(!inflater.is_done());
assert_eq!(inflater.total_in(), 0);

pub fn wipe(&mut self)

Zeroes the history window and the decode tables (which hold what the stream decoded and how it was coded), then resets the inflater for a new stream. For connections that carried secrets: call it before the inflater is dropped or reused. The allocations are kept.

The zeroing goes through core::hint::black_box so it is not removed as a dead store; without unsafe volatile writes that is a strong hint to the compiler, not a guarantee.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
let mut out = Vec::new();
inflater.finish_vec(&[0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00], &mut out)?;
inflater.wipe();
assert_eq!(inflater.total_out(), 0);

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

After Done, starts a new DEFLATE stream that keeps the window, so the next stream may refer back into this one. This is RFC 7692 context takeover after a message that ended with a final block.

Errors

ErrorKind::InvalidState before the current stream is done.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
let mut out = Vec::new();
inflater.finish_vec(&[0x03, 0x00], &mut out)?;
inflater.next_stream()?;
inflater.finish_vec(&[0x03, 0x00], &mut out)?;

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

Presets the history with dictionary (its last 2^window_bits bytes), for streams compressed with the same preset dictionary. Only before any input.

Errors

ErrorKind::InvalidState after input has been given.

Examples

use compress_lib::deflate::Inflater;

let mut inflater = Inflater::new();
inflater.set_dictionary(b"common prefix")?;

pub fn decompress( &mut self, input: &[u8], output: &mut [u8], ) -> Result<Progress, Error>

Decompresses as much of input into output as fits. More input may follow in later calls.

Returns how much input was consumed, how much output was produced, and the Status: NeedsInput (all input consumed, the stream goes on), NeedsOutput (output is full; call again with more room and the rest of the input), or Done (the final block ended; consumed stops at the stream’s last byte, so trailing data stays with the caller).

Errors

Any decoding error of ErrorKind, or OutputLimit / RatioLimit when a limit stops the stream. After an error every call returns the same error until reset.

Examples

use compress_lib::deflate::{Inflater, Status};

let compressed = [0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00];
let mut inflater = Inflater::new();
let mut out = Vec::new();
let mut buf = [0u8; 2]; // tiny on purpose
let mut input = &compressed[..];
loop {
    let p = inflater.decompress(input, &mut buf)?;
    input = &input[p.consumed..];
    out.extend_from_slice(&buf[..p.produced]);
    if p.status == Status::Done {
        break;
    }
}
assert_eq!(out, b"hello");

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

As decompress, with input the last of the stream: if the stream is unfinished once input runs out, the result is UnexpectedEnd (unless output was full first, which is NeedsOutput).

Errors

As decompress, plus ErrorKind::UnexpectedEnd.

Examples

use compress_lib::{ErrorKind, deflate::Inflater};

let truncated = [0xCB, 0x48, 0xCD];
let mut out = [0u8; 16];
let err = Inflater::new().finish(&truncated, &mut out).unwrap_err();
assert_eq!(err.kind(), ErrorKind::UnexpectedEnd);

pub fn decompress_vec( &mut self, input: &[u8], out: &mut Vec<u8>, ) -> Result<Progress, Error>

Decompresses input, appending to out, growing it as needed but never past the output cap. Growth doubles what this call has produced (at least 64 KiB at a time), so peak memory is at most 1.5 times max_output while a reallocation holds the old buffer and the new one. Returns NeedsInput or Done.

Errors

As decompress, plus ErrorKind::AllocationFailed when the vector cannot grow.

Examples

use compress_lib::deflate::{Inflater, Status};

let mut out = Vec::new();
let p = Inflater::new().decompress_vec(&[0xCB, 0x48, 0xCD, 0xC9, 0xC9, 0x07, 0x00], &mut out)?;
assert_eq!(p.status, Status::Done);
assert_eq!(out, b"hello");

pub fn finish_vec( &mut self, input: &[u8], out: &mut Vec<u8>, ) -> Result<Progress, Error>

As decompress_vec, with input the last of the stream: an unfinished stream is UnexpectedEnd.

Errors

As decompress_vec, plus ErrorKind::UnexpectedEnd.

Examples

use compress_lib::deflate::Inflater;

let mut out = Vec::new();
Inflater::new().finish_vec(&[0x03, 0x00], &mut out)?;
assert!(out.is_empty());

Trait Implementations

impl Debug for Inflater

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Inflater

fn default() -> Self

Returns the “default value” for a type.