Skip to content

About

πŸ†A lightweight, high-performance string manipulation library optimized for speed-sensitive applications.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

105 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

CheetahString

Crates.io Documentation License Rust Version

CheetahString is an immutable, clone-cheap UTF-8 value for latency-sensitive systems. It stores short text inline, keeps static text allocation-free, and shares long dynamic text through Arc<str>. The same value contract works with std and no_std + alloc.

Version 3.2.0 is the supported 3.x release line for the immutable architecture.

Design contract

Input path Storage Allocation events during conversion Clone allocation
Explicit from_static_str Static 0 0
Other UTF-8 input ≀ 23 bytes Inline 0 0
Long Arc<str> Shared 0; payload pointer is retained 0
Long borrowed text or exact-capacity String Shared 1 0
Long spare-capacity String / builder Shared 1: copied into Arc backing without shrinking 0
concat, +, replace results Inline up to 23 bytes, otherwise Shared 0 inline, otherwise 1: written once at the exact length 0

On supported 32-bit and 64-bit targets, both CheetahString and Option<CheetahString> occupy 24 bytes. A 10,000-element vector therefore uses 240,000 bytes of element slots instead of the previous 320,000-byte contract. This is achieved with safe Rust enum niches; string pointers are never converted to integers. tests/layout_snapshot.rs and tests/allocation_contract.rs enforce the representation, container footprint, and portability contract.

The representation has no mutable Owned(String) state. Construction history therefore cannot change clone complexity. Use:

  • CheetahString for protocol text, immutable fields, and collection keys;
  • CheetahBuilder for append-heavy construction followed by finish();
  • standard String when mutation or spare capacity must continue;
  • CheetahBytes for byte semantics when the optional bytes feature is active;
  • CheetahText for UTF-8 text that stays in a received bytes::Bytes buffer, also behind the bytes feature.

Installation

Add the crate to your project:

[dependencies]
cheetah-string = "3.2.0"

With optional integrations:

[dependencies]
cheetah-string = {
  version = "3.2.0",
  features = ["serde", "bytes"]
}

The minimum supported Rust version is 1.95.

The packaged consumer matrix can be reproduced with bash scripts/check-msrv-package.sh 1.95 on Unix or pwsh -File scripts/check-msrv-package.ps1 -Msrv 1.95 on Windows.

Quick start

use cheetah_string::{CheetahBuilder, CheetahString};

let inline = CheetahString::from("orders");
let static_value = CheetahString::from_static_str("system-topic");
let shared = CheetahString::from_string("long-dynamic-value-".repeat(8));
let adopted = CheetahString::from(std::sync::Arc::<str>::from(
    "ownership-preserving-shared-value",
));
let cloned = shared.clone();

assert_eq!(inline, "orders");
assert_eq!(static_value, "system-topic");
assert_eq!(shared, cloned);
assert_eq!(shared.as_bytes().as_ptr(), cloned.as_bytes().as_ptr());
assert_eq!(adopted, "ownership-preserving-shared-value");

// Short contents stay on the stack, so building and finishing this key
// allocates nothing.
let mut builder = CheetahBuilder::new();
builder.push_str("orders");
builder.push('@');
builder.push_str("group-a");
let route_key = builder.finish();

assert_eq!(route_key, "orders@group-a");

Build composite keys with concat when every part is a string, or with cheetah_format! when numbers or other Display values are involved. Both keep results of up to 23 bytes inline without allocating, unlike CheetahString::from(format!(..)):

use cheetah_string::{cheetah_format, CheetahString};

let key = CheetahString::concat(&["orders", "@", "group-a"]);
assert_eq!(key, "orders@group-a");

let queue_id = 4;
let queue_key = cheetah_format!("{key}#{queue_id}");
assert_eq!(queue_key, "orders@group-a#4");

When mutation continues, keep the builder's String:

use cheetah_string::CheetahBuilder;

let mut builder = CheetahBuilder::with_capacity(128);
builder.push_str("orders");
let mut value = builder.into_string();
value.push_str("@group-a");

