suiteki
A string type that stores short strings inline, borrows static ones and reference-counts owned ones.
Str is two words wide — sixteen bytes on a 64-bit target — and never spends
more than that. It stores one of three things:
- Inline. A borrowed
&strof up to fifteen bytes (seven on a 32-bit target) is copied into theStritself. Nothing is allocated, cloning copies the two words, and there is no pointer to follow to read the text. - Borrowed. A
&'static stris kept as-is: no allocation, and cloning is a pointer copy, whatever its length. - Shared. Any nonempty
Stringis moved into a reference-counted box that keeps its buffer and capacity: one allocation, and cloning is a counter increment rather than a copy of the bytes.
The discriminant is packed into the two top bits of the length word, whose most
significant byte is the last byte of the Str — the byte the inline bytes stop
at. So nothing is spent on a discriminant, and the word is never zero, which is
what keeps an Option<Str> two words wide as well.
It derefs to str, so every str method is available, and it implements the
usual traits (Debug, Display, Hash, Ord, Borrow<str>, FromStr,
FromIterator, Add, Extend, Index) so it drops into existing code.
The crate is no_std and needs only alloc.
use Str;
// A literal costs nothing to store and nothing to clone.
let greeting = from;
assert_eq!;
assert!;
// A short borrowed copy stays inline without allocating.
let inline = "world"..unwrap;
assert_eq!;
// A longer one is refcounted, so this clone copies no bytes.
let owned = from;
let alias = owned.clone;
assert_eq!;
// It concatenates and compares like any other string type.
let combined = greeting + " " + &inline;
assert_eq!;
Empty strings never reach the allocator, however they are built, and neither do borrowed copies that fit inline:
use Str;
assert!;
assert!;
assert!;
into_string allocates a fresh String for inline and static strings; for an
owned one it takes the allocation back when this is the last reference, and
copies only when it is not:
use Str;
let s = from;
let shared = s.clone;
let copied = s.into_string; // `shared` is still alive, so this copies.
assert_eq!;
let moved = shared.into_string; // Last reference: takes the `String`.
assert_eq!;
Installation
[]
= "0.1"
Features
| Feature | Default | Effect |
|---|---|---|
std |
yes | AsRef<OsStr>, AsRef<Path>, TryFrom<OsString> and ToSocketAddrs. Turn it off for a no_std build. |
serde |
no | Serialize and Deserialize for Str. |
nami |
no | Registers Str as a constant signal for the nami reactive framework. |
Reference counting
The count is not part of the public API, and there is no way to read it. That
keeps Str a value type: code cannot branch on how many aliases exist, and the
representation stays free to change. The count is non-atomic, so Str is
neither Send nor Sync — it is meant to be cheap on one thread, not shared
across several.
Benchmarks
The suite covers construction from a &'static str, from a String and from a
borrowed &str; clone, deref, equality, hashing and to_string; ownership
lifecycles including shared aliases, into_string round trips and reserved
capacity; every representation across clone, access and drop; equality against
aliases and first/last-byte mismatches; Unicode, NUL and Display formatting;
and collect/extend concatenation — at byte lengths from 0 to 4096,
bracketing the inline boundary on both 32- and 64-bit targets.
tests/allocations.rs pins the allocation counts those paths are allowed to
make.
Miri
The type is built on raw pointers and a hand-written reference count, so the test suite doubles as a memory-safety suite:
Origin
suiteki (水滴, "water droplet") was extracted from the
WaterUI framework, where it lived as
waterui-str, and is maintained as a standalone library.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.