# fashex - fast hexadecimal encoding and decoding
[![crates.io][crates-badge]][crates-url]
[![docs.rs][docs-badge]][docs-url]
[![license][license-badge]][license-url]
[crates-badge]: https://img.shields.io/crates/v/fashex
[crates-url]: https://crates.io/crates/fashex
[docs-badge]: https://docs.rs/fashex/badge.svg
[docs-url]: https://docs.rs/fashex
[license-badge]: https://img.shields.io/crates/l/fashex
[license-url]: https://codeberg.org/Hanyu/fashex/src/branch/main/LICENSE-APACHE
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](./BENCHMARK.md).
## Usage
Adds `fashex` as a dependency in your `Cargo.toml`:
```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:
```toml
[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.
1. 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.
1. The SIMD-accelerated code paths for `aarch64` architecture are tested and fuzzed.
1. 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
<sup>
Licensed under either of <a href="./LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="./LICENSE-MIT">MIT license</a> at your option.
</sup>
<br>
<sub>
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.
</sub>
[`core::simd`]: https://doc.rust-lang.org/nightly/core/simd/index.html
[`hex-simd`]: https://github.com/Nugine/simd
[`const-hex`]: https://github.com/DaniPopes/const-hex
[`faster-hex`]: https://github.com/nervosnetwork/faster-hex