Search and split

Equality, prefix, and suffix checks compare up to 64 bytes with overlapping fixed-size loads instead of calling memcmp, and use memcmp beyond that. Substring search picks its backend by haystack and needle length, with thresholds measured on x86_64 and aarch64. Needles of 2 to 32 bytes in short text use a screened search with no setup: 16 positions at a time are checked against the needle's first and last bytes, and only positions that pass compare the middle. find and rfind screen text under 256 bytes; on aarch64 find stops sooner for needles under 16 bytes. contains keeps the standard library's SIMD search once the text spans a 16-byte block plus the needle and screens only shorter text, or text under 256 bytes on targets without that search. Every other search uses memchr::memmem, except that rfind uses str::rfind once the text is at least 24 + 2 * needle bytes long. Single-byte needles use memchr, and a needle at least as long as the text is answered by one comparison. Use CheetahFinder to search for one needle repeatedly.

Iterator capabilities are explicit:

use cheetah_string::CheetahString;

let value = CheetahString::from("a::b::c");
let forward: Vec<_> = value.split_str("::").collect();
assert_eq!(forward, ["a", "b", "c"]);

let csv = CheetahString::from("a,b,c");
let reverse: Vec<_> = csv.split_char(',').rev().collect();
assert_eq!(reverse, ["c", "b", "a"]);

let reverse_lines: Vec<_> = CheetahString::from("a\nb\nc").lines().rev().collect();
assert_eq!(reverse_lines, ["c", "b", "a"]);

split_str is intentionally forward-only. Unsupported reverse iteration fails at compile time instead of panicking at runtime.

Bytes interoperability

The ownership boundary is explicit:

Conversion UTF-8 validation Payload copy
bytes::Bytes -> CheetahBytes No No
CheetahBytes -> bytes::Bytes No No
Bytes -> CheetahString::try_from Yes Yes
CheetahBytes -> CheetahString::try_from Yes Yes
Bytes -> CheetahString::try_copy_from_bytes Yes Yes
&CheetahBytes -> try_copy_to_cheetah_string Yes Yes
Bytes -> CheetahText::try_from_bytes Yes No
CheetahText::slice / slice_ref Char boundaries only No
CheetahText -> bytes::Bytes No No
String -> CheetahText No No
CheetahString -> CheetahText No Only inline values
CheetahText -> CheetahString No Yes
use bytes::Bytes;
use cheetah_string::{CheetahBytes, CheetahString};

let raw = Bytes::from_static(b"orders");
let bytes = CheetahBytes::from(raw);
let text = bytes.try_copy_to_cheetah_string().unwrap();
assert_eq!(text, "orders");

let invalid = Bytes::from_static(&[0xff]);
let error = CheetahString::try_copy_from_bytes(invalid.clone()).unwrap_err();
assert_eq!(error.into_bytes(), invalid);

CheetahText keeps decoded text inside the network buffer. Validation keeps the buffer, and slice_ref turns the &str results of split, lines, or split_once into owned values that share it:

use bytes::Bytes;
use cheetah_string::{CheetahString, CheetahText};

let frame = Bytes::from_static(b"KEYS=order-10001\nTAGS=paid\n");
let text = CheetahText::try_from_bytes(frame).unwrap();

let mut properties = Vec::new();
for line in text.lines() {
    let (key, value) = line.split_once('=').unwrap();
    properties.push((text.slice_ref(key), text.slice_ref(value)));
}
assert_eq!(properties[0].1, "order-10001");

// Copy values that must outlive the frame; short ones become inline.
let tag: CheetahString = properties[1].1.to_cheetah_string();
assert_eq!(tag, "paid");

A slice keeps its whole buffer alive. Copy long-lived values with to_cheetah_string() so they do not pin a large receive buffer.

