Enum CompressionLevel 

pub enum CompressionLevel {
    Uncompressed,
    Fastest,
    Default,
    Better,
    Best,
    Level(i32),
}

The compression mode used impacts the speed of compression, and resulting compression ratios. Faster compression will result in worse compression ratios, and vice versa.

Variants

Uncompressed

This level does not compress the data at all, and simply wraps it in a Zstandard frame.

Fastest

This level is roughly equivalent to Zstd compression level 1

Default

This level uses the crate’s dedicated dfast-style matcher to target a better speed/ratio tradeoff than CompressionLevel::Fastest.

It represents this crate’s “default” compression setting and may evolve in future versions as the implementation moves closer to reference zstd level 3 behavior.

Better

This level is roughly equivalent to Zstd level 7.

Uses the hash-chain matcher with a lazy2 matching strategy: the encoder evaluates up to two positions ahead before committing to a match, trading speed for a better compression ratio than CompressionLevel::Default.

Limitation: hash-chain tables use 32-bit positions. For single-frame inputs exceeding ~4 GiB, matches can still be found for roughly one window past that point; once all in-window positions exceed u32::MAX (≈4 GiB + window size), matching becomes effectively repcode-only. Prefer CompressionLevel::Default for very large single-frame streams until table rebasing is implemented.

Best

This level is roughly equivalent to Zstd level 11.

Uses the hash-chain matcher with a deep lazy2 matching strategy and a 16 MiB window. Compared to CompressionLevel::Better, this level uses larger hash and chain tables (2 M / 1 M entries vs 1 M / 512 K), a deeper search (32 candidates vs 16), and a higher target match length (128 vs 48), trading speed for the best compression ratio available in this crate.

Limitation: hash-chain tables use 32-bit positions. For single-frame inputs exceeding ~4 GiB, matches can still be found for roughly one window past that point; once all in-window positions exceed u32::MAX (≈4 GiB + window size), matching becomes effectively repcode-only. Prefer CompressionLevel::Default for very large single-frame streams until table rebasing is implemented.

Level(i32)

Numeric compression level.

Levels 1–22 correspond to the C zstd level numbering. Higher values produce smaller output at the cost of more CPU time. Negative values select ultra-fast modes that trade ratio for speed. Level 0 is treated as DEFAULT_LEVEL, matching C zstd semantics.

Named variants map to specific numeric levels: Fastest = 1, Default = 3, Better = 7, Best = 11. Best remains the highest-ratio named preset, but Level values above 11 can target stronger (slower) tuning than the named hierarchy.

Levels above 11 use progressively larger windows and deeper search with the lazy2 hash-chain backend. Levels that require strategies this crate has not yet implemented (btopt, btultra) are approximated with the closest available matcher.

Limitation: large hash-chain levels still use 32-bit positions. For single-frame inputs exceeding ~4 GiB, matches can still be found for roughly one window past that point; once all in-window positions exceed u32::MAX (≈4 GiB + window size), matching becomes effectively repcode-only. Prefer CompressionLevel::Default for very large single-frame streams until table rebasing is implemented.

Semver note: this variant was added after the initial enum shape and is a breaking API change for downstream crates that exhaustively match on CompressionLevel without a wildcard arm.

Implementations

impl CompressionLevel

pub const MIN_LEVEL: i32 = -131072

The minimum supported numeric compression level (ultra-fast mode).

pub const MAX_LEVEL: i32 = 22

The maximum supported numeric compression level.

pub const DEFAULT_LEVEL: i32 = 3

The default numeric compression level (equivalent to Default).

pub const fn from_level(level: i32) -> Self

Create a compression level from a numeric value.

Returns named variants for canonical levels (0/3, 1, 7, 11) and Level for all other values.

With the default matcher backend (MatchGeneratorDriver), values outside MIN_LEVEL..=MAX_LEVEL are silently clamped during built-in level parameter resolution.

Trait Implementations

impl Clone for CompressionLevel

fn clone(&self) -> CompressionLevel

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CompressionLevel

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

Formats the value using the given formatter.

impl Copy for CompressionLevel