kstring/
lib.rs

1//! Key String: Optimized for map keys.
2//!
3//! # Examples
4//!
5//! String creation
6//! ```rust
7//! // Explicit
8//! let literal = kstring::KString::from_static("literal");
9//! // Implicit
10//! let literal = kstring::KString::from("literal");
11//!
12//! // Explicit
13//! let inline = kstring::KString::try_inline("stack").unwrap();
14//! let inline = kstring::KString::from_ref("stack");
15//!
16//! let formatted: kstring::KStringCow = format!("Hello {} and {}", literal, inline).into();
17//! ```
18//!
19//! # Background
20//!
21//! Considerations:
22//! - Large maps
23//! - Most keys live and drop without being used in any other way
24//! - Most keys are relatively small (single to double digit bytes)
25//! - Keys are immutable
26//! - Allow zero-cost abstractions between structs and maps (e.g. no allocating
27//!   when dealing with struct field names)
28//!
29//! Ramifications:
30//! - Inline small strings rather than going to the heap.
31//! - Preserve `&'static str` across strings ([`KString`]),
32//!   references ([`KStringRef`]), and lifetime abstractions ([`KStringCow`]) to avoid
33//!   allocating for struct field names.
34//! - Use `Box<str>` rather than `String` to use less memory.
35//!
36//! # Feature Flags
37//!
38#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
39#![cfg_attr(not(feature = "unsafe"), forbid(unsafe_code))]
40#![cfg_attr(docsrs, feature(doc_auto_cfg))]
41
42#[cfg(not(feature = "std"))]
43compile_error!("`std` feature is required; reserved for future `no_std` support");
44
45mod stack;
46mod string;
47mod string_cow;
48mod string_ref;
49
50pub mod backend;
51
52pub use stack::StackString;
53pub use string::*;
54pub use string_cow::*;
55pub use string_ref::*;
56
57#[cfg(test)]
58mod test {
59    #[test]
60    fn test_size() {
61        println!(
62            "String: {}",
63            std::mem::size_of::<crate::string::StdString>()
64        );
65        println!(
66            "Box<str>: {}",
67            std::mem::size_of::<crate::backend::DefaultStr>()
68        );
69        println!(
70            "Box<Box<str>>: {}",
71            std::mem::size_of::<Box<crate::backend::DefaultStr>>()
72        );
73        println!("str: {}", std::mem::size_of::<&'static str>());
74        println!(
75            "Cow: {}",
76            std::mem::size_of::<std::borrow::Cow<'static, str>>()
77        );
78    }
79}