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
Substr type which is essentially a
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).
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
It’s an open TODO to update this “feature tour” to include
Conceptually equivalent to
Create a const
ArcStr from a string literal. The
ArcStr require no heap allocation, can be freely cloned and used
ArcStrs from the heap, and are effectively “free”.
feature = "substr": Create a