smart_string/lib.rs
1#![deny(unsafe_op_in_unsafe_fn)]
2
3//! `smart-string` is a collection of small string primitives:
4//!
5//! - [`PascalString`]: fixed-capacity UTF-8 string stored inline (stack / in-place).
6//! - [`SmartString`]: stack-or-heap string that promotes to heap when needed.
7//! - [`StrStack`]: a compact “stack” of string slices backed by a single byte buffer.
8//!
9//! ## Notes
10//!
11//! - `SmartString` promotion (stack → heap) can happen implicitly during mutation when capacity is exceeded.
12//! - Demotion (heap → stack) is **explicit** and must be requested via [`SmartString::try_into_stack`].
13//!
14//! ## Safety & invariants
15//!
16//! This crate contains a small amount of `unsafe` code used to project internal UTF‑8 byte buffers as `&str` / `&mut str`
17//! without repeated validation and bounds checks.
18//!
19//! Soundness relies on internal invariants:
20//!
21//! - `PascalString`: `len <= CAPACITY` and `data[..len]` is always valid UTF‑8.
22//! - `StrStack`: `data` is always valid UTF‑8 and `ends` stores valid UTF‑8 segment boundaries within `data`.
23//!
24//! See also: `docs/parity.api.md` for the “std `String` parity” checklist and compatibility notes.
25//! - MSRV (default features): **Rust 1.59.0**.
26//! - Motivation: `SmartString`'s public API uses a default const generic parameter
27//! (`SmartString<const N: usize = DEFAULT_CAPACITY>`), which requires newer compilers.
28//! - Note: MSRV is a `rustc` guarantee for this crate. Without a committed `Cargo.lock`, transitive dependency MSRVs
29//! can drift over time; our CI runs an MSRV job to detect such drift.
30mod display_ext;
31pub mod pascal_string;
32pub mod smart_string;
33pub mod str_stack;
34
35pub use crate::display_ext::DisplayExt;
36pub use crate::pascal_string::PascalString;
37pub use crate::smart_string::IntoChars;
38pub use crate::smart_string::SmartString;
39pub use crate::smart_string::Utf16DecodeError;
40pub use crate::str_stack::StrStack;
41pub use crate::str_stack::StrStackIter;