Skip to main content

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(all(not(feature = "std"), not(test)), no_std)]
41#![cfg_attr(docsrs, feature(doc_cfg))]
42#![warn(clippy::print_stderr)]
43#![warn(clippy::print_stdout)]
44#![warn(clippy::std_instead_of_core)]
45#![warn(clippy::std_instead_of_alloc)]
46
47#[allow(unused_extern_crates)]
48extern crate alloc;
49
50mod stack;
51mod string;
52mod string_cow;
53mod string_ref;
54
55pub mod backend;
56
57pub use stack::StackString;
58pub use string::*;
59pub use string_cow::*;
60pub use string_ref::*;
61
62#[cfg(test)]
63mod test {
64    #[test]
65    fn test_size() {
66        println!("String: {}", size_of::<crate::string::StdString>());
67        println!("Box<str>: {}", size_of::<crate::backend::DefaultStr>());
68        println!(
69            "Box<Box<str>>: {}",
70            size_of::<Box<crate::backend::DefaultStr>>()
71        );
72        println!("str: {}", size_of::<&'static str>());
73        println!("Cow: {}", size_of::<alloc::borrow::Cow<'static, str>>());
74    }
75}
76
77#[doc = include_str!("../README.md")]
78#[cfg(doctest)]
79pub struct ReadmeDoctests;