Skip to main content

hex_turbo/
lib.rs

1//! # Hex Turbo
2//!
3//! A hex codec that peaks past 150 GiB/s, with every vector load and store of
4//! its SIMD kernels proven by the [Kani](https://github.com/model-checking/kani)
5//! model checker.
6//!
7//! The best kernel is picked per call: **AVX-512 VBMI** or **AVX2** on x86 via
8//! runtime detection, and a scalar kernel in safe Rust everywhere else.
9//! `no_std` is supported.
10//!
11//! ## Usage
12//!
13//! ```rust
14//! # #[cfg(feature = "std")]
15//! # {
16//! use hex_turbo::LOWER_CASE;
17//!
18//! let encoded = LOWER_CASE.encode(b"Hello world");
19//! assert_eq!(encoded, "48656c6c6f20776f726c64");
20//! assert_eq!(LOWER_CASE.decode(&encoded).unwrap(), b"Hello world");
21//! # }
22//! ```
23//!
24//! The slice APIs write into a caller-provided buffer and need no allocator:
25//!
26//! ```rust
27//! use hex_turbo::LOWER_CASE;
28//!
29//! let mut output = [0u8; 64];
30//! let len = LOWER_CASE.encode_slice(b"Raw bytes", &mut output).unwrap();
31//! assert_eq!(&output[..len], b"526177206279746573");
32//! ```
33//!
34//! [`UPPER_CASE`] encodes to `[0-9A-F]`; both engines decode either case.
35//!
36//! ## Feature Flags
37//!
38//! | Feature | Default | Description |
39//! |---------|---------|-------------|
40//! | **`std`** | Yes | `String`/`Vec` APIs. The slice APIs and every SIMD kernel work without it. |
41//! | **`unstable`** | No | Exposes the raw kernels (`encode_avx2`, `decode_avx512_vbmi`, …), compiled on x86; each returns `None` where the CPU lacks it. |
42//!
43//! ## Selecting a Backend
44//!
45//! On x86 both SIMD kernels are compiled in, and the best one this CPU
46//! supports is picked at runtime (CPUID, read once). Target features enabled
47//! at compile time are used without detection:
48//!
49//! ```text
50//! RUSTFLAGS='-C target-cpu=native' cargo build
51//! RUSTFLAGS='-C target-feature=+avx512f,+avx512bw,+avx512vbmi' cargo build
52//! ```
53//!
54//! The kernels themselves are safe code: a kernel is entered only with a
55//! token that exists where its CPU features are enabled or detected, and every
56//! vector load and store moves a whole array of exactly its width. On non-x86
57//! targets the crate is `#![forbid(unsafe_code)]`.
58//!
59//! ## Safety & Verification
60//!
61//! The [README](https://crates.io/crates/hex-turbo) lists exactly what the
62//! Kani proofs, tests and fuzzing cover, and what they don't.
63
64#![cfg_attr(not(any(feature = "std", test)), no_std)]
65#![cfg_attr(
66    not(any(target_arch = "x86", target_arch = "x86_64")),
67    forbid(unsafe_code)
68)]
69#![cfg_attr(docsrs, feature(doc_cfg))]
70#![forbid(elided_lifetimes_in_paths)]
71#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
72
73#[cfg(all(doctest, feature = "std"))]
74#[doc = include_str!("../README.md")]
75struct ReadmeDoctests;
76
77mod engine;
78mod error;
79mod scalar;
80
81#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
82mod cpu;
83#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
84mod simd;
85
86pub use engine::{Engine, LOWER_CASE, UPPER_CASE};
87pub use error::Error;
88
89pub(crate) use engine::Config;
90
91/// Encodes `input` with [`LOWER_CASE`].
92#[cfg(feature = "std")]
93#[inline]
94pub fn encode<T: AsRef<[u8]>>(input: T) -> String {
95    LOWER_CASE.encode(input)
96}
97
98/// Encodes `input` with [`UPPER_CASE`].
99#[cfg(feature = "std")]
100#[inline]
101pub fn encode_upper<T: AsRef<[u8]>>(input: T) -> String {
102    UPPER_CASE.encode(input)
103}
104
105/// Decodes `input`, in either case.
106///
107/// # Errors
108///
109/// [`Error::InvalidLength`] or [`Error::InvalidCharacter`] if `input` is not
110/// valid hex.
111#[cfg(feature = "std")]
112#[inline]
113pub fn decode<T: AsRef<[u8]>>(input: T) -> Result<Vec<u8>, Error> {
114    LOWER_CASE.decode(input)
115}