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.

DecompressedSizeError

Error from find_decompressed_size.

FrameContentSize

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

FrameMagic

What the first four bytes of a buffer announce, read by frame_magic.

FrameSizeError

Error from find_frame_compressed_size.

LegacyVersionlegacy

One of the pre-1.0 frame formats this crate decodes.

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

decompression_margin

Bytes the compressed input must trail the end of the output by for every frame in src to decode in place: the compressed data sits at the end of the output buffer and the decoder writes from its start. Backs the C ZSTD_decompressionMargin.

find_decompressed_size

Total decompressed size the frames in src declare, without decoding any of them: FrameContentSize::Known with the sum, skippable frames counting zero, or FrameContentSize::Unknown as soon as one frame does not declare its size. Backs the C ZSTD_findDecompressedSize entry point.

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_input_needed

How many bytes from its start the frame header beginning src takes to read whole, judged from what src holds of it: the bytes that hold the descriptor until they are all here (five, or one without the magic number), then the header’s own length, and eight for a skippable frame. A caller reading a header in pieces asks this before read_frame_header_info; upstream’s ZSTD_getFrameHeader_advanced returns the same counts.

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.

frame_header_size_in_format

frame_header_size for a frame in either format: with magicless the header starts at its descriptor byte and its length counts no magic number.

frame_magic

Which frame src starts with, judged by its magic number alone. Backs the C ZSTD_isFrame / ZSTD_isSkippableFrame. None when src is shorter than four bytes or the magic is no frame’s.

is_frame

Whether src starts with a frame this build decodes or skips: a Zstandard frame, a skippable frame, or with the legacy feature a v0.5-v0.7 frame. Backs the C ZSTD_isFrame, which answers the same for upstream’s default build.

min_decoding_buffer_size

Smallest output buffer a block-by-block decode of a frame can run in: the window, plus room for a block written after it and split literals, capped by the content size when the frame declares one. Backs the C ZSTD_decodingBufferSize_min; None when the result does not fit usize.

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.