Module decoding 

RFC 8878 Zstandard decoder.

The entry points:

• StreamingDecoder — implements crate::io::Read over a compressed byte stream, transparently parsing the frame header and concatenated frames. The typical choice for application code.
• FrameDecoder — single-frame interface; use when the caller manages the input buffer manually (zero-copy slices, network framing, etc).
• workspace::WorkspaceDecoder (feature caller-workspace): streaming decoder over a byte slice the caller sizes and owns, with no allocation and limits on window, output and work. For consumers that account their memory themselves, such as browser bundles verifying a download.
• DictionaryHandle — pre-parsed dictionary handle. Parse the dictionary bytes once with DictionaryHandle::decode_dict and reuse the handle across every subsequent decode; saves the per-frame dictionary parse cost when the same dictionary is used many times in a row.

Both decoders expose dictionary-aware constructors / methods, though the exact naming differs:

• StreamingDecoder::new_with_dictionary_handle / StreamingDecoder::new_with_dictionary_bytes
• FrameDecoder::decode_all_with_dict_handle / FrameDecoder::decode_all_with_dict_bytes

The _handle variants reuse a previously parsed DictionaryHandle; the _bytes variants parse the dictionary per call (suitable for one-off decodes).

Errors surface through errors::FrameDecoderError and the per-decoder error types in the errors submodule.

Modules

errors

Errors that might occur while decoding zstd formatted data

workspacecaller-workspace

Streaming decoder that runs entirely in caller-owned memory.

Structs

Dictionary

Zstandard includes support for “raw content” dictionaries, that store bytes optionally used during sequence execution.

DictionaryHandle

Shared pre-parsed dictionary handle for repeated decoding.

DictionaryRefused

A dictionary a StreamingDecoder constructor refused, with what the constructor took by value handed back: the source, unread, since the dictionary is checked before anything is read, and the decoder where the caller passed one (() where the constructor makes its own).

FinishedFrame

The sizes of one frame a StreamingDecoder decoded, as StreamingDecoder::read_reporting_frames reports it: what the frame took from the source and what it decoded to, as upstream’s ZSTD_trace_decompress_end reports them.

FrameDecoder

Low level Zstandard decoder that can be used to decompress frames with fine control over when and how many bytes are decoded.

FrameHeaderInfo

Frame header fields decoded by read_frame_header_info, mirroring the values the C ZSTD_getFrameHeader fills into a ZSTD_FrameHeader.

PartialDecodelsm

Outcome of FrameDecoder::decode_blocks_partial: the decompressed bytes of the requested inner-block range plus where (if anywhere) decoding stopped early.

ResumeInputlsm

Resume input fed to FrameDecoder::decode_blocks_partial’s resume argument to continue a cold partial decode without re-decompressing the preceding blocks.

ResumeStatelsm

Cross-block decode state needed to resume a cold partial decode at an inner block boundary, emitted by FrameDecoder::decode_blocks_partial when its emit_resume argument is true (returned in PartialDecode::resume_state) and fed back via that same method’s resume argument (ResumeInput).

StreamingDecoder

High level Zstandard frame decoder that can be used to decompress a given Zstandard frame.

Enums

BlockDecodingStrategy

ContentChecksum

How the decoder treats a frame’s optional XXH64 content checksum (RFC 8878 Content_Checksum_flag). The XXH64 pass over the decompressed output is a measurable share of decode time, so it is made skippable.

FrameContentSize

Decompressed size a frame declares in its header, as read by read_frame_content_size without decoding the frame body.

FrameSizeError

Error from find_frame_compressed_size.

Constants

DICTIONARY_MAGIC

This 4 byte (little endian) magic number refers to the start of a dictionary

MAXIMUM_ALLOWED_WINDOW_SIZE

Largest window a frame may declare before a decoder that holds the window itself refuses it, unless FrameDecoder::set_max_window_size raised the ceiling.

MAX_DECODER_WINDOW_SIZE

Largest window any decode accepts, the ceiling FrameDecoder::set_max_window_size can be raised to. The largest window this build decodes on any path, however far the ceiling is raised: upstream ZSTD_WINDOWLOG_MAX, 1 << 31 on 64-bit targets and 1 << 30 on 32-bit ones, where a larger window could not be addressed.

Functions

find_frame_compressed_size

On-disk byte length of the FIRST frame in src — magic number, frame header, every block, and the trailing content checksum when present — computed by walking the block headers without decoding any block body.

frame_decompressed_bound

Upper bound on the decompressed size of the FIRST frame in src, without decoding the body. Backs the C ZSTD_decompressBound (per-frame term).

frame_header_size

Length in bytes of the frame header at the start of src, including the 4-byte magic number (the offset at which the first block begins). Backs the C ZSTD_frameHeaderSize.

read_frame_content_size

Read the decompressed size a frame declares in its header, without decoding the frame body.

read_frame_header_info

Decode the leading frame header fields of src without decoding the body.