# flexstr
[](https://crates.io/crates/flexstr)
[](https://docs.rs/flexstr)
[](https://github.com/nu11ptr/flexstr/actions)
[](https://codecov.io/gh/nu11ptr/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:
```rust,ignore
// `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.
```rust
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](benchmarks/README.md) 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>)