structured_zstd/encoding/

parameters.rs

//! Fine-grained compression parameters — the drop-in equivalent of C
//! zstd's advanced `ZSTD_CCtx_setParameter` surface.
//!
//! [`CompressionLevel`] selects a
//! whole tuning preset in one knob. This module exposes the individual
//! knobs underneath it — window/hash/chain/search logs, the match
//! strategy, and the long-distance-matching (LDM) block — so callers
//! can override a level's defaults for domain-specific tuning.
//!
//! # Builder
//!
//! [`CompressionParameters`] is built through
//! [`CompressionParameters::builder`], which takes an explicit base
//! [`CompressionLevel`] (there is no
//! implicit default). Every knob left unset inherits that base level's
//! resolved value, so a builder that overrides nothing reproduces plain
//! level-based compression byte-for-byte.
//!
//! ```rust
//! use structured_zstd::encoding::{CompressionLevel, CompressionParameters, Strategy};
//!
//! let params = CompressionParameters::builder(CompressionLevel::Level(19))
//!     .window_log(22)
//!     .strategy(Strategy::Btultra2)
//!     .enable_long_distance_matching(true)
//!     .build()
//!     .expect("parameters within bounds");
//! ```
//!
//! # Bounds
//!
//! Every knob has an inclusive `[lower, upper]` range, queryable via
//! [`CParameter::bounds`] (the analogue of `ZSTD_cParam_getBounds`).
//! [`CompressionParametersBuilder::build`] validates each set knob and
//! returns [`ParameterError::OutOfBounds`] for the first violation.
//!
//! # Long-distance matching (LDM)
//!
//! LDM is **off at every [`CompressionLevel`] preset**, matching upstream `libzstd.so.1` where `ZSTD_compress(..., level)`
//! never enables LDM — even at level 22. It is activated either by
//! [`CompressionParametersBuilder::enable_long_distance_matching`] or by any of
//! the `ldm_*` setters, which each imply `enable_long_distance_matching(true)`.
//! It works under every [`Strategy`]: the optimal parsers weigh its matches as
//! candidates, the others take them outright and search only the bytes between
//! them, as upstream does. A dictionary loaded under it is indexed for it too.

use crate::encoding::CompressionLevel;

/// Match-finder strategy — the drop-in equivalent of C zstd's
/// `ZSTD_strategy` enum (`ZSTD_fast` … `ZSTD_btultra2`). The numeric
/// ordinals match upstream (`fast = 1` … `btultra2 = 9`), so
/// [`Strategy::ordinal`] / [`Strategy::from_ordinal`] round-trip with
/// the C `ZSTD_c_strategy` parameter value.
#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum Strategy {
    /// `ZSTD_fast` (1) — single-table fast finder.
    Fast,
    /// `ZSTD_dfast` (2) — two parallel hash tables.
    Dfast,
    /// `ZSTD_greedy` (3) — commit the first acceptable match, no lookahead.
    Greedy,
    /// `ZSTD_lazy` (4) — one-position lazy lookahead.
    Lazy,
    /// `ZSTD_lazy2` (5) — two-position lazy lookahead.
    Lazy2,
    /// `ZSTD_btlazy2` (6) — binary-tree-assisted lazy2.
    Btlazy2,
    /// `ZSTD_btopt` (7) — optimal parser, no ultra refinements.
    Btopt,
    /// `ZSTD_btultra` (8) — optimal parser with refined price tables.
    Btultra,
    /// `ZSTD_btultra2` (9) — optimal parser with two-pass dynamic stats.
    Btultra2,
}

impl Strategy {
    /// Upstream `ZSTD_strategy` ordinal (`fast = 1` … `btultra2 = 9`).
    pub const fn ordinal(self) -> u32 {
        match self {
            Self::Fast => 1,
            Self::Dfast => 2,
            Self::Greedy => 3,
            Self::Lazy => 4,
            Self::Lazy2 => 5,
            Self::Btlazy2 => 6,
            Self::Btopt => 7,
            Self::Btultra => 8,
            Self::Btultra2 => 9,
        }
    }

