Crate flexstr

A flexible, simple to use, immutable, clone-efficient String replacement for Rust

String Creation from Literals

String constants are easily wrapped into the unified string type. String contents are inlined when possible otherwise allocated on the heap.

use flexstr::{local_str, LocalStr, ToLocalStr};

// Use `local_str` macro to wrap literals as compile-time constants
const STATIC_STR: LocalStr = local_str!("This will not allocate or copy");
assert!(STATIC_STR.is_static());

// Strings up to 22 bytes (on 64-bit) will be inlined automatically
// (demo only, use macro or `from_static` for literals as above)
let inline_str = "inlined".to_local_str();
assert!(inline_str.is_inline());

// When a string is too long to be wrapped/inlined, it will heap allocate
// (demo only, use macro or `from_static` for literals as above)
let rc_str = "This is too long to be inlined".to_local_str();
assert!(rc_str.is_heap());

String Creation and Manipulation

The stdlib format macro equivalent is used to create brand new strings. String operations like changing case and concatenation are efficiently supported (inlining when possible).

use flexstr::{local_fmt, LocalStr, ToCase};

// You can efficiently create a new `LocalStr` (without creating a `String`)
// This is equivalent to the stdlib `format!` macro
let inline_str = local_fmt!("in{}", "lined");
assert!(inline_str.is_inline());

// We can upper/lowercase strings without converting to a `String` first
// This doesn't heap allocate since inlined
let inline_str2: LocalStr = "INLINED".to_ascii_lower();
assert!(inline_str2.is_inline());
assert_eq!(inline_str, inline_str2);

// Concatenation doesn't even copy if we can fit it in the inline string
let inline_str3 = inline_str2 + "!!!";
assert!(inline_str3.is_inline());
assert_eq!(inline_str3, "inlined!!!");

Efficient, Universal String Type

Clones never copy or allocate and are very fast. Regardless of underlying storage type, all strings work together and resulting strings automatically choose the best storage.

use flexstr::{local_str, LocalStr, ToLocalStr};

// Clone is cheap, and never allocates
// (at most it is a ref count increment for heap allocated strings)
let rc_str = "This is too long to be inlined".to_local_str().clone();
assert!(rc_str.is_heap());

// Regardless of storage type, these all operate seamlessly together
// and choose storage as required
const STATIC_STR: LocalStr = local_str!("This will eventually end up on the ");
let inline_str = "heap".to_local_str();

let heap_str2 = STATIC_STR + &inline_str;
assert!(heap_str2.is_heap());
assert_eq!(heap_str2, "This will eventually end up on the heap");  

Macros

local_fmt

Equivalent to format! macro from stdlib. Efficiently creates a native LocalStr

local_str

Create compile time constant LocalStr (equivalent, but less typing than: LocalStr::from_static("my_literal")

local_ufmt

Equivalent to [local_fmt] except that it uses ufmt which is much faster, but has limitations. See ufmt docs for more details

shared_fmt

Equivalent to format! macro from stdlib. Efficiently creates a native SharedStr

shared_str

Create compile time constant SharedStr (equivalent, but less typing than: SharedStr::from_static("my_literal")

shared_ufmt

Equivalent to [shared_fmt] except that it uses ufmt which is much faster, but has limitations. See ufmt docs for more details

Structs

WrongStorageType

Error type returned from try_as_static_str or try_to_heap when this FlexStr does not contain the expected type of storage

Enums

StorageType

Represents the storage type used by a particular FlexStr

Constants

PTR_SIZED_PAD

Padding the size of a pointer for this platform minus one

STRING_SIZED_INLINE

Using this inline capacity will result in a type with the same memory size as a builtin String

Traits

IntoFlex

A trait that converts the source to a FlexStr while consuming the original

IntoLocalStr

A trait that converts the source to a LocalStr while consuming the original

IntoSharedStr

A trait that converts the source to a SharedStr while consuming the original

Repeat

Trait that can repeat a given FlexStr “n” times efficiently

ToCase

Trait that provides uppercase/lowercase conversion functions for FlexStr

ToFlex

A trait that converts the source to a FlexStr without consuming it

ToLocalStr

A trait that converts the source to a LocalStr without consuming it

ToSharedStr

A trait that converts the source to a SharedStr without consuming it

Functions

flex_fmt

Equivalent to the format function from stdlib. Efficiently creates a native FlexStr

Type Aliases

FlexStrBase

A flexible base string type that transparently wraps a string literal, inline string, or a custom HEAP type

LocalStr

A flexible string type that transparently wraps a string literal, inline string, or an Rc<str>

SharedStr

A flexible string type that transparently wraps a string literal, inline string, or an Arc<str>

Unions

FlexStr

A flexible string type that transparently wraps a string literal, inline string, or a heap allocated type