Skip to main content

zxc/
lib.rs

1// SPDX-License-Identifier: BSD-3-Clause
2/*
3 * ZXC - High-performance lossless compression
4 *
5 * Copyright (c) Bertrand Lebonnois and contributors.
6 */
7
8#![doc = include_str!("../README.md")]
9#![warn(missing_docs)]
10#![warn(rust_2018_idioms)]
11
12pub use zxc_sys::{
13    ZXC_ERROR_BAD_BLOCK_SIZE,
14    ZXC_ERROR_BAD_BLOCK_TYPE,
15    ZXC_ERROR_BAD_CHECKSUM,
16    ZXC_ERROR_BAD_HEADER,
17    ZXC_ERROR_BAD_MAGIC,
18    ZXC_ERROR_BAD_OFFSET,
19    ZXC_ERROR_BAD_VERSION,
20    ZXC_ERROR_CORRUPT_DATA,
21    ZXC_ERROR_DST_TOO_SMALL,
22    ZXC_ERROR_IO,
23    ZXC_ERROR_MEMORY,
24    ZXC_ERROR_NULL_INPUT,
25    ZXC_ERROR_OVERFLOW,
26    ZXC_ERROR_SRC_TOO_SMALL,
27    ZXC_LEVEL_BALANCED,
28    ZXC_LEVEL_COMPACT,
29    ZXC_LEVEL_DEFAULT,
30    ZXC_LEVEL_DENSITY,
31    ZXC_LEVEL_FAST,
32    ZXC_LEVEL_FASTEST,
33    ZXC_LEVEL_ULTRA,
34    // Error codes
35    ZXC_OK,
36    ZXC_VERSION_MAJOR,
37    ZXC_VERSION_MINOR,
38    ZXC_VERSION_PATCH,
39};
40
41// =============================================================================
42// Compression Levels
43// =============================================================================
44
45/// Compression level presets.
46///
47/// Higher levels produce smaller output but compress more slowly.
48/// Decompression speed is similar across most levels; levels 6-7 sit a notch
49/// below the others because Huffman-coded literals (and, at level 7, tokens)
50/// add a per-block decode cost relative to RAW/RLE literals.
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
52#[repr(i32)]
53pub enum Level {
54    /// Fastest compression, best for real-time applications (level 1)
55    Fastest = 1,
56
57    /// Fast compression, good for real-time applications (level 2)
58    Fast = 2,
59
60    /// Recommended default: ratio > LZ4, decode speed > LZ4 (level 3)
61    #[default]
62    Default = 3,
63
64    /// Good ratio, good decode speed (level 4)
65    Balanced = 4,
66
67    /// High density: storage / firmware / assets (level 5)
68    Compact = 5,
69
70    /// High density: Huffman-coded literals on top of COMPACT plus a
71    /// price-based optimal LZ77 parser (level 6).
72    Density = 6,
73
74    /// Maximum density: Huffman-coded literals *and* sequence tokens with a
75    /// deep parse. Slowest compression, best ratio (level 7 / ULTRA).
76    Ultra = 7,
77}
78
79impl Level {
80    /// Returns all available compression levels.
81    pub fn all() -> &'static [Level] {
82        &[
83            Level::Fastest,
84            Level::Fast,
85            Level::Default,
86            Level::Balanced,
87            Level::Compact,
88            Level::Density,
89            Level::Ultra,
90        ]
91    }
92}
93
94impl From<Level> for i32 {
95    fn from(level: Level) -> i32 {
96        level as i32
97    }
98}
99
100// =============================================================================
101// Compression Options
102// =============================================================================
103
104/// Options for compression operations.
105#[derive(Debug, Clone)]
106pub struct CompressOptions {
107    /// Compression level (default: `Level::Default`)
108    pub level: Level,
109
110    /// Write checksums for data integrity (default: `false`)
111    pub checksum: bool,
112
113    /// Enable seek table for random-access decompression (default: `false`)
114    pub seekable: bool,
115
116    /// Pre-trained dictionary content (default: `None`).
117    ///
118    /// Set to the raw dictionary content bytes (as returned by
119    /// [`train_dict`] or [`dict_load`]). The decoder must be given the same
120    /// dictionary to decompress the resulting archive.
121    pub dict: Option<Vec<u8>>,
122
123    /// Shared literal Huffman table (default: `None`; ignored without `dict`).
124    ///
125    /// The 128-byte packed code-lengths table from [`train_dict_huf`] or
126    /// [`dict_huf`]. Becomes part of the archive's dictionary binding: the
127    /// decoder must be given the same (dict, table) pair.
128    pub dict_huf: Option<Vec<u8>>,
129}
130
131impl Default for CompressOptions {
132    fn default() -> Self {
133        Self {
134            level: Level::Default,
135            checksum: false,
136            seekable: false,
137            dict: None,
138            dict_huf: None,
139        }
140    }
141}
142
143impl CompressOptions {
144    /// Create options with the specified compression level.
145    pub fn with_level(level: Level) -> Self {
146        Self {
147            level,
148            ..Default::default()
149        }
150    }
151
152    /// Writes checksums for data integrity.
153    pub fn with_checksum(mut self) -> Self {
154        self.checksum = true;
155        self
156    }
157
158    /// Writes no checksums, which is the default.
159    #[deprecated(note = "checksums are off by default: drop this call")]
160    pub fn without_checksum(mut self) -> Self {
161        self.checksum = false;
162        self
163    }
164
165    /// Enable seek table for random-access decompression.
166    pub fn with_seekable(mut self) -> Self {
167        self.seekable = true;
168        self
169    }
170
171    /// Attach a pre-trained dictionary (raw content bytes).
172    pub fn with_dict(mut self, dict: impl Into<Vec<u8>>) -> Self {
173        self.dict = Some(dict.into());
174        self
175    }
176
177    /// Attach the dictionary's shared literal Huffman table (128 bytes).
178    pub fn with_dict_huf(mut self, huf: impl Into<Vec<u8>>) -> Self {
179        self.dict_huf = Some(huf.into());
180        self
181    }
182
183    /// Attach a [`Dictionary`] (content + shared table) in one call.
184    pub fn with_dictionary(mut self, dictionary: &Dictionary) -> Self {
185        self.dict = Some(dictionary.content().to_vec());
186        self.dict_huf = Some(dictionary.huf().to_vec());
187        self
188    }
189}
190
191// =============================================================================
192// Decompression Options
193// =============================================================================
194
195/// Options for decompression operations.
196#[derive(Debug, Clone)]
197pub struct DecompressOptions {
198    /// Verify checksums. `None` (the default) verifies them when the archive
199    /// carries them, except on the block API, whose blocks cannot say so: see
200    /// [`Dctx::decompress_block`].
201    pub verify_checksum: Option<bool>,
202
203    /// Pre-trained dictionary content (default: `None`).
204    ///
205    /// Must match the dictionary used at compression time. Required to
206    /// decompress an archive that was produced with a dictionary.
207    pub dict: Option<Vec<u8>>,
208
209    /// Shared literal Huffman table (default: `None`; ignored without `dict`).
210    ///
211    /// Must match the table used at compression time (the archive's dict_id
212    /// binds the (dict, table) pair).
213    pub dict_huf: Option<Vec<u8>>,
214}
215
216impl Default for DecompressOptions {
217    fn default() -> Self {
218        Self {
219            verify_checksum: None,
220            dict: None,
221            dict_huf: None,
222        }
223    }
224}
225
226impl DecompressOptions {
227    /// Create options that skip checksum verification.
228    pub fn skip_checksum() -> Self {
229        Self {
230            verify_checksum: Some(false),
231            ..Default::default()
232        }
233    }
234
235    /// Attach a pre-trained dictionary (raw content bytes).
236    pub fn with_dict(mut self, dict: impl Into<Vec<u8>>) -> Self {
237        self.dict = Some(dict.into());
238        self
239    }
240
241    /// Attach the dictionary's shared literal Huffman table (128 bytes).
242    pub fn with_dict_huf(mut self, huf: impl Into<Vec<u8>>) -> Self {
243        self.dict_huf = Some(huf.into());
244        self
245    }
246
247    /// Attach a [`Dictionary`] (content + shared table) in one call.
248    pub fn with_dictionary(mut self, dictionary: &Dictionary) -> Self {
249        self.dict = Some(dictionary.content().to_vec());
250        self.dict_huf = Some(dictionary.huf().to_vec());
251        self
252    }
253
254    /// The setting for a frame, whose header says whether it carries checksums.
255    pub(crate) fn verify_frame(&self) -> bool {
256        self.verify_checksum.unwrap_or(true)
257    }
258}
259
260// =============================================================================
261// Submodules
262// =============================================================================
263
264mod ctx;
265mod dict;
266mod error;
267mod file;
268mod oneshot;
269mod pstream;
270pub mod seekable;
271mod stdio;
272
273pub use dict::{
274    Dictionary, dict_get_id, dict_huf, dict_id, dict_load, dict_save, get_dict_id, train_dict,
275    train_dict_huf,
276};
277pub use zxc_sys::{ZXC_DICT_SIZE_MAX, ZXC_HUF_TABLE_SIZE};
278
279/// The dictionary content and shared table to attach to a C context, as slices
280/// borrowed from the caller's options: empty means absent, and a table only
281/// accompanies a dictionary, then in `ZXC_HUF_TABLE_SIZE` bytes. Slices rather
282/// than pointers keep the borrow checker in charge of the FFI call's lifetime.
283pub(crate) fn dict_parts<'a>(
284    dict: Option<&'a [u8]>,
285    dict_huf: Option<&'a [u8]>,
286) -> Result<(&'a [u8], &'a [u8])> {
287    let content: &[u8] = dict.unwrap_or(&[]);
288    let table: &[u8] = match dict_huf {
289        // A wrong length is a programming error, dictionary or not.
290        Some(h) if !h.is_empty() => {
291            if h.len() != ZXC_HUF_TABLE_SIZE {
292                return Err(Error::BadHufTable);
293            }
294            if content.is_empty() { &[] } else { h }
295        }
296        _ => &[],
297    };
298    Ok((content, table))
299}
300
301/// The C pointer for a dictionary slice: NULL when the slice is empty.
302pub(crate) fn dict_ptr(slice: &[u8]) -> *const std::ffi::c_void {
303    if slice.is_empty() {
304        std::ptr::null()
305    } else {
306        slice.as_ptr() as *const std::ffi::c_void
307    }
308}
309
310pub use ctx::{Cctx, Dctx, compress_block_bound, decompress_block_bound};
311pub use error::{Error, Result};
312pub use file::{
313    StreamCompressOptions, StreamDecompressOptions, StreamError, StreamResult, compress_file,
314    compress_file_with_options, decompress_file, decompress_file_with_options,
315    file_decompressed_size,
316};
317pub use oneshot::{
318    FrameInfo, compress, compress_bound, compress_to, compress_with_options, decompress,
319    decompress_to, decompress_with_options, decompressed_size, default_level, frame_info,
320    max_level, min_level, runtime_codename, runtime_version, version, version_string,
321};
322pub use pstream::{CStream, CStreamProgress, DStream, DStreamProgress};
323pub use seekable::{Seekable, seek_table_size, write_seek_table};
324pub use stdio::{Decoder, Encoder, detect_zxc};