string_alloc/
lib.rs

1//! An allocator-aware, `no_std`-compatible implementation of `String<A>` that mirrors `std::string::String`.
2//!
3//! This crate provides a custom string implementation that supports custom allocators while maintaining
4//! full compatibility with the standard library's string functionality.
5//!
6//! ## Requirements
7//!
8//! This crate requires the nightly toolchain due to its use of the `allocator_api` feature.
9//! Add the following to your `rust-toolchain.toml` or use `cargo +nightly`:
10//!
11//! ```toml
12//! [toolchain]
13//! channel = "nightly"
14//! ```
15//!
16//! ## Features
17//!
18//! - UTF-8 correctness
19//! - Full `no_std` support via `extern crate alloc`
20//! - Custom allocator compatibility
21//! - Thread-safe operations
22//! - `format!` macro support
23//! - Serde serialization/deserialization (optional)
24//!
25//! ## Design Choices
26//!
27//! This implementation closely mirrors the standard library's `String` type while making some
28//! deliberate choices to keep the codebase small and safe:
29//!
30//! - **Allocator Support**: All methods that allocate take an explicit allocator parameter with the `_in` suffix
31//!   to distinguish them from the default allocator versions.
32//!
33//! - **UTF-8 Safety**: All string operations maintain UTF-8 correctness, with proper handling of
34//!   character boundaries and byte lengths.
35//!
36//! - **Minimal Dependencies**: The implementation uses only stable features and core functionality,
37//!   avoiding unstable features to maintain compatibility and safety.
38//!
39//! ### Omitted Features
40//!
41//! Some features from the standard library's `String` implementation have been intentionally omitted:
42//!
43//! - `from_utf8_lossy`: Requires unstable features for efficient lossy UTF-8 conversion
44//! - `get`/`get_mut`: Can be worked around using string slicing and `split_at`
45//! - `drain`: Can be replaced with `split_off` and `retain` for most use cases
46//!
47//! These omissions are intentional to:
48//! - Keep the codebase small and maintainable
49//! - Avoid unstable features
50//! - Maintain safety guarantees
51//! - Provide workable alternatives through existing methods
52//!
53//! ## Usage
54//!
55//! ```rust
56//! #![feature(allocator_api)]
57//!
58//! use string_alloc::String;
59//! use std::alloc::Global;
60//! use std::fmt::Write;
61//!
62//! // Basic usage
63//! let mut s = String::from_str_in("hello", Global);
64//! s.push_str(" world");
65//!
66//! // Using format! macro
67//! let name = "Alice";
68//! let mut s2 = String::new_in(Global);
69//! write!(s2, "Hello, {}!", name).unwrap();
70//!
71//! // With serde (requires "serde" feature)
72//! #[cfg(feature = "serde")]
73//! {
74//!     use serde::{Serialize, Deserialize};
75//!     
76//!     #[derive(Serialize, Deserialize)]
77//!     struct Person {
78//!         name: String<Global>,
79//!     }
80//! }
81//! ```
82//!
83//! ## License
84//!
85//! Apache-2.0
86
87#![no_std]
88#![feature(allocator_api)]
89
90#[cfg(feature = "std")] extern crate std;
91
92extern crate alloc;
93
94pub mod string;
95pub use string::String;
string_alloc/lib.rs

string_alloc/
lib.rs
