core:zlib

zlib compression and decompression.

A pure Wado port of zlib 1.3.1 (https://github.com/madler/zlib). This code is derived from the original zlib by Jean-loup Gailly and Mark Adler, and is licensed under the zlib License (https://github.com/madler/zlib/blob/develop/LICENSE).

Implements DEFLATE (RFC 1951) and gzip (RFC 1952) fully. RFC 1950 (zlib format) is supported except for preset dictionaries (FDICT); streams with FDICT set return ZlibError::PresetDictionaryNotSupported.

The decoder is annotated against the format specifications, whose text is kept under wado-compiler/ref/ (RFC 1950, RFC 1951, RFC 1952). Section references in the comments below point at those documents.

Features:

Adler-32 and CRC-32 checksums (with combine operations)
DEFLATE inflate (decompression) with dynamic/fixed Huffman and stored blocks
DEFLATE deflate (compression) with fixed and dynamic Huffman codes + LZ77
Compression levels 0-9 with strategy selection
zlib, gzip, and raw DEFLATE wrappers
Streaming DeflateStream / InflateStream API

All compression entry points share the same shape: the input buffer is required, and level and strategy default to Z_DEFAULT_COMPRESSION and Z_DEFAULT_STRATEGY respectively.

All decompression entry points take a non-negative max_output, default i32::MAX. Output that would pass it fails with ZlibError::OutputExceedsMax before it is written, so untrusted input cannot expand without bound.

Synopsis

let data: ByteList = b"wado wado wado wado";

// One call per container format; level and strategy default.
let compressed = zlib_compress(&data);  // RFC 1950
let smallest = zlib_compress(&data, Z_BEST_COMPRESSION);  // override the level
let gz = gzip_compress(&data);  // RFC 1952
let raw = deflate_raw(&data);  // no header or trailer

// `uncompress` tells zlib from gzip; the rest name the format they read.
assert uncompress(&compressed) matches { Ok(round) && round == data };
assert inflate_zlib(&smallest) matches { Ok(round) && round == data };
assert inflate_gzip(&gz) matches { Ok(round) && round == data };
assert inflate_raw(&raw) matches { Ok(round) && round == data };

// A stream, for input arriving in pieces.
let mut stream = DeflateStream::new(Z_DEFAULT_COMPRESSION);
stream.update(&(b"wado wado " as ByteList));
stream.update(&(b"wado wado" as ByteList));
assert uncompress(&stream.finish()) matches { Ok(round) && round == data };

Globals

`pub global Z_OK: i32`

`pub global Z_STREAM_END: i32`

`pub global Z_ERRNO: i32`

`pub global Z_STREAM_ERROR: i32`

`pub global Z_DATA_ERROR: i32`

`pub global Z_MEM_ERROR: i32`

`pub global Z_BUF_ERROR: i32`

`pub global Z_VERSION_ERROR: i32`

`pub global Z_NO_FLUSH: i32`

`pub global Z_PARTIAL_FLUSH: i32`

`pub global Z_SYNC_FLUSH: i32`

`pub global Z_FULL_FLUSH: i32`

`pub global Z_FINISH: i32`

`pub global Z_BLOCK: i32`

`pub global Z_TREES: i32`

`pub global Z_NO_COMPRESSION: i32`

`pub global Z_BEST_SPEED: i32`

`pub global Z_BEST_COMPRESSION: i32`

`pub global Z_DEFAULT_COMPRESSION: i32`

`pub global Z_DEFAULT_STRATEGY: i32`

`pub global Z_FILTERED: i32`

`pub global Z_HUFFMAN_ONLY: i32`

`pub global Z_RLE: i32`

`pub global Z_FIXED: i32`

`pub global Z_BINARY: i32`

`pub global Z_TEXT: i32`

`pub global Z_UNKNOWN: i32`

`pub global Z_DEFLATED: i32`

`pub global MAX_WBITS: i32`

`pub global ZLIB_FORMAT: i32`

`pub global RAW_FORMAT: i32`

`pub global GZIP_FORMAT: i32`

`pub global AUTO_FORMAT: i32`

Format value that asks an InflateStream to auto-detect zlib or gzip framing from the magic bytes.

Functions

`pub fn zlib_version() -> String`

Returns the zlib version string.

`pub fn adler32(adler: u32, buf: &ByteList, offset: i32, len: i32) -> u32`

Computes an Adler-32 checksum over buf[offset..<offset + len], starting from adler.

`pub fn adler32_init() -> u32`

Returns the initial Adler-32 checksum value (1).

`pub fn adler32_combine(adler1: u32, adler2: u32, len2: i32) -> u32`

Combines two Adler-32 checksums into one for concatenated data.

adler1 and adler2 are the checksums of the first and second segments; len2 is the length of the second segment.

`pub fn crc32(crc: u32, buf: &ByteList, offset: i32, len: i32) -> u32`

Computes a CRC-32 checksum over buf[offset..<offset + len], starting from crc.

`pub fn crc32_init() -> u32`

Returns the initial CRC-32 checksum value (0).

`pub fn crc32_combine(crc1: u32, crc2: u32, len2: i32) -> u32`

Combines two CRC-32 checksums into one for concatenated data.

crc1 and crc2 are the checksums of the first and second segments; len2 is the length of the second segment.

`pub fn compress_bound(source_len: i32) -> i32`

Returns the maximum compressed size for a given source length.

Uses the larger of the stored-block worst case and the classic compressBound formula to match zlib-rs/zlib-ng behavior.

`pub fn inflate_raw(input: &ByteList, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Decompresses raw DEFLATE data (no header/checksum), failing with ZlibError::OutputExceedsMax once the output would pass max_output.

`pub fn inflate_zlib(input: &ByteList, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Decompresses zlib-wrapped data (RFC 1950: 2-byte header + DEFLATE + 4-byte Adler-32), failing with ZlibError::OutputExceedsMax once the output would pass max_output.

`pub fn deflate_stored(input: &ByteList) -> ByteList`

Compresses data into raw DEFLATE stored blocks (no actual compression).

`pub fn deflate_huffman(input: &ByteList) -> ByteList`

Compresses data using DEFLATE with fixed Huffman codes and LZ77 matching.

`pub fn deflate_raw(input: &ByteList, level: i32 = Z_DEFAULT_COMPRESSION, strategy: i32 = Z_DEFAULT_STRATEGY) -> ByteList`

Compresses data as raw DEFLATE (RFC 1951) with no wrapper header or trailer.

level is 0-9 (0 = stored, 1 = fastest, 9 = best compression). strategy is one of Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE, or Z_FIXED.

`pub fn zlib_compress(input: &ByteList, level: i32 = Z_DEFAULT_COMPRESSION, strategy: i32 = Z_DEFAULT_STRATEGY) -> ByteList`

Compresses data in zlib format (RFC 1950).

level defaults to Z_DEFAULT_COMPRESSION and strategy defaults to Z_DEFAULT_STRATEGY.

`pub fn inflate_gzip(input: &ByteList, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Decompresses gzip-wrapped data (RFC 1952), concatenating its members and failing with ZlibError::OutputExceedsMax once their output would pass max_output.

`pub fn uncompress(input: &ByteList, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Auto-detects the wrapper format (zlib or gzip) and decompresses, failing with ZlibError::OutputExceedsMax once the output would pass max_output.

`pub fn gzip_compress(input: &ByteList, level: i32 = Z_DEFAULT_COMPRESSION, strategy: i32 = Z_DEFAULT_STRATEGY, header: &GzipHeader = &GzipHeader::new()) -> ByteList`

Compresses data as one gzip member (RFC 1952). header sets MTIME, the file name, the comment and the other optional fields; the default sets none.

`pub fn inflate_get_gzip_header(input: &ByteList) -> Result<GzipHeader, ZlibError>`

Parses and returns the gzip header without decompressing the body.

`pub fn inflate_sync_find(input: &ByteList, start: i32) -> i32`

Finds the next DEFLATE sync point (00 00 FF FF) at or after start.

Returns the offset of the recovered block, or -1 if no sync point is found. Useful for recovering from corruption in a DEFLATE stream after a sync flush.

Structs

`pub struct GzipHeader`

A gzip header (RFC 1952) used by gzip_compress to set optional fields and by inflate_get_gzip_header to report them.

Fields are private.

`pub fn new() -> GzipHeader`

Creates a header with all fields cleared (os set to 0xFF = unknown).

`pub fn text(&self) -> bool`

Returns true if the FTEXT flag is set (payload is probably ASCII text).

`pub fn time(&self) -> u32`

Returns MTIME (modification time as a Unix timestamp; 0 = unset).

`pub fn os(&self) -> i32`

Returns the OS byte (0xFF = unknown).

`pub fn extra(&self) -> ByteList`

Returns the FEXTRA payload (empty = none).

`pub fn name(&self) -> String`

Returns the FNAME (original file name; empty = none).

`pub fn comment(&self) -> String`

Returns the FCOMMENT (empty = none).

`pub fn hcrc(&self) -> bool`

Returns true if the FHCRC flag is set (header CRC16 is present).

`pub fn set_text(&mut self, text: bool)`

Sets the FTEXT flag, indicating the payload is probably ASCII text.

`pub fn set_time(&mut self, time: u32)`

Sets MTIME (modification time as a Unix timestamp; 0 = unset).

`pub fn set_os(&mut self, os: i32)`

Sets the OS byte (0xFF = unknown).

`pub fn set_extra(&mut self, extra: &ByteList)`

Sets the FEXTRA payload. An empty array clears the field.

`pub fn set_name(&mut self, name: String)`

Sets the FNAME (original file name). An empty string clears the field.

`pub fn set_comment(&mut self, comment: String)`

Sets the FCOMMENT. An empty string clears the field.

`pub fn set_hcrc(&mut self, hcrc: bool)`

Enables the FHCRC flag, which appends a 16-bit CRC of the header.

`pub struct DeflateStream`

Streaming deflate compressor.

Buffer chunks via update, then call finish once to emit the compressed output. compress is a single-shot variant that compresses one input without buffering. The output wrapper is selected by format (defaults to ZLIB_FORMAT).

Fields are private.

`pub fn new(level: i32 = Z_DEFAULT_COMPRESSION, strategy: i32 = Z_DEFAULT_STRATEGY, format: i32 = ZLIB_FORMAT) -> DeflateStream`

Creates a stream emitting format (ZLIB_FORMAT, RAW_FORMAT, or GZIP_FORMAT).

`pub fn set_header(&mut self, header: &GzipHeader)`

Attaches a custom gzip header. The header is only emitted when the stream's format is GZIP_FORMAT; it is ignored for the zlib and raw formats.

`pub fn params(&mut self, level: i32, strategy: i32)`

Changes the compression level and strategy for subsequent input. The new values take effect when finish or compress is called.

`pub fn bound(&self, source_len: i32) -> i32`

Returns an upper bound on the compressed size for source_len input bytes (delegates to compress_bound).

`pub fn pending(&self) -> i32`

Returns the number of bytes currently buffered awaiting compression.

`pub fn get_total_in(&self) -> i32`

Returns the cumulative number of input bytes consumed across all finish/compress calls.

`pub fn get_total_out(&self) -> i32`

Returns the cumulative number of output bytes produced across all finish/compress calls.

`pub fn reset(&mut self)`

Discards buffered input and counters so the stream can be reused. level, strategy, format, and any custom gzip header are kept.

`pub fn copy(&self) -> DeflateStream`

Returns an independent copy of this stream, including buffered input and any attached gzip header.

`pub fn update(&mut self, chunk: &ByteList)`

Appends chunk to the input buffer. Panics if the stream has already been finished.

`pub fn finish(&mut self) -> ByteList`

Compresses all buffered input and returns the wrapped output. Marks the stream as finished; further update/finish/compress calls panic until reset is invoked.

`pub fn compress(&mut self, input: &ByteList) -> ByteList`

Compresses input in one shot, bypassing the internal buffer. Marks the stream as finished.

`pub struct InflateStream`

Streaming inflate decompressor.

Buffer compressed chunks via update, then call finish once to produce the decompressed output. decompress is a single-shot variant.

Fields are private.

`pub fn new(format: i32 = ZLIB_FORMAT) -> InflateStream`

Creates a stream for input in format (ZLIB_FORMAT, RAW_FORMAT, GZIP_FORMAT, or AUTO_FORMAT).

`pub fn get_total_in(&self) -> i32`

Returns the cumulative number of input bytes consumed across all finish calls.

`pub fn get_total_out(&self) -> i32`

Returns the cumulative number of output bytes produced across all finish calls.

`pub fn reset(&mut self)`

Discards buffered input and counters so the stream can be reused. format is preserved.

`pub fn copy(&self) -> InflateStream`

Returns an independent copy of this stream, including buffered input.

`pub fn update(&mut self, chunk: &ByteList)`

Appends chunk to the buffered compressed input.

`pub fn finish(&mut self, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Decompresses the buffered input into at most max_output bytes and clears the buffer. The stream may be reused for further input.

`pub fn decompress(&self, input: &ByteList, max_output: i32 = i32::MAX) -> Result<ByteList, ZlibError>`

Decompresses input in one shot into at most max_output bytes, using the stream's format. Does not touch the internal buffer.

Enums

`pub enum ZlibError`

Error type for zlib/gzip decompression operations.