Module arcstr 

Better reference counted strings

Fork of https://github.com/thomcc/arcstr/

License and version information can be found at https://github.com/plabayo/rama/tree/main/docs/thirdparty/fork.

This crate defines ArcStr, a type similar to Arc<str>, but with a number of new features and functionality. There’s a list of benefits in the ArcStr documentation comment which covers some of the reasons you might want to use it over other alternatives.

Additionally, if the substr feature is enabled (and it is by default), we provide a Substr type which is essentially a (ArcStr, Range<usize>) with better ergonomics and more functionality, which represents a shared slice of a “parent” ArcStr (note that in reality, u32 is used for the index type, but this is not exposed in the API, and can be transparently changed via a cargo feature).

Feature overview

A quick tour of the distinguishing features:

use rama_utils::str::arcstr::{ArcStr, arcstr};

// Works in const:
const MY_ARCSTR: ArcStr = arcstr!("amazing constant");
assert_eq!(MY_ARCSTR, "amazing constant");

// `arcstr!` input can come from `include_str!` too:
const MY_ARCSTR: ArcStr = arcstr!(include_str!("my-best-files.txt"));

Or, you can define the literals in normal expressions. Note that these literals are essentially “Zero Cost”. Specifically, below we not only avoid allocating any heap memory to instantiate wow or any of the clones, we also don’t have to perform any atomic reads or writes.

use rama_utils::str::arcstr::{ArcStr, arcstr};

let wow: ArcStr = arcstr!("Wow!");
assert_eq!("Wow!", wow);
// This line is probably not something you want to do regularly,
// but causes no extra allocations, nor performs any atomic reads
// nor writes.
let wowzers = wow.clone().clone().clone().clone();

// At some point in the future, we can get a `&'static str` out of one
// of the literal `ArcStr`s too. Note that this returns `None` for
// a dynamically allocated `ArcStr`:
let static_str: Option<&'static str> = ArcStr::as_static(&wowzers);
assert_eq!(static_str, Some("Wow!"));

Of course, this is in addition to the typical functionality you might find in a non-borrowed string type (with the caveat that there is explicitly no way to mutate ArcStr).

Structs

ArcStr

A better atomically-reference counted string type.

Substr

A low-cost string type representing a view into an ArcStr.