cheetah-string 3.1.0

An immutable, clone-cheap UTF-8 string with explicit construction and byte interoperability
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

# Safety model


This file records the unsafe boundaries that remain in the stable
`CheetahString` 3.1 implementation. The retired packed representation is not
part of this model and is not exported by the crate.

## Core invariants


- Every `CheetahString` is valid UTF-8 for its complete lifetime.
- Inline length is represented by a private 0-through-23 enum and never exceeds
  the 23-byte inline buffer. Its invalid discriminants are compiler layout
  niches; they are never constructed as inline lengths.
- Static storage contains a valid `&'static str`.
- Shared storage is an owned `Arc<str>` and preserves pointer provenance.
- `CheetahBytes` has byte semantics and does not imply UTF-8.

## Unsafe boundary inventory


| Boundary | Caller obligation | Internal proof |
|---|---|---|
| `CheetahString::from_utf8_unchecked_vec` | The complete vector is valid UTF-8. | The private unsafe helper either copies at most 23 validated bytes inline or converts the owned vector to `String` before freezing it. |
| `CheetahString::from_utf8_unchecked_bytes` | The complete slice is valid UTF-8. | The validated `str` view is immediately copied into canonical storage. |
| `CheetahString::from_utf8_unchecked_arc_vec` | The complete shared vector is valid UTF-8. | Unique input follows the vector boundary; shared input is copied through the validated slice boundary. |
| `CheetahString::from_utf8_unchecked_bytes_buf` | The complete `bytes::Bytes` payload is valid UTF-8. | The payload is copied through the validated slice boundary. |
| `CheetahBytes::into_string_unchecked` | The complete byte payload is valid UTF-8. | The obligation is forwarded to the `bytes::Bytes` text boundary. |
| SSE2 equality helper | SSE2 is available and both slices have equal length. | Runtime/target gating establishes SSE2, and each unaligned 16-byte load is guarded by the loop bounds. |

The private helpers whose names contain `validated` are themselves `unsafe fn`.
Safe constructors perform UTF-8 validation before entering those helpers;
public unchecked constructors forward their documented caller contract in an
explicit unsafe block.

The 24-byte representation does not add an unsafe boundary. `Static` remains a
normal `&'static str`, `Shared` remains a normal `Arc<str>`, and the outer Rust
enum uses the constrained inline-length discriminants as niches. No pointer is
converted to an integer or reconstructed. Layout snapshots gate the compiler
optimization separately from Miri's behavioral provenance checks.

## Verification


Run the stable representation under Miri:

```bash
cargo +nightly miri test --lib --no-default-features
cargo +nightly miri test --test basic --no-default-features
cargo +nightly miri test --test bytes --features bytes
```

Compile all fuzz targets with libFuzzer and AddressSanitizer:

```bash
cargo +nightly fuzz build
```

The same commands are encoded in `.github/workflows/safety.yml` with pinned
third-party actions.