[−][src]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.

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 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).

It's an open TODO to update this "feature tour" to include Substr.

Macros

format	Conceptually equivalent to `ArcStr::from(format!("...", args...))`.
literal	Create a const `ArcStr` from a string literal. The resulting `ArcStr` require no heap allocation, can be freely cloned and used interchangeably with `ArcStr`s from the heap, and are effectively "free".
literal_substr	`feature = "substr"`: Create a `const` `Substr`.

Structs

ArcStr	A better atomically-reference counted string type.
Substr	A low-cost string type representing a view into an `ArcStr`.