base122-fast 0.1.2

High-performance Base122 codex (5+ Gbps) with lower overhead (~14%) than Base64.
Documentation 
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

# base122-fast


[![Crates.io](https://img.shields.io/crates/v/base122-fast.svg)](https://crates.io/crates/base122-fast)
[![Documentation](https://docs.rs/base122-fast/badge.svg)](https://docs.rs/base122-fast)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Base122](https://github.com/kevinAlbs/Base122) is a binary-to-text encoding scheme designed to be significantly more space-efficient than Base64. It incurs only **~14% overhead** (compared to Base64's 33%) while remaining valid UTF-8.

**base122-fast** is a high-performance implementation optimized for modern CPUs, featuring **no_std** support.

## Key Features


*   **High Throughput**: Optimized for Gbps-level processing.
*   **no_std**: Suitable for embedded systems and WASM (requires `alloc`).
*   **SIMD Within A Register**: Uses SWAR techniques to process multiple bytes in 64-bit registers.
*   **Safety**: While leveraging `unsafe` for performance, it is rigorously tested for round-trip integrity.

## Performance


The following throughput was measured on **high-entropy binary data** using an **AMD Ryzen 5 5600** (single core).

| Data Size | Encode (Throughput) | Decode (Throughput) |
| :--- | :--- | :--- |
| 16 B | 301.9 MiB/s | 335.9 MiB/s |
| 64 B | 883.6 MiB/s | 834.2 MiB/s |
| 1 KiB | 2.15 GiB/s | 1.63 GiB/s |
| 64 KiB | 2.40 GiB/s | 1.64 GiB/s |
| 1 MiB | 814.6 MiB/s | 678.9 MiB/s |

For large payloads (≥1 MiB), the implementation sustains approximately **6.5 Gbps encoding** and **5.4 Gbps decoding**.

> **Note:** Run `cargo bench` to reproduce these results. The benchmarks evaluate encoding, decoding, and round-trip integrity on random byte streams.

## Quick Start


Add to `Cargo.toml`:

```toml
[dependencies]
base122-fast = "0.1"
```

### Usage


```rust
use base122_fast::{encode, decode};

// Encoding
let data = b"hello world";
let encoded_str = encode(data);

// Decoding
let decoded_vec = decode(&encoded_str).expect("Invalid Base122");
assert_eq!(data, decoded_vec.as_slice());
```

## Implementation Details


Base122 maps binary data to a UTF-8 safe subset of 122 non-control bytes. Six ASCII codes (`\x00`, `\x0A`, `\x0D`, `\x22`, `\x26`, `\x5C`) are considered illegal and are handled via an escape mechanism.

### Optimization Strategy

High throughput is achieved by processing 64-bit chunks. When a chunk contains no illegal bytes, a **branchless fast-path** is taken. By utilizing `unsafe` pointer arithmetic and pre-calculating output capacities, the hot loop avoids bounds checking and reallocations.

## License


MIT License.