embark_codec/lib.rs
1//! The compression layer of the `embark` toolkit: one interface over
2//! DEFLATE, LZ4, Snappy, Zstandard and LZMA1, keyed by the
3//! [`CodecId`](embark_format::CodecId) that `embark-format` writes into
4//! every entry header.
5//!
6//! There are two ways in. [`compress`] and [`decompress`] take a `CodecId`
7//! and dispatch at runtime, which is what a decoder reading an untrusted
8//! entry needs. The unit structs — [`Store`], [`Deflate`], [`Lz4`],
9//! [`Snappy`], [`Zstd`], [`Lzma`] — are the direct-call form for a caller
10//! that already knows its codec, and [`compress_best_in`] runs the `auto`
11//! family's codec selection: compress with one [`AutoTier`]'s worth of
12//! candidates and keep the smallest output.
13//!
14//! Every codec is pure Rust with no C dependency, so the whole crate builds
15//! for `no_std` targets with only `alloc`.
16//!
17//! # Features
18//!
19//! Each codec has its own feature and none are on by default, so a build
20//! links only the formats it names. `enc` compiles the compressing half and
21//! `dec` the decompressing half; a consumer that only reads embedded files
22//! needs `dec` plus the codecs its entries actually use.
23//!
24//! `parallel-encode` is separate from all of those: it does not change what
25//! is compiled, only how fast `enc` runs, by letting the encoder use more
26//! than one thread. See [`parallel`].
27//!
28//! A codec that was not compiled in is not an error at the format level:
29//! [`decompress`] reports [`Error::UnknownCodec`](embark_format::Error::UnknownCodec)
30//! for it, and [`compress`] falls back to [`CodecId::Store`](embark_format::CodecId::Store)
31//! so encoding never fails.
32//!
33//! # Example
34//!
35//! ```
36//! # #[cfg(all(feature = "enc", feature = "dec", feature = "deflate"))] {
37//! use embark_format::CodecId;
38//!
39//! let data = b"embark embark embark embark".repeat(8);
40//! let packed = embark_codec::compress(CodecId::Deflate, &data);
41//! assert!(packed.len() < data.len());
42//!
43//! let back = embark_codec::decompress(CodecId::Deflate, &packed, data.len())?;
44//! assert_eq!(back, data);
45//! # }
46//! # Ok::<(), embark_format::Error>(())
47//! ```
48
49// docs.rs builds with `--cfg docsrs` (see each manifest's
50// `[package.metadata.docs.rs]`), which turns this on and makes rustdoc label
51// every item with the feature that gates it. Nearly all of this API is
52// behind one, so without the label the rendered docs read as though it were
53// all unconditional. Inert on stable, where `docsrs` is never set.
54#![cfg_attr(docsrs, feature(doc_cfg))]
55#![cfg_attr(not(feature = "std"), no_std)]
56
57#[cfg(feature = "alloc")]
58extern crate alloc;
59
60// A codec's implementation is only reachable through `enc` or `dec`. With
61// neither, the module would compile to dead code, so it is not compiled at
62// all; the `Codec` handle it names stays available either way.
63mod best;
64mod codec;
65#[cfg(all(feature = "deflate", any(feature = "enc", feature = "dec")))]
66mod deflate;
67mod dispatch;
68#[cfg(all(feature = "lz4", any(feature = "enc", feature = "dec")))]
69mod lz4;
70#[cfg(all(feature = "lzma", any(feature = "enc", feature = "dec")))]
71mod lzma;
72// Build-time only: the encoder's thread budget. Nothing under `dec` reaches
73// it, so a consumer's binary never links it.
74#[cfg(feature = "enc")]
75pub mod parallel;
76#[cfg(all(feature = "snappy", any(feature = "enc", feature = "dec")))]
77mod snappy;
78mod store;
79#[cfg(all(feature = "zstd", any(feature = "enc", feature = "dec")))]
80mod zstd;
81
82#[cfg(feature = "deflate")]
83pub use codec::Deflate;
84#[cfg(feature = "lz4")]
85pub use codec::Lz4;
86#[cfg(feature = "lzma")]
87pub use codec::Lzma;
88#[cfg(feature = "snappy")]
89pub use codec::Snappy;
90#[cfg(feature = "zstd")]
91pub use codec::Zstd;
92pub use codec::{Codec, Store};
93
94#[cfg(feature = "enc")]
95pub use best::{AutoTier, compress_best, compress_best_in};
96#[cfg(feature = "enc")]
97pub use dispatch::compress;
98#[cfg(feature = "dec")]
99pub use dispatch::decompress;