Crate fashex 

fashex - fast hexadecimal encoding and decoding

Hexadecimal string encoding and decoding with best-effort SIMD acceleration.

Highlights

• Best-effort SIMD acceleration.
• Small, focused public APIs.

Performance

This crate is comparable in performance to hex-simd, slightly better than const-hex, and far superior to faster-hex.

For benchmark results, please refer to BENCHMARK.md.

Usage

Adds fashex as a dependency in your Cargo.toml:

[dependencies]
fashex = "*" # Please specify the latest version instead of "*"!

For detailed usage instructions, please refer to the documentation.

Features

• alloc (default)

  Enables Rust alloc crate support.

• std (default)

  Enables Rust standard library support.

• nightly

  Enables features that require nightly Rust.

• portable-simd

  Enables portable SIMD acceleration support via unstable core::simd, which may help improve performance on platforms other than x86, x86_64, aarch64 (arm64ec), loongarch32 and loongarch64.

  Notes: this requires nightly Rust.

• experimental-loongarch-simd

  Enables experimental SIMD acceleration via Loongson SIMD eXtention or Loongson Advanced SIMD eXtention.

  Notes: this requires nightly Rust.

• runtime-cpu-detection (default)

  Enables CPU features detection at runtime.

no_std support

This crate is no_std-friendly, just disable the default features:

[dependencies]
fashex = { version = "*", default-features = false, features = [] } # Please specify the latest version instead of "*"!

Some notes:

1. You will probably need to enable “alloc” feature manually.
2. OS-independent no_std-friendly CPU features detection is only supported on x86 and x86_64 platforms. On other platforms, runtime-cpu-detection does nothing when “std” feature is disabled.

Disclaimer

Although all tests are passing and hours of fuzzing show no failures, latent bugs may still exist in the code.

1. The SIMD-accelerated code paths for x86 / x86_64 architecture are well tested and fuzzed.
2. The SIMD-accelerated code paths for aarch64 architecture are tested and fuzzed.
3. The SIMD-accelerated code paths for loongarch64 / loongarch32 architecture are cross-tested, but not extensively fuzzed.

If you find any bugs, please report them.

Acknowledgements

This crate is inspired by the following repositories:

• hex-simd, SPDX-License-Identifier: MIT
• const-hex, SPDX-License-Identifier: MIT OR Apache-2.0
• faster-hex, SPDX-License-Identifier: MIT OR Apache-2.0

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Modules

bufferdocsrs

Traits and implementations for buffers used by this crate.

Macros

decode

Helper macro for decoding hexadecimal strings to byte arrays in const contexts.

encode

Helper macro for encoding byte arrays as hexadecimal strings in const contexts.

Structs

Displayalloc

A wrapper for displaying a byte slice as a hexadecimal string.

InvalidInput

A generic error type indicating invalid input.

Constants

HEX_CHARS_LOWER

The lowercase hexadecimal chars: "0123456789abcdef".

HEX_CHARS_UPPER

The uppercase hexadecimal chars: "0123456789ABCDEF".

Traits

Hex

A trait for encoding / decoding a hexadecimal string (bytes) from / into the raw bytes.

Functions

decode

Decodes src (a hexadecimal string, case insensitive) into raw bytes, writes them into dst, and returns a reference to the written bytes.

decode_generic

decode(), but const-evaluable at the cost of performance.

encode

Encodes src as a hexadecimal string into dst and returns a reference to the written string.

encode_generic

encode(), but const-evaluable at the cost of performance.