structured_zstd/
lib.rs

1//! Pure-Rust Zstandard codec with a production-grade decoder, dictionary
2//! handle reuse, and an actively-improved encoder.
3//!
4//! The crate ships:
5//!
6//! * [`decoding`] — [RFC 8878] decoder ([`decoding::StreamingDecoder`],
7//!   [`decoding::FrameDecoder`], dictionary-backed paths via
8//!   [`decoding::DictionaryHandle`]).
9//! * [`encoding`] — frame compressor, streaming encoder, named and numeric
10//!   compression levels ([`encoding::CompressionLevel`]).
11//! * [`dictionary`] (feature `dict_builder`) — COVER / FastCOVER training
12//!   plus raw-to-finalized dictionary helpers.
13//!
14//! No FFI, no cmake, no system zstd. `no_std` builds are supported by
15//! disabling the default `std` feature.
16//!
17//! The packaged README is included below for the docs.rs landing page; the
18//! API anchors above link straight into the per-module documentation.
19//!
20//! [RFC 8878]: https://www.rfc-editor.org/rfc/rfc8878
21// Keep crate docs aligned with the packaged README via the crate-local symlink in `zstd/README.md`.
22#![doc = include_str!("../README.md")]
23#![no_std]
24#![deny(trivial_casts, trivial_numeric_casts, rust_2018_idioms)]
25#![cfg_attr(docsrs, feature(doc_cfg))]
26
27#[cfg(feature = "std")]
28extern crate std;
29
30#[cfg(not(feature = "rustc-dep-of-std"))]
31extern crate alloc;
32
33#[cfg(feature = "std")]
34pub(crate) const VERBOSE: bool = false;
35
36macro_rules! vprintln {
37    ($($x:expr),*) => {
38        #[cfg(feature = "std")]
39        if crate::VERBOSE {
40            std::println!($($x),*);
41        }
42    }
43}
44
45mod bit_io;
46mod common;
47pub mod decoding;
48#[cfg(feature = "dict_builder")]
49#[cfg_attr(docsrs, doc(cfg(feature = "dict_builder")))]
50pub mod dictionary;
51pub mod encoding;
52mod histogram;
53
54#[cfg(feature = "lsm")]
55#[cfg_attr(docsrs, doc(cfg(feature = "lsm")))]
56pub mod skippable;
57
58pub(crate) mod blocks;
59
60#[cfg(feature = "fuzz_exports")]
61pub mod fse;
62#[cfg(feature = "fuzz_exports")]
63pub mod huff0;
64
65#[cfg(not(feature = "fuzz_exports"))]
66pub(crate) mod fse;
67#[cfg(not(feature = "fuzz_exports"))]
68pub(crate) mod huff0;
69
70#[cfg(feature = "std")]
71pub mod io_std;
72
73#[cfg(feature = "std")]
74pub use io_std as io;
75
76#[cfg(not(feature = "std"))]
77pub mod io_nostd;
78
79#[cfg(not(feature = "std"))]
80pub use io_nostd as io;
81
82#[cfg(test)]
83mod tests;
84
85/// Re-exports of internal types used by benchmarks.
86///
87/// Gated behind the `bench_internals` feature so normal builds do not
88/// widen the public API surface. Not part of the stable API; items may
89/// change or disappear without notice.
90#[cfg(feature = "bench_internals")]
91#[doc(hidden)]
92pub mod testing {
93    pub use crate::bit_io::BitReaderReversed;
94
95    /// Bench-only facade for the decoder wildcopy implementation.
96    ///
97    /// # Safety
98    /// Caller must satisfy the same safety contract as
99    /// `decoding::copy_bytes_overshooting_for_bench`.
100    #[inline(always)]
101    pub unsafe fn copy_bytes_overshooting_for_bench(
102        src: (*const u8, usize),
103        dst: (*mut u8, usize),
104        copy_at_least: usize,
105    ) {
106        // Keep decoder internals crate-private and expose only this bench shim.
107        unsafe { crate::decoding::copy_bytes_overshooting_for_bench(src, dst, copy_at_least) };
108    }
109
110    /// Maximum block size per RFC 8878 §3.1.1.2.3 (128 KiB).
111    /// Exposed for parity tests that feed exactly-one-block chunks
112    /// into the donor splitter comparator.
113    pub const MAX_BLOCK_SIZE: u32 = crate::common::MAX_BLOCK_SIZE;
114
115    /// Run our donor-port block splitter on a 128 KB chunk.
116    ///
117    /// `split_level` mirrors donor `ZSTD_splitBlock(level)`: `0` selects
118    /// the borders heuristic (`ZSTD_splitBlock_fromBorders`), `1..=4`
119    /// select `ZSTD_splitBlock_byChunks` at the corresponding sampling
120    /// level. Returns the split position (or `block.len()` if no split).
121    ///
122    /// Crate-internal facade for the donor-parity comparator test —
123    /// the underlying functions stay `fn` so they don't widen the
124    /// stable API surface.
125    pub fn block_splitter_decision(block: &[u8], split_level: usize) -> usize {
126        crate::encoding::frame_compressor::block_splitter_decision_for_bench(block, split_level)
127    }
128}
129
130/// SIMD wildcopy overshoot slack carried by every decoder backend.
131/// Mirrors donor zstd's `WILDCOPY_OVERLENGTH` (16 bytes). Public so
132/// callers sizing an output slice for
133/// [`crate::decoding::FrameDecoder::decode_to_slice_trusted`] can size
134/// `frame_content_size + WILDCOPY_OVERLENGTH` without duplicating
135/// the constant.
136pub const WILDCOPY_OVERLENGTH: usize = crate::decoding::buffer_backend::WILDCOPY_OVERLENGTH;
structured_zstd/lib.rs

structured_zstd/
lib.rs
