Crate arcstr[−][src]
Expand description
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
Conceptually equivalent to ArcStr::from(format!("...", args...)).
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”.
feature = "substr": Create a const Substr.