Crate lean_string

LeanString

Compact, clone-on-write string.

Properties

LeanString has the following properties:

• size_of::<LeanString>() == size_of::<[usize; 2]>() (2 words).
  • one usize smaller than String.
• Stores up to 16 bytes inline (on the stack).
  • 8 bytes if 32-bit architecture.
  • Strings larger than 16 bytes are stored on the heap.
• Clone-on-Write (CoW)
  • LeanString uses a reference-counted heap buffer (like Arc).
  • When a LeanString is cloned, the heap buffer is shared.
  • When a LeanString is mutated, the heap buffer is copied if it is shared.
• O(1), zero allocation construction from &'static str.
• Nich optimized for Option<LeanString>.
  • size_of::<Option<LeanString>>() == size_of::<LeanString>()
• High API compatibility for String.
• Supports no_std environment.

Example

use lean_string::LeanString;

// This is a zero-allocation operation, stored inlined.
let small = LeanString::from("Hello");

// More than 16 bytes, stored on the heap (64-bit architecture).
let large = LeanString::from("This is a not long but can't store inlined");

// Clone is O(1), heap buffer is shared.
let mut cloned = large.clone();

// Mutating a shared string will copy the heap buffer. (CoW)
cloned.push('!');
assert_eq!(cloned, "This is a not long but can't store inlined!");
assert_eq!(large  + "!", cloned);

Comparison

Name	Size	Inline	&'static str	Notes
String	24 bytes	No	No	prelude
Cow<'static, str>	24 bytes	No	Yes	std (alloc)
CompactString	24 bytes	24 bytes	Yes	Nich optimized for Option<_>
EcoString	16 bytes	15 bytes	No	Clone-on-Write, Nich optimized for Option<_>
LeanString (This crate)	16 bytes	16 bytes	Yes	Clone-on-Write, Nich optimized for Option<_>

Above table is for 64-bit architecture. Click here for 32-bit architecture.

Name	Size	Inline	&'static str	Notes
String	12 bytes	No	No	prelude
Cow<'static, str>	12 bytes	No	Yes	std (alloc)
CompactString	12 bytes	12 bytes	Yes	Nich optimized for Option<_>
EcoString	8 bytes	7 bytes	No	Clone-on-Write, Nich optimized for Option<_>
LeanString (This crate)	8 bytes	8 bytes	Yes	Clone-on-Write, Nich optimized for Option<_>

• Size: The size of the struct.
• Inline: The maximum size of the string that can be stored inlined (on the stack).
• &'static str: Zero-allocation and O(1) construction from &'static str.

Other string types may have different properties and use cases.

• arcstr
• byteyarn
• flexstr
• hipstr
• imstr
• kstring
• smartstring

For more comparison and information, please see Rust String Benchmarks.

Special Thanks

The idea and implementation of LeanString is inspired by the following projects:

• ecow
• compact_str

I would like to thank the authors of these projects for their great work.

License

This crate is licensed under the MIT license.

Structs

FromUtf16Error

An error if the conversion from a sequence of UTF-16 code units to a LeanString fails due to invalid UTF-16 code unit sequences.

LeanString

Compact, clone-on-write, UTF-8 encoded, growable string type.

ReserveError

An error if allocating or resizing a LeanString failed.

Enums

ToLeanStringError

An error that can occur when converting a value to a LeanString.

Traits

ToLeanString

A trait for converting a value to a LeanString.