    /// Construct from an upstream `ZSTD_strategy` ordinal. Returns
    /// `None` outside `1..=9`.
    pub const fn from_ordinal(ordinal: u32) -> Option<Self> {
        Some(match ordinal {
            1 => Self::Fast,
            2 => Self::Dfast,
            3 => Self::Greedy,
            4 => Self::Lazy,
            5 => Self::Lazy2,
            6 => Self::Btlazy2,
            7 => Self::Btopt,
            8 => Self::Btultra,
            9 => Self::Btultra2,
            _ => return None,
        })
    }

    /// Internal runtime strategy tag.
    pub(crate) const fn tag(self) -> crate::encoding::strategy::StrategyTag {
        use crate::encoding::strategy::StrategyTag;
        match self {
            Self::Fast => StrategyTag::Fast,
            Self::Dfast => StrategyTag::Dfast,
            Self::Greedy => StrategyTag::Greedy,
            // Lazy / Lazy2 ride the runtime `Lazy` tag (the lazy lookahead
            // depth carries the variance, see `lazy_depth`). `Btlazy2`
            // keeps its own tag: `Lazy` resolves to the Row finder, while
            // btlazy2 is a binary-tree search and must stay on the
            // HashChain/BT storage.
            Self::Lazy | Self::Lazy2 => StrategyTag::Lazy,
            Self::Btlazy2 => StrategyTag::Btlazy2,
            Self::Btopt => StrategyTag::BtOpt,
            Self::Btultra => StrategyTag::BtUltra,
            Self::Btultra2 => StrategyTag::BtUltra2,
        }
    }

    /// Lazy lookahead depth for the greedy/lazy band (0/1/2). `Optimal`
    /// strategies report 2 (the depth their hash-chain seed walk runs at).
    pub(crate) const fn lazy_depth(self) -> u8 {
        match self {
            Self::Fast | Self::Dfast | Self::Greedy => 0,
            Self::Lazy => 1,
            _ => 2,
        }
    }
}

/// Whether literals are entropy-coded, the drop-in equivalent of C zstd's
/// `ZSTD_c_literalCompressionMode` (`ZSTD_ps_auto` / `ZSTD_ps_enable` /
/// `ZSTD_ps_disable`).
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub enum LiteralCompressionMode {
    /// The level decides: literals are stored raw on the fast strategy's
    /// acceleration (negative) levels, where the Huffman pass costs more
    /// speed than it saves, and compressed everywhere else.
    #[default]
    Auto,
    /// Compress literals on every level, the negative ones included. A
    /// block whose literals do not shrink still stores them raw.
    Enable,
    /// Never compress literals: every literal section is stored raw.
    Disable,
}

/// Which finder the greedy, lazy and lazy2 strategies search, the drop-in
/// equivalent of C zstd's `ZSTD_c_useRowMatchFinder` (`ZSTD_ps_auto` /
/// `ZSTD_ps_enable` / `ZSTD_ps_disable`). The other strategies have a finder
/// of their own and ignore it.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub enum RowMatchFinderMode {
    /// Rows above a 16 KiB window, a hash chain at or below it, where the rows
    /// cost more to set up than they save (upstream
    /// `ZSTD_resolveRowMatchFinderMode`, zstd_compress.c:246).
    #[default]
    Auto,
    /// Search rows at every window size.
    Enable,
    /// Search a hash chain at every window size.
    Disable,
}

impl RowMatchFinderMode {
    /// Whether a greedy / lazy / lazy2 frame with a `window`-byte window
    /// searches rows.
    pub(crate) const fn searches_rows(self, window: usize) -> bool {
        match self {
            Self::Auto => window > (1 << 14),
            Self::Enable => true,
            Self::Disable => false,
        }
    }
}