Each slice and drop updates the buffer's atomic reference count, so short values are cheaper to copy into an inline CheetahString. Decoding 20 typical RocketMQ properties was 23% slower with every piece as CheetahText, while CheetahString keys with CheetahText values matched the copying decoder on short values and were 1.9x faster on 72-byte values.

The conversion matrix above is covered by tests/bytes.rs and tests/allocation_contract.rs.

Features

Feature Default Contract
std Yes Standard-library integration
serde No Serialization and deserialization
bytes No CheetahBytes and explicit byte/text conversion
experimental-simd No Deprecated no-op; the portable comparison replaced the x86_64 SSE2 experiment
simd No Deprecated no-op alias for experimental-simd
experimental-packed No Deprecated no-op retained for 3.x dependency compatibility

Optional features do not change the stable CheetahString layout.

The former packed v1 type was removed in 3.1 because its heap representation round-tripped an allocation pointer through usize, which strict-provenance Miri rejected. The stable immutable CheetahString now reaches 24 bytes through safe Rust enum niches, but it is not a mutable PackedCheetahString drop-in. Use CheetahBuilder or String while mutation continues.

Performance evidence

The repository includes RocketMQ-shaped Criterion workloads for property building, remoting-header parsing, topic insertion and lookup, plus explicit layout and allocation contracts. Blocking timing decisions run only on a dedicated fixed CPU with two reversed base/head rounds.

cargo test --test layout_snapshot --all-features
cargo test --test allocation_contract --all-features -- --test-threads=1
cargo bench --bench shared_backing -- __allocation_evidence_only__ --noplot \
  2>&1 | tee target/allocation-evidence.log
python scripts/verify-allocation-evidence.py target/allocation-evidence.log
cargo bench --bench search_thresholds
cargo bench --bench comprehensive
cargo bench --bench mq_properties
cargo bench --bench mq_remoting_header
cargo bench --bench mq_topic

Hosted-runner and local benchmark results are diagnostic; they do not independently establish a release-grade performance pass. The versioned allocation and layout tests are the deterministic performance contracts. scripts/verify-allocation-evidence.py independently validates the schema-v3 allocation record emitted by the shared-backing benchmark.

Pull requests also compare exact instruction counts, which unlike timings repeat on shared runners. scripts/instruction-counts.py builds the fixed scenarios in scripts/icount/scenarios.rs against the base and head checkouts, runs each under Valgrind's cachegrind, and fails when a scenario executes more than 2% and more than 2 instructions per iteration above base. To accept a deliberate regression, label the pull request accept-instruction-regression and re-run the job; it then reports the counts without failing. With Valgrind installed, run it locally against a checkout of main:

python scripts/instruction-counts.py --base ../cheetah-string-main --head .

benches/search_thresholds.rs times the substring-search backends that contains, find, and rfind choose between; the Search thresholds workflow runs it on x86_64 and aarch64 when the search dispatch changes.

Safety and portability

The repository's workflows are the authoritative record of automated checks. Release validation is fail-closed: formatting, linting, tests, dependency audit, and package construction must complete before any tag or publication step.

The unsafe constructors are explicitly named and require the caller to prove UTF-8 validity. Safe byte constructors validate before creating text.

CI enforces the Rust 1.95 packaged-consumer matrix, warning-free rustdoc, locked dependency auditing, and repository workflow contracts. The Safety workflow runs Miri over the stable text/byte invariants and compiles every libFuzzer target with AddressSanitizer on pull requests and on a weekly schedule. The maintained commands and toolchain setup are encoded directly in .github/workflows/safety.yml; unsafe constructor obligations remain next to their public APIs in src/cheetah_string/construct.rs and src/bytes.rs.

Pattern and error signatures are covered by tests/api_contract.rs. The dedicated .github/workflows/api-compatibility.yml workflow compares every pull request with origin/main under minor-release semver rules.

Projects using CheetahString

License

Licensed under either of Apache License 2.0 or MIT, at your option.

About

πŸ†A lightweight, high-performance string manipulation library optimized for speed-sensitive applications.

Topics

Resources

Stars

18 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages