Crate arcstr

Better reference counted strings

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

(Aside: eventually, my hope is to provide a couple utility types built on top of ArcStr, but for now, just the main one).

Feature overview

A quick tour of the distinguishing features:

use arcstr::ArcStr;

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

// `arcstr::literal!` input can come from `include_str!` too:
const MY_ARCSTR: ArcStr = arcstr::literal!(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 don't allocate any heap memory to instantiate wow or any of the clones, we also don't have to perform any atomic reads or writes.

use arcstr::ArcStr;

let wow: ArcStr = arcstr::literal!("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
// 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 a non-borrowed string type (with the caveat that no way to mutate ArcStr is provided intentionally).

Macros

literal

Create a const ArcStr from a string literal. The resulting ArcStr require no heap allocation, can be freely cloned and used interchangeably with ArcStrs from the heap, and are effectively "free".

Structs

ArcStr

A better atomically-reference counted string type.