/// One tunable compression parameter — the analogue of a C zstd
/// `ZSTD_cParameter`. Used to query bounds via [`CParameter::bounds`].
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum CParameter {
    /// Maximum back-reference distance, `log2`. C `ZSTD_c_windowLog`.
    WindowLog,
    /// Match-finder hash table size, `log2`. C `ZSTD_c_hashLog`.
    HashLog,
    /// Match-finder chain table size, `log2`. C `ZSTD_c_chainLog`.
    ChainLog,
    /// Number of search attempts, `log2`. C `ZSTD_c_searchLog`.
    SearchLog,
    /// Minimum match length in bytes. C `ZSTD_c_minMatch`.
    MinMatch,
    /// "Good enough" match length that ends the search. C `ZSTD_c_targetLength`.
    TargetLength,
    /// Match-finder [`Strategy`] (1..=9). C `ZSTD_c_strategy`.
    Strategy,
    /// LDM enable flag (0/1). C `ZSTD_c_enableLongDistanceMatching`.
    EnableLongDistanceMatching,
    /// LDM hash table size, `log2`. C `ZSTD_c_ldmHashLog`.
    LdmHashLog,
    /// LDM minimum match length in bytes. C `ZSTD_c_ldmMinMatch`.
    LdmMinMatch,
    /// LDM bucket size, `log2`. C `ZSTD_c_ldmBucketSizeLog`.
    LdmBucketSizeLog,
    /// LDM hash-insertion rate, `log2`. C `ZSTD_c_ldmHashRateLog`.
    LdmHashRateLog,
}

/// Inclusive `[lower_bound, upper_bound]` range for a [`CParameter`],
/// the drop-in equivalent of C zstd's `ZSTD_bounds`.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct Bounds {
    /// Smallest accepted value (inclusive).
    pub lower_bound: i64,
    /// Largest accepted value (inclusive).
    pub upper_bound: i64,
}

impl Bounds {
    /// Whether `value` falls within `[lower_bound, upper_bound]`.
    pub const fn contains(&self, value: i64) -> bool {
        value >= self.lower_bound && value <= self.upper_bound
    }

    /// `value` moved to the nearest end of the range when it falls outside.
    ///
    /// ```
    /// use structured_zstd::encoding::CParameter;
    /// assert_eq!(CParameter::MinMatch.bounds().clamp(9), 7);
    /// assert_eq!(CParameter::MinMatch.bounds().clamp(5), 5);
    /// ```
    pub const fn clamp(&self, value: i64) -> i64 {
        if value < self.lower_bound {
            self.lower_bound
        } else if value > self.upper_bound {
            self.upper_bound
        } else {
            value
        }
    }
}

impl CParameter {
    /// Inclusive value bounds for this parameter, mirroring
    /// `ZSTD_cParam_getBounds`. Window/hash/chain logs cap at 30 (the
    /// encoder's match-finder ceiling) rather than the 31 C allows on
    /// 64-bit, because the back-reference history is indexed with `u32`
    /// positions over a `2 * window` eviction band.
    pub const fn bounds(self) -> Bounds {
        let (lower_bound, upper_bound) = match self {
            // ZSTD_WINDOWLOG_MIN .. encoder ceiling.
            Self::WindowLog => (10, 30),
            // ZSTD_HASHLOG_MIN .. ZSTD_HASHLOG_MAX.
            Self::HashLog => (6, 30),
            // ZSTD_CHAINLOG_MIN .. ZSTD_CHAINLOG_MAX (64-bit).
            Self::ChainLog => (6, 30),
            // ZSTD_SEARCHLOG_MIN .. ZSTD_SEARCHLOG_MAX (64-bit).
            Self::SearchLog => (1, 30),
            // ZSTD_MINMATCH_MIN .. ZSTD_MINMATCH_MAX.
            Self::MinMatch => (3, 7),
            // ZSTD_TARGETLENGTH_MIN .. ZSTD_TARGETLENGTH_MAX.
            Self::TargetLength => (0, 131_072),
            // ZSTD_fast .. ZSTD_btultra2.
            Self::Strategy => (1, 9),
            // Boolean flag.
            Self::EnableLongDistanceMatching => (0, 1),
            // ZSTD_LDM_HASHLOG_MIN .. ZSTD_LDM_HASHLOG_MAX.
            Self::LdmHashLog => (6, 30),
            // ZSTD_LDM_MINMATCH_MIN .. ZSTD_LDM_MINMATCH_MAX.
            Self::LdmMinMatch => (4, 4096),
            // ZSTD_LDM_BUCKETSIZELOG_MIN .. ZSTD_LDM_BUCKETSIZELOG_MAX.
            Self::LdmBucketSizeLog => (1, 8),
            // ZSTD_LDM_HASHRATELOG_MIN .. ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN.
            Self::LdmHashRateLog => (0, 24),
        };
        Bounds {
            lower_bound,
            upper_bound,
        }
    }
}

