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`]: mutable builder for a compact list of string segments in a single byte buffer.
8//! - [`StrList`]: frozen (immutable) string list with no excess capacity.
9//! - [`StrListRef`]: borrowed read-only view over string list data (zero-copy).
10//!
11//! ## Notes
12//!
13//! - `SmartString` promotion (stack → heap) can happen implicitly during mutation when capacity is exceeded.
14//! - Demotion (heap → stack) is **explicit** and must be requested via [`SmartString::try_into_stack`].
15//!
16//! ## Safety & invariants
17//!
18//! This crate contains a small amount of `unsafe` code used to project internal UTF‑8 byte buffers as `&str` / `&mut str`
19//! without repeated validation and bounds checks.
20//!
21//! Soundness relies on internal invariants:
22//!
23//! - `PascalString`: `len <= CAPACITY` and `data[..len]` is always valid UTF‑8.
24//! - `StrStack`: `data` is always valid UTF‑8 and `ends` stores valid UTF‑8 segment boundaries within `data`.
25//!
26//! See also: `docs/parity.api.md` for the “std `String` parity” checklist and compatibility notes.
27//! - MSRV (default features): **Rust 1.59.0**.
28//! - Motivation: `SmartString`'s public API uses a default const generic parameter
29//! (`SmartString<const N: usize = DEFAULT_CAPACITY>`), which requires newer compilers.
30//! - Note: MSRV is a `rustc` guarantee for this crate. Without a committed `Cargo.lock`, transitive dependency MSRVs
31//! can drift over time; our CI runs an MSRV job to detect such drift.
32mod display_ext;
33pub mod pascal_string;
34pub mod smart_string;
35pub mod str_stack;
36
37pub use crate::display_ext::DisplayExt;
38pub use crate::pascal_string::PascalString;
39pub use crate::smart_string::IntoChars;
40pub use crate::smart_string::SmartString;
41pub use crate::smart_string::Utf16DecodeError;
42pub use crate::str_stack::Checkpoint;
43pub use crate::str_stack::StrList;
44pub use crate::str_stack::StrListIter;
45pub use crate::str_stack::StrListRef;
46pub use crate::str_stack::StrListValidationError;
47pub use crate::str_stack::StrStack;
48pub use crate::str_stack::StrStackIter;
49pub use crate::str_stack::StrStackOverflow;