compact_str

A CompactString is a memory-efficient string type that implements Small String Optimization (SSO). It can store up to 24 bytes (on 64-bit architectures) or 12 bytes (on 32-bit architectures) directly on the stack. If a string exceeds this size, it is transparently stored on the heap.

Key use cases:

• As a drop-in replacement for String to reduce heap allocations.
• In parsing, deserializing, or applications where many small strings are present.

Key Properties:

• size_of::<CompactString>() == size_of::<String>() (it won't increase your stack frame size).
• Clone is O(n).
• From<String> or From<Box<str>> re-uses the underlying buffer where possible.
• O(1) creation from &'static str using CompactString::const_new.
• Space optimized for Option<CompactString>: size_of::<CompactString>() == size_of::<Option<CompactString>>().

The drain(range) method returns a Drain iterator that yields the characters in the specified range.

Important: Dropping the Drain iterator will remove the selected range from the source CompactString, even if you haven't consumed all elements from the iterator. This mirrors the behavior of std::string::Drain.

use compact_str::CompactString;

let mut cs = CompactString::from("hello world");
{
    let mut drain = cs.drain(0..5);
    while let Some(c) = drain.next() {
        println!("{}", c);
    }
}
// cs is now " world"

The ToCompactString trait provides the to_compact_string(&self) method. This trait is automatically implemented for all types that implement std::fmt::Display, with high-performance specialized implementations for:

• Integers: u8, u16, u32, u64, usize, u128, i8, i16, i32, i64, isize, i128
• Floats: f32, f64
• Others: bool, char, NonZeroU*, NonZeroI*, String, CompactString

The CompactStringExt trait allows you to efficiently join collections into a CompactString. It is automatically implemented for any type that can be converted into an iterator yielding types that implement AsRef<str> (e.g., Vec<String>, slices, etc.).

It provides two methods:

• join_compact(separator: impl AsRef<str>)
• concat_compact()

Use concat_compact() to merge all elements of an iterator or collection into one CompactString without a separator.

use compact_str::CompactStringExt;

let items = ["hello", " ", "world", "!"];
let compact = items.concat_compact();

assert_eq!(compact, "hello world!");

Use join_compact(separator) to merge elements of an iterator or collection into a single CompactString, inserting the separator between each element.

use compact_str::CompactStringExt;

let fruits = vec!["apples", "oranges", "bananas"];
let compact = fruits.join_compact(", ");

assert_eq!(compact, "apples, oranges, bananas");

To String

• into_string(self): Consumes the CompactString and returns a standard String.

From String (Memory Efficient)

• from_string_buffer(s): Converts a String into a CompactString without inlining. This method reuses the existing heap allocation from the String instead of deallocating it and allocating a new one. This is useful for performance-sensitive code where you want to avoid allocator trips.

Note: For standard usage where you want short strings to be inlined onto the stack, use From<String> instead of from_string_buffer.

# use compact_str::CompactString;
let s = CompactString::new("Hello world");
let standard_string = s.into_string();

// Efficiently reuse buffer
let og = "hello world".to_string();
let og_addr = og.as_ptr();
let mut c = CompactString::from_string_buffer(og);
assert_eq!(og_addr, c.as_ptr());

If the std feature is enabled, CompactString can be converted into a Box<dyn std::error::Error> or Box<dyn std::error::Error + Send + Sync>. This is useful for using CompactString as an error message in applications using the ? operator.

use compact_str::CompactString;

fn do_something() -> Result<(), Box<dyn std::error::Error>> {
    let err_msg = CompactString::from("something went wrong");
    Err(err_msg.into())
}

CompactString implements FromIterator and Extend, allowing you to build strings from iterators of char, &char, &str, Box<str>, Cow<'a, str>, String, or other CompactString instances.

use compact_str::CompactString;

// Building from an iterator
let cs: CompactString = "hello".chars().collect();

// Extending an existing CompactString
let mut cs = CompactString::new("hello");
cs.extend(" world");