/// The match-finder parameters a numeric level selects for a source of a given
/// size, the drop-in equivalent of C zstd's `ZSTD_getCParams`.
///
/// The size matters: the reference's level table has a row per source-size
/// tier, and the tier changes the strategy as well as the table widths, so one
/// level can run a different match-finder on a small input than on a large
/// one. This is the selection the encoder itself makes for a frame without a
/// dictionary; knobs set through [`CompressionParameters`] override it.
///
/// # Examples
///
/// ```
/// use structured_zstd::encoding::{LevelParameters, Strategy};
///
/// // Level 11 is a lazy2 level on a large or unknown-size source...
/// let large = LevelParameters::for_level(11, None, 0);
/// assert_eq!(large.strategy, Strategy::Lazy2);
///
/// // ...and the optimal parser on one of 16 KiB or less, whose window is
/// // also cut down to the source.
/// let small = LevelParameters::for_level(11, Some(4096), 0);
/// assert_eq!(small.strategy, Strategy::Btopt);
/// assert_eq!(small.window_log, 12);
/// ```
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct LevelParameters {
    /// Back-reference window, `log2`. C `windowLog`.
    pub window_log: u32,
    /// Chain / binary-tree table size, `log2`. C `chainLog`.
    pub chain_log: u32,
    /// Hash table size, `log2`. C `hashLog`.
    pub hash_log: u32,
    /// Search attempts per position, `log2`. C `searchLog`.
    pub search_log: u32,
    /// Match-finder hash width, in bytes. C `minMatch`.
    pub min_match: u32,
    /// Length that ends a search early; on a negative level, the step size
    /// minus one. C `targetLength`.
    pub target_length: u32,
    /// The match-finder strategy. C `strategy`.
    pub strategy: Strategy,
}

impl LevelParameters {
    /// Parameters for `level` compressing a source of `source_size` bytes with
    /// a `dictionary_size`-byte dictionary (`0` for none).
    ///
    /// `level` is on the reference's scale: `0` is the default level, levels
    /// above [`CompressionLevel::MAX_LEVEL`] clamp to it, and a negative level
    /// is an acceleration factor. `None` is a source of unknown size, which is
    /// sized as a large one; `Some(0)` is a source that is really empty.
    /// C `ZSTD_getCParams` spells unknown as `0`, so a caller porting from it
    /// maps `0` to `None`.
    pub fn for_level(level: i32, source_size: Option<u64>, dictionary_size: usize) -> Self {
        let size = source_size.unwrap_or(crate::encoding::cparams::CONTENTSIZE_UNKNOWN);
        let cp = crate::encoding::cparams::get_cparams(level, size, dictionary_size);
        Self {
            window_log: cp.window_log,
            chain_log: cp.chain_log,
            hash_log: cp.hash_log,
            search_log: cp.search_log,
            min_match: cp.min_match,
            target_length: cp.target_length,
            // Every row of the level table names one of the nine strategies.
            strategy: Strategy::from_ordinal(cp.strategy)
                .expect("the level table only holds strategies 1..=9"),
        }
    }

    /// These parameters fitted to a source of `source_size` bytes and a
    /// `dictionary_size`-byte dictionary, the drop-in equivalent of C zstd's
    /// `ZSTD_adjustCParams`: a window wider than the data comes down to it, and
    /// the tables shrink with the window. `None` is a source of unknown size,
    /// which leaves the tables alone.
    ///
    /// Every field must already lie within its [`CParameter::bounds`].
    ///
    /// # Examples
    ///
    /// ```
    /// use structured_zstd::encoding::LevelParameters;
    ///
    /// let level_19 = LevelParameters::for_level(19, None, 0);
    /// let small = level_19.adjusted(Some(1000), 0);
    /// assert_eq!(small.window_log, 10);
    /// assert!(small.hash_log <= 11);
    /// assert_eq!(level_19.adjusted(None, 0), level_19);
    /// ```
    pub fn adjusted(self, source_size: Option<u64>, dictionary_size: usize) -> Self {
        let cp = crate::encoding::cparams::CParams {
            window_log: self.window_log,
            chain_log: self.chain_log,
            hash_log: self.hash_log,
            search_log: self.search_log,
            min_match: self.min_match,
            target_length: self.target_length,
            strategy: self.strategy.ordinal(),
        };
        let size = source_size.unwrap_or(crate::encoding::cparams::CONTENTSIZE_UNKNOWN);
        let cp = crate::encoding::cparams::adjust_cparams(cp, size, dictionary_size, false);
        Self {
            window_log: cp.window_log,
            chain_log: cp.chain_log,
            hash_log: cp.hash_log,
            search_log: cp.search_log,
            min_match: cp.min_match,
            target_length: cp.target_length,
            strategy: self.strategy,
        }
    }
}

