moos/
lib.rs

1//! # MOOS
2//!
3//! ### Memory-Optimized Objects and Strings (_"moö-se"_)
4//!
5//! This crate (pronounced "moose") is a small collection of Rust primitives
6//! that prioritize memory efficiency and performance in constrained/embedded
7//! environments. At present, this crate includes 2 main types: [`CowStr`] and
8//! [`InlineStr`], which are described in detail below.
9//!
10//! ---
11//!
12//! ## [`CowStr`]
13//!
14//! Memory-efficient string alternative to `Cow<'a, str>` from the
15//! `std::borrow` module with memory optimizations and support for inline
16//! storage of small strings on the stack via [`InlineStr`].
17//!
18//! ### Example
19//!
20//! ```rust
21//! use moos::CowStr;
22//!
23//! # fn main() -> Result<(), moos::inline_str::StringTooLongError> {
24//! let owned = CowStr::Owned("This is an owned string.".into());
25//! let inlined = CowStr::Inlined("smol str!".parse()?);
26//! let borrowed = CowStr::Borrowed("This is a borrowed string.");
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! ## [`InlineStr`]
32//!
33//! The [`InlineStr`] type is a low-level inline (stack-allocated) string type,
34//! designed specifically for small strings. It avoids heap allocations for
35//! strings within the size limit imposed by its fixed capacity, which is
36//! dependent on the architecture's pointer width.
37//!
38//! ### Capacity
39//!
40//! The fixed capacity of an `InlineStr` is dependent on the pointer width of
41//! the target architecture; it is designed to maximize the amount of inline
42//! storage available within a single machine word, less 2 bytes for its length
43//! and null terminator (`\0`) character.
44//!
45//! On 64-bit systems, this usually equates to a maximum size of 22 B of UTF-8
46//! data, while on 32-bit systems, the maximum size is typically 10 B.
47//!
48//! ---
49//!
50//! ## `no_std` Support
51//!
52//! These types are designed to be used in `no_std` environments, making them
53//! suitable for embedded systems and other resource-constrained applications.
54//!
55//! ---
56//!
57//! ## Features
58//!
59//! - `std`: Enables integration with the Rust standard library. When disabled,
60//!   which is the default, the crate operates in `no_std` mode.
61//! - `serde`†: Enables serialization and deserialization support via Serde.
62//!
63//! > † enabled by default
64
65#![cfg_attr(not(any(test, feature = "std")), no_std)]
66
67extern crate alloc;
68extern crate core;
69
70pub mod cow_str;
71pub mod inline_str;
72
73pub use cow_str::*;
74pub use inline_str::*;