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