/// Error returned by [`CompressionParametersBuilder::build`] when a knob
/// is set outside its [`CParameter::bounds`].
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ParameterError {
    /// A parameter was set to a value outside its inclusive bounds.
    OutOfBounds {
        /// Which parameter violated its range.
        parameter: CParameter,
        /// The rejected value.
        value: i64,
        /// The inclusive `[lower, upper]` range it had to fall within.
        bounds: Bounds,
    },
}

impl core::fmt::Display for ParameterError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Self::OutOfBounds {
                parameter,
                value,
                bounds,
            } => write!(
                f,
                "compression parameter {parameter:?} = {value} out of bounds \
                 [{}, {}]",
                bounds.lower_bound, bounds.upper_bound
            ),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for ParameterError {}

/// LDM tuning overrides — every knob is `Option`, falling back to the
/// strategy-derived upstream zstd default (`LdmParams::adjust_for`) when unset.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub(crate) struct LdmOverride {
    pub(crate) hash_log: Option<u32>,
    pub(crate) min_match: Option<u32>,
    pub(crate) bucket_size_log: Option<u32>,
    pub(crate) hash_rate_log: Option<u32>,
}

/// Internal per-knob override set consumed by the match-generator's
/// `reset` path. Every field left `None` inherits the base level's
/// resolved value, so the default path is byte-identical to level-based
/// compression.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub(crate) struct ParamOverrides {
    pub(crate) window_log: Option<u8>,
    pub(crate) hash_log: Option<u32>,
    pub(crate) chain_log: Option<u32>,
    pub(crate) search_log: Option<u32>,
    pub(crate) min_match: Option<u32>,
    pub(crate) target_length: Option<u32>,
    pub(crate) strategy: Option<Strategy>,
    /// `Some` when `enable_long_distance_matching(true)` was set; carries
    /// the (possibly empty) LDM knob overrides.
    pub(crate) ldm: Option<LdmOverride>,
    /// Whether literals are entropy-coded; `Auto` leaves it to the level.
    pub(crate) literal_compression: LiteralCompressionMode,
    /// The greedy / lazy band's finder; `Auto` leaves it to the window.
    pub(crate) row_match_finder: RowMatchFinderMode,
}

impl ParamOverrides {
    /// Whether any knob overrides the base level. An all-`None`
    /// override is a no-op the `reset` path can skip entirely, keeping
    /// the default level-based geometry byte-identical.
    pub(crate) fn is_empty(&self) -> bool {
        self.window_log.is_none()
            && self.hash_log.is_none()
            && self.chain_log.is_none()
            && self.search_log.is_none()
            && self.min_match.is_none()
            && self.target_length.is_none()
            && self.strategy.is_none()
            && self.ldm.is_none()
            && self.literal_compression == LiteralCompressionMode::Auto
            && self.row_match_finder == RowMatchFinderMode::Auto
    }
}

/// Fully-resolved fine-grained compression parameters. Build through
/// [`CompressionParameters::builder`]; pass to
/// [`FrameCompressor::set_parameters`](crate::encoding::FrameCompressor::set_parameters)
/// or [`compress_with_parameters`](crate::encoding::compress_with_parameters).
///
/// Wraps a base [`CompressionLevel`] plus the set of knobs that override it. A parameter set that
/// overrides nothing is equivalent to compressing at its base level.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct CompressionParameters {
    level: CompressionLevel,
    overrides: ParamOverrides,
}

impl CompressionParameters {
    /// Start a builder from a base compression level. Knobs left unset
    /// inherit that level's resolved defaults.
    pub fn builder(level: CompressionLevel) -> CompressionParametersBuilder {
        CompressionParametersBuilder {
            level,
            window_log: None,
            hash_log: None,
            chain_log: None,
            search_log: None,
            min_match: None,
            target_length: None,
            strategy: None,
            enable_ldm: false,
            ldm: LdmOverride::default(),
            literal_compression: LiteralCompressionMode::Auto,
            row_match_finder: RowMatchFinderMode::Auto,
        }
    }

