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