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
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// The `simd` feature is nightly-only, and deliberately the only thing in this
// crate that is: see `src/simd.rs` and the README section it points at.
//! # base85n
//!
//! A Rust implementation of Base85N, an encoding for data that has to be
//! embedded in a text-based format -- JSON, XML, HTML, configuration files --
//! where Base64 would otherwise be used and the size or the cleanliness of the
//! result matters. It has
//! a 4-byte-to-5-character Base85 core, an adaptive Dynamic Passthrough (DP)
//! mode for partially human-readable, 1:1-efficiency output on favorable
//! input, and a Fill mode that carries a run of up to 2048 identical bytes in
//! five characters -- or a short zero run together with the two bytes beside
//! it. See `spec/base85n-v0.5.0.md` in the repository for the full
//! specification.
//!
//! ```
//! let data = b"hello, world!";
//! let encoded = base85n::encode(data);
//! let decoded = base85n::decode(&encoded).unwrap();
//! assert_eq!(decoded, data);
//! ```
//! The crate also exports a C ABI (see [`ffi`]) so that callers in other
//! languages can link this implementation instead of a hand-written one;
//! `cargo build --release` produces `libbase85n.so`/`.dylib`/`.dll` and
//! `libbase85n.a` alongside the Rust library.
/// Alphabet-N, the R-Set and the donor profiles of spec section 4. They are
/// public because a binding layer -- the `python/` crate, say -- has to be able
/// to hand them to its own callers without a second copy of section 4.
pub use ;
pub use DecodeError;
/// Encode `data` as a Base85N string.
///
/// This never fails: any byte sequence, including the empty sequence, has
/// a valid Base85N encoding.
/// Encode `data` on up to `threads` threads, producing exactly what
/// [`encode`] produces.
///
/// Encoding is the slower direction, and it is the direction that
/// parallelises: signals are self-describing and segment boundaries are
/// decided by the data, so encoders started at different offsets converge on
/// the same decisions and their output can be spliced. There is no chunk-size
/// parameter in the format and no second canonical form -- `threads` changes
/// how the work is divided and nothing about the result. Spec section 11.3
/// describes the procedure and what bounds it.
///
/// Inputs below a couple of megabytes are encoded on the calling thread: the
/// seam repair costs more than the split saves.
/// The parallel encoder with the chunking handed in, for `fuzz/` only.
///
/// See `encode::__fuzz_encode_parallel_chunked`: the seam is what the parallel
/// encoder has to get right, and a megabyte of chunk is what makes it expensive
/// for a fuzzer to reach. Behind the `fuzzing` feature, which no shipped build
/// enables.
/// Decode a Base85N string `s` back into the original bytes.
///
/// # Errors
///
/// Returns a [`DecodeError`] if `s` is not a well-formed Base85N string;
/// see that type's variants for the specific error conditions detected.