    /// The base compression level these parameters override.
    pub fn level(&self) -> CompressionLevel {
        self.level
    }

    /// Whether long-distance matching is enabled.
    pub fn long_distance_matching_enabled(&self) -> bool {
        self.overrides.ldm.is_some()
    }

    /// How literals are entropy-coded (see [`LiteralCompressionMode`]).
    pub fn literal_compression_mode(&self) -> LiteralCompressionMode {
        self.overrides.literal_compression
    }

    /// Which finder the greedy / lazy band searches (see [`RowMatchFinderMode`]).
    pub fn row_match_finder_mode(&self) -> RowMatchFinderMode {
        self.overrides.row_match_finder
    }

    /// The window, `log2`, the encoder gives a frame of `source_size` bytes
    /// (`None` = unknown) with `dictionary_size` bytes of dictionary content
    /// under these parameters: resolved exactly as the encoder resolves it.
    ///
    /// ```
    /// use structured_zstd::encoding::{CompressionLevel, CompressionParameters};
    ///
    /// let params = CompressionParameters::builder(CompressionLevel::Level(19))
    ///     .window_log(23)
    ///     .build()
    ///     .unwrap();
    /// assert_eq!(params.window_log_for(None, 0), 23);
    /// assert!(params.window_log_for(Some(1000), 0) < 23);
    /// ```
    pub fn window_log_for(&self, source_size: Option<u64>, dictionary_size: usize) -> u32 {
        let sizes = crate::encoding::DictionarySizes {
            content: dictionary_size,
            serialized: dictionary_size,
        };
        let params =
            crate::encoding::levels::config::frame_level_params(self, source_size, Some(sizes));
        u32::from(params.window_log)
    }

    /// These parameters as a dictionary's own, driving a frame of
    /// `source_size` bytes (`None` = unknown): an explicit window is raised to
    /// cover the source, as far as 512 KiB, as upstream raises a prepared
    /// dictionary's window for a frame of known size
    /// (`ZSTD_compressBegin_usingCDict_internal`, zstd_compress.c:5844-5852).
    /// A window left to the level is resolved for the source and covers it.
    ///
    /// ```
    /// use structured_zstd::encoding::{CompressionLevel, CompressionParameters};
    ///
    /// let params = CompressionParameters::builder(CompressionLevel::Level(3))
    ///     .window_log(10)
    ///     .build()
    ///     .unwrap();
    /// let source = Some(1 << 20);
    /// assert_eq!(params.for_dictionary_frame(source).window_log_for(source, 0), 19);
    /// assert_eq!(params.for_dictionary_frame(None).window_log_for(None, 0), 10);
    /// ```
    pub fn for_dictionary_frame(mut self, source_size: Option<u64>) -> Self {
        const RAISE_LIMIT: u64 = 1 << 19;
        let known =
            source_size.filter(|size| *size != crate::encoding::cparams::CONTENTSIZE_UNKNOWN);
        if let (Some(window), Some(source)) = (self.overrides.window_log, known) {
            // Bounded by `RAISE_LIMIT`, so it fits and its log is at most 19.
            let limited = source.min(RAISE_LIMIT) as u32;
            let source_log = if limited > 1 {
                (u32::BITS - (limited - 1).leading_zeros()) as u8
            } else {
                1
            };
            self.overrides.window_log = Some(window.max(source_log));
        }
        self
    }

    pub(crate) fn overrides(&self) -> ParamOverrides {
        self.overrides
    }
}

/// Builder for [`CompressionParameters`]. Each setter records one knob;
/// [`Self::build`] validates them against [`CParameter::bounds`].
#[derive(Copy, Clone, Debug)]
pub struct CompressionParametersBuilder {
    level: CompressionLevel,
    window_log: Option<u32>,
    hash_log: Option<u32>,
    chain_log: Option<u32>,
    search_log: Option<u32>,
    min_match: Option<u32>,
    target_length: Option<u32>,
    strategy: Option<Strategy>,
    enable_ldm: bool,
    ldm: LdmOverride,
    literal_compression: LiteralCompressionMode,
    row_match_finder: RowMatchFinderMode,
}

