flexstr

A flexible, simple to use, clone-efficient String replacement for Rust. It unifies borrowed, inlined, referenced counted and boxed strings into a single type.

Overview

If you've used Cow, but you wish cloning owned strings was more performant and that being owned didn't always imply heap allocation, this crate might be what you are looking for. The operations are "lazy" (like Cow), and it tries not to do work the user is not expecting.

Users of previous versions: you should be aware this new version is a ground up rewrite with a solidly different thought process, API and design. Even if the previous versions didn't match your needs, this one might. Users should be aware that nearly all the string construction code is not yet present in this version. The new way to do this (workaround?) is to do the work as a String and then import it into a LocalStr or SharedStr. Moving into and out of the boxed variant (from_owned) should be near zero cost.

Features

• Simple: just an enum. You mostly already know how to use it.
• Borrowed, inlined, reference counted, and boxed strings in a single type
• O(1) clone
  • NOTE: first clone when variant is Boxed is O(n)
• Mutable (Copy-on-write under the hood, if necessary)
• Inlined string type can be used on its own
• Same size a a String (3 words wide, even inside an Option)
• Lazy instantiation (no unexpected allocations)
• No external dependencies
  • NOTE: serde/sqlx optional for serialization/deserialization/encode/decode
• Optional no_std
• Optional safe feature that forbids any unsafe usage
  • NOTE: This does induce a performance penalty, as would be expected
  • NOTE 2: OsStr/Path support on Windows requires at least one unsafe call (win_min_unsafe feature).
• Handles all Rust string types (str, CStr, OsStr, Path, [u8])

Cargo Features

• safe = Use all safe functions and add forbid(unsafe_code) (performance penalty)
• sqlx = Enable sqlx encode/decode/type support
• sqlx_pg_arrays = Enable sqlx Postgres array support (implies sqlx feature)
• std = Use std (default)
• serde = add serde dependency and adds serialization/deserialization
• win_min_unsafe = enables the minimum necessary unsafe code on Windows to support OsStr/Path. No other string types or operating systems are impacted (implies safe feature).
  • NOTE: The code will refuse to compile if this is not specified when ALL the following conditions are true:
    • The safe feature is enabled
    • The osstr and/or path feature(s) are enabled
    • Compiling for Windows

String Type Features:

• str = Enable str-based strings (default)
• bytes = Enable byte-based strings ([u8])
• cstr = Enable CStr-based strings
• osstr = Enable OsStr-based strings
• path = Enable Path-based strings (implies osstr feature)

Example

It is just an enum that looks like this - you can probably guess much of how it works just by looking at it:

// `S` is just the raw string type (typically `str`)
// `R` is just an `Arc` or an `Rc`.
pub enum FlexStr<'s, S, R> {
    Borrowed(&'s S),
    Inlined(InlineFlexStr<S>),
    RefCounted(R),
    Boxed(Box<S>),
}

// You would typically use it via one of the type aliases, for example:
pub type LocalStr<'s> = FlexStr<'s, str, Rc<str>>;
pub type SharedStr<'s> = FlexStr<'s, str, Arc<str>>;

Even that you don't really need to concern yourself with. You can just use it how you would expect a simple wrapper to behave.

use flexstr::*;

// This will be a "Borrowed" variant
let hello: SharedStr = "hello".into();
assert!(hello.is_borrowed());

// This will be a "Boxed" variant
let world: SharedStr = "world".to_string().into();
assert!(world.is_boxed());

// This is now "Inlined" (since it is short)
let hello = hello.into_owned();
assert!(hello.is_inlined());

// This is now "Inlined" as well (since it is short)
let world = world.optimize();
assert!(world.is_inlined());

println!("{hello} {world}");

Performance

In general, it performs quite well given that it is mostly just a thin wrapper over the stdlib. See the benchmarks page for more details.

AI Usage

The code was written by hand with care (although AI tab completion was used). Any contributions should be completely understood by the contributor, whether AI assisted or not.

The tests on the otherhand were 90%+ generated by AI under my instruction. I've done a cursory review for sanity, but they need more work. Volunteers welcome.

Status

This is currently experimental, however, I will be using this at a startup in production code, so it will become production ready at some point.

Contributions

Contributions are welcome so long as they align to my vision for this crate. Currently, it does most of what I want it to do (outside of string construction and mutation, but I'm not ready to start on that yet).

License

This project is licensed optionally under either:

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)