cheetah_string/lib.rs
1#![cfg_attr(not(feature = "std"), no_std)]
2#![deny(unsafe_op_in_unsafe_fn)]
3#![warn(missing_docs)]
4
5//! An immutable, clone-cheap UTF-8 value for latency-sensitive systems.
6//!
7//! [`CheetahString`] has one constructor-independent value contract:
8//!
9//! - explicit static values borrow their `&'static str`;
10//! - other values up to 23 bytes are stored inline;
11//! - other long values use a shared `Arc<str>` backing.
12//!
13//! Long clones are bounded O(1) and allocate zero times. Append-heavy
14//! construction belongs to [`CheetahBuilder`]; call
15//! [`CheetahBuilder::finish`] to freeze the value or
16//! [`CheetahBuilder::into_string`] when mutation or spare capacity must
17//! continue. `from_string` freezes its input and does not retain a mutable
18//! `String` representation. Long `Arc<str>` inputs can be adopted without
19//! allocation through [`CheetahString::from_arc_str`].
20//!
21//! The crate supports `no_std + alloc`. Optional `serde` integration preserves
22//! the text contract, while the `bytes` feature exposes `CheetahBytes` for
23//! byte-oriented data. Byte-to-text conversion validates and copies; only
24//! `bytes::Bytes <-> CheetahBytes` is zero-copy.
25//!
26//! # Split capability
27//!
28//! [`CheetahString::split_char`] returns a double-ended standard iterator.
29//! [`CheetahString::split_str`] is forward-only, so unsupported reverse
30//! iteration fails at compile time rather than panicking at runtime.
31//!
32//! # Search and experimental SIMD
33//!
34//! Stable builds delegate equality, prefix, and suffix comparisons to the
35//! standard slice/`str` implementations so the compiler and standard library
36//! select the best portable strategy. The `experimental-simd` feature exposes
37//! an x86_64 SSE2 experiment for controlled benchmarking only. The deprecated
38//! `simd` feature remains a 3.x compatibility alias.
39//!
40//! Substring search through `find()` and `contains()` continues to use
41//! `memchr`/`memmem`, which is the stable default search backend.
42//!
43//! # Retired experimental features
44//!
45//! The former `experimental-packed` flag is a compatibility no-op. Its v1
46//! public type was removed because integer-to-pointer reconstruction did not
47//! satisfy Rust's strict-provenance model.
48//!
49//! ```compile_fail
50//! use cheetah_string::packed::PackedCheetahString;
51//! ```
52//!
53//! To opt into the isolated experiment:
54//!
55//! ```toml
56//! [dependencies]
57//! cheetah-string = { version = "3.1.0", features = ["experimental-simd"] }
58//! ```
59//!
60//! # Example
61//!
62//! ```rust
63//! use cheetah_string::{CheetahBuilder, CheetahString};
64//!
65//! let topic = CheetahString::from_static_str("orders");
66//! assert!(topic.starts_with("ord"));
67//!
68//! let mut builder = CheetahBuilder::with_capacity(32);
69//! builder.push_str(topic.as_str());
70//! builder.push('@');
71//! builder.push_str("group-a");
72//!
73//! let route = builder.finish();
74//! assert_eq!(route, "orders@group-a");
75//! ```
76extern crate alloc;
77
78mod builder;
79mod cheetah_string;
80mod error;
81mod inline;
82mod search;
83
84#[cfg(feature = "bytes")]
85#[path = "bytes.rs"]
86mod cheetah_bytes;
87
88#[cfg(feature = "serde")]
89mod serde;
90
91#[cfg(all(feature = "experimental-simd", target_arch = "x86_64"))]
92mod simd;
93
94#[cfg(feature = "bytes")]
95pub use cheetah_bytes::{CheetahBytes, FromUtf8BytesError};
96
97pub use builder::CheetahBuilder;
98pub use cheetah_string::{CheetahString, SplitPattern, SplitStr, StrPattern};
99pub use error::{Error, Result};
100pub use search::CheetahFinder;
101
102/// Deprecated v3 compatibility name for [`CheetahString`].
103///
104/// `CheetahString` is now itself immutable and clone-cheap, so a second value
105/// type no longer carries a distinct contract.
106#[deprecated(since = "3.0.0", note = "use CheetahString")]
107pub type CheetahStr = CheetahString;