inline_flexstr

A simple to use, copy/clone-efficient inline string type for Rust

Overview

A fast inline string crate. Essentially it never allocates on the heap, but is limited currently to strings that are 2 bytes less than 3 machine words in length (10 bytes on 32-bit, 22 bytes on 64-bit). It is generic over all the Rust string types (str, CStr, OsStr, Path, [u8]).

Features

• Implements Copy
• O(1) copy/clone
• Mutable
• Same size a a String (3 words wide, even inside an Option)
• 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

use inline_flexstr::*;

let hello: InlineStr = "hello".try_into().expect("string too long");
let world: InlineCStr = c"world!".try_into().expect("string too long");

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)