impl CompressionParametersBuilder {
    /// Choose the finder the greedy, lazy and lazy2 strategies search instead
    /// of leaving it to the window size. C `ZSTD_c_useRowMatchFinder`.
    ///
    /// ```rust
    /// use structured_zstd::encoding::{
    ///     compress_with_parameters, CompressionLevel, CompressionParameters,
    ///     RowMatchFinderMode,
    /// };
    /// use structured_zstd::decoding::FrameDecoder;
    ///
    /// let data = b"a row or a chain, the frame decodes the same ".repeat(2000);
    /// let chain = CompressionParameters::builder(CompressionLevel::Level(7))
    ///     .row_match_finder(RowMatchFinderMode::Disable)
    ///     .build()
    ///     .unwrap();
    /// let frame = compress_with_parameters(&data[..], &chain);
    /// let mut decoded = Vec::with_capacity(data.len());
    /// FrameDecoder::new()
    ///     .decode_all_to_vec(&frame, &mut decoded)
    ///     .unwrap();
    /// assert_eq!(decoded, data);
    /// ```
    pub fn row_match_finder(mut self, mode: RowMatchFinderMode) -> Self {
        self.row_match_finder = mode;
        self
    }

    /// Decide whether literals are entropy-coded, overriding the level's own
    /// choice. C `ZSTD_c_literalCompressionMode`.
    ///
    /// ```rust
    /// use structured_zstd::encoding::{
    ///     compress_with_parameters, CompressionLevel, CompressionParameters,
    ///     LiteralCompressionMode,
    /// };
    ///
    /// // Literal-heavy input: 32 distinct symbols and nothing for the match
    /// // finder to repeat, so only entropy-coding the literals shrinks it.
    /// let text: Vec<u8> = (0..8192u32)
    ///     .map(|i| b'a' + (i.wrapping_mul(2_654_435_761) >> 27) as u8)
    ///     .collect();
    /// // Level -3 stores literals raw by default; asking for compression
    /// // makes the frame smaller on input like this.
    /// let compressed_literals = CompressionParameters::builder(CompressionLevel::Level(-3))
    ///     .literal_compression(LiteralCompressionMode::Enable)
    ///     .build()
    ///     .unwrap();
    /// let plain = compress_with_parameters(
    ///     &text[..],
    ///     &CompressionParameters::builder(CompressionLevel::Level(-3)).build().unwrap(),
    /// );
    /// let coded = compress_with_parameters(&text[..], &compressed_literals);
    /// assert!(coded.len() < plain.len());
    /// ```
    pub fn literal_compression(mut self, mode: LiteralCompressionMode) -> Self {
        self.literal_compression = mode;
        self
    }

    /// Override the maximum back-reference distance (`log2`). C
    /// `ZSTD_c_windowLog`.
    pub fn window_log(mut self, value: u32) -> Self {
        self.window_log = Some(value);
        self
    }

    /// Override the match-finder hash table size (`log2`). C `ZSTD_c_hashLog`.
    pub fn hash_log(mut self, value: u32) -> Self {
        self.hash_log = Some(value);
        self
    }

    /// Override the match-finder chain table size (`log2`). C `ZSTD_c_chainLog`.
    pub fn chain_log(mut self, value: u32) -> Self {
        self.chain_log = Some(value);
        self
    }

    /// Override the search-attempts count (`log2`). C `ZSTD_c_searchLog`.
    pub fn search_log(mut self, value: u32) -> Self {
        self.search_log = Some(value);
        self
    }

    /// Override the minimum match length in bytes. C `ZSTD_c_minMatch`.
    pub fn min_match(mut self, value: u32) -> Self {
        self.min_match = Some(value);
        self
    }

    /// Override the "good enough" target match length. C `ZSTD_c_targetLength`.
    pub fn target_length(mut self, value: u32) -> Self {
        self.target_length = Some(value);
        self
    }

    /// Override the match-finder [`Strategy`]. C `ZSTD_c_strategy`.
    pub fn strategy(mut self, value: Strategy) -> Self {
        self.strategy = Some(value);
        self
    }

