Skip to main content

Crate hex_turbo

Crate hex_turbo 

Source
Expand description

§Hex Turbo

A hex codec that peaks past 150 GiB/s, with every vector load and store of its SIMD kernels proven by the Kani model checker.

The best kernel is picked per call: AVX-512 VBMI or AVX2 on x86 via runtime detection, and a scalar kernel in safe Rust everywhere else. no_std is supported.

§Usage

use hex_turbo::LOWER_CASE;

let encoded = LOWER_CASE.encode(b"Hello world");
assert_eq!(encoded, "48656c6c6f20776f726c64");
assert_eq!(LOWER_CASE.decode(&encoded).unwrap(), b"Hello world");

The slice APIs write into a caller-provided buffer and need no allocator:

use hex_turbo::LOWER_CASE;

let mut output = [0u8; 64];
let len = LOWER_CASE.encode_slice(b"Raw bytes", &mut output).unwrap();
assert_eq!(&output[..len], b"526177206279746573");

UPPER_CASE encodes to [0-9A-F]; both engines decode either case.

§Feature Flags

FeatureDefaultDescription
stdYesString/Vec APIs. The slice APIs and every SIMD kernel work without it.
unstableNoExposes the raw kernels (encode_avx2, decode_avx512_vbmi, …), compiled on x86; each returns None where the CPU lacks it.

§Selecting a Backend

On x86 both SIMD kernels are compiled in, and the best one this CPU supports is picked at runtime (CPUID, read once). Target features enabled at compile time are used without detection:

RUSTFLAGS='-C target-cpu=native' cargo build
RUSTFLAGS='-C target-feature=+avx512f,+avx512bw,+avx512vbmi' cargo build

The kernels themselves are safe code: a kernel is entered only with a token that exists where its CPU features are enabled or detected, and every vector load and store moves a whole array of exactly its width. On non-x86 targets the crate is #![forbid(unsafe_code)].

§Safety & Verification

The README lists exactly what the Kani proofs, tests and fuzzing cover, and what they don’t.

Structs§

Engine
A stateless hex encoder/decoder.

Enums§

Error
Errors returned by the encode and decode entry points.

Constants§

LOWER_CASE
RFC 4648 §8 alphabet, encoding to [0-9a-f].
UPPER_CASE
RFC 4648 §8 alphabet, encoding to [0-9A-F].

Functions§

decodestd
Decodes input, in either case.
encodestd
Encodes input with LOWER_CASE.
encode_upperstd
Encodes input with UPPER_CASE.