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};