    /// Enable or disable long-distance matching. C
    /// `ZSTD_c_enableLongDistanceMatching`. Off at every level preset.
    /// This is the explicit activation toggle; the `ldm_*` knob setters
    /// also enable LDM implicitly. The flag is plain last-write-wins, so
    /// a trailing `enable_long_distance_matching(false)` disables LDM even
    /// if an earlier `ldm_*` call set a knob (the knob is then ignored at
    /// [`build`](Self::build)).
    pub fn enable_long_distance_matching(mut self, enable: bool) -> Self {
        self.enable_ldm = enable;
        self
    }

    /// Override the LDM hash table size (`log2`). C `ZSTD_c_ldmHashLog`.
    /// Implies [`Self::enable_long_distance_matching(true)`](Self::enable_long_distance_matching).
    pub fn ldm_hash_log(mut self, value: u32) -> Self {
        self.enable_ldm = true;
        self.ldm.hash_log = Some(value);
        self
    }

    /// Override the LDM minimum match length. C `ZSTD_c_ldmMinMatch`.
    /// Implies [`Self::enable_long_distance_matching(true)`](Self::enable_long_distance_matching).
    pub fn ldm_min_match(mut self, value: u32) -> Self {
        self.enable_ldm = true;
        self.ldm.min_match = Some(value);
        self
    }

    /// Override the LDM bucket size (`log2`). C `ZSTD_c_ldmBucketSizeLog`.
    /// Implies [`Self::enable_long_distance_matching(true)`](Self::enable_long_distance_matching).
    pub fn ldm_bucket_size_log(mut self, value: u32) -> Self {
        self.enable_ldm = true;
        self.ldm.bucket_size_log = Some(value);
        self
    }

    /// Override the LDM hash-insertion rate (`log2`). C `ZSTD_c_ldmHashRateLog`.
    /// Implies [`Self::enable_long_distance_matching(true)`](Self::enable_long_distance_matching).
    pub fn ldm_hash_rate_log(mut self, value: u32) -> Self {
        self.enable_ldm = true;
        self.ldm.hash_rate_log = Some(value);
        self
    }

    /// Validate every set knob against [`CParameter::bounds`] and
    /// produce the resolved [`CompressionParameters`].
    ///
    /// # Errors
    ///
    /// Returns [`ParameterError::OutOfBounds`] for the first knob whose
    /// value falls outside its inclusive range.
    pub fn build(self) -> Result<CompressionParameters, ParameterError> {
        check(CParameter::WindowLog, self.window_log)?;
        check(CParameter::HashLog, self.hash_log)?;
        check(CParameter::ChainLog, self.chain_log)?;
        check(CParameter::SearchLog, self.search_log)?;
        check(CParameter::MinMatch, self.min_match)?;
        check(CParameter::TargetLength, self.target_length)?;
        if let Some(s) = self.strategy {
            check(CParameter::Strategy, Some(s.ordinal()))?;
        }
        let ldm = if self.enable_ldm {
            check(CParameter::LdmHashLog, self.ldm.hash_log)?;
            check(CParameter::LdmMinMatch, self.ldm.min_match)?;
            check(CParameter::LdmBucketSizeLog, self.ldm.bucket_size_log)?;
            check(CParameter::LdmHashRateLog, self.ldm.hash_rate_log)?;
            Some(self.ldm)
        } else {
            None
        };
        Ok(CompressionParameters {
            level: self.level,
            overrides: ParamOverrides {
                // `window_log` is bounds-checked at <= 30, so the cast is lossless.
                window_log: self.window_log.map(|v| v as u8),
                hash_log: self.hash_log,
                chain_log: self.chain_log,
                search_log: self.search_log,
                min_match: self.min_match,
                target_length: self.target_length,
                strategy: self.strategy,
                ldm,
                literal_compression: self.literal_compression,
                row_match_finder: self.row_match_finder,
            },
        })
    }
}

/// Validate one optional knob against its bounds.
fn check(parameter: CParameter, value: Option<u32>) -> Result<(), ParameterError> {
    if let Some(value) = value {
        let bounds = parameter.bounds();
        let value = i64::from(value);
        if !bounds.contains(value) {
            return Err(ParameterError::OutOfBounds {
                parameter,
                value,
                bounds,
            });
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests;