arcstr/
lib.rs

1//! # Better reference counted strings
2//!
3//! This crate defines [`ArcStr`], a type similar to `Arc<str>`, but with a
4//! number of new features and functionality. There's a list of
5//! [benefits][benefits] in the `ArcStr` documentation comment which covers some
6//! of the reasons you might want to use it over other alternatives.
7//!
8//! Additionally, if the `substr` feature is enabled (and it is by default), we
9//! provide a [`Substr`] type which is essentially a `(ArcStr, Range<usize>)`
10//! with better ergonomics and more functionality, which represents a shared
11//! slice of a "parent" `ArcStr` (note that in reality, `u32` is used for the
12//! index type, but this is not exposed in the API, and can be transparently
13//! changed via a cargo feature).
14//!
15//! [benefits]: struct.ArcStr.html#benefits-of-arcstr-over-arcstr
16//!
17//! ## Feature overview
18//!
19//! A quick tour of the distinguishing features:
20//!
21//! ```
22//! use arcstr::ArcStr;
23//!
24//! // Works in const:
25//! const MY_ARCSTR: ArcStr = arcstr::literal!("amazing constant");
26//! assert_eq!(MY_ARCSTR, "amazing constant");
27//!
28//! // `arcstr::literal!` input can come from `include_str!` too:
29//! # // We have to fake it here, but this has test coverage and such.
30//! # const _: &str = stringify!{
31//! const MY_ARCSTR: ArcStr = arcstr::literal!(include_str!("my-best-files.txt"));
32//! # };
33//! ```
34//!
35//! Or, you can define the literals in normal expressions. Note that these
36//! literals are essentially ["Zero Cost"][zero-cost]. Specifically, below we
37//! not only avoid allocating any heap memory to instantiate `wow` or any of
38//! the clones, we also don't have to perform any atomic reads or writes.
39//!
40//! [zero-cost]: struct.ArcStr.html#what-does-zero-cost-literals-mean
41//!
42//! ```
43//! use arcstr::ArcStr;
44//!
45//! let wow: ArcStr = arcstr::literal!("Wow!");
46//! assert_eq!("Wow!", wow);
47//! // This line is probably not something you want to do regularly,
48//! // but causes no extra allocations, nor performs any atomic reads
49//! // nor writes.
50//! let wowzers = wow.clone().clone().clone().clone();
51//!
52//! // At some point in the future, we can get a `&'static str` out of one
53//! // of the literal `ArcStr`s too. Note that this returns `None` for
54//! // a dynamically allocated `ArcStr`:
55//! let static_str: Option<&'static str> = ArcStr::as_static(&wowzers);
56//! assert_eq!(static_str, Some("Wow!"));
57//! ```
58//!
59//! Of course, this is in addition to the typical functionality you might find in a
60//! non-borrowed string type (with the caveat that there is explicitly no way to
61//! mutate `ArcStr`).
62//!
63//! It's an open TODO to update this "feature tour" to include `Substr`.
64#![cfg_attr(not(feature = "std"), no_std)]
65#![deny(missing_docs)]
66#![allow(unknown_lints)]
67// for `cfg(loom)` and such -- I don't want to add a build.rs for this.
68#![allow(unexpected_cfgs)]
69
70#[doc(hidden)]
71pub extern crate alloc;
72
73#[doc(hidden)]
74pub use core;
75
76#[macro_use]
77mod mac;
78mod arc_str;
79#[cfg(feature = "serde")]
80mod impl_serde;
81pub use arc_str::ArcStr;
82
83#[cfg(feature = "substr")]
84mod substr;
85#[cfg(feature = "substr")]
86pub use substr::Substr;
87
88// Not public API, exists for macros
89#[doc(hidden)]
90pub mod _private {
91    // Not part of public API. Transmutes a `*const u8` to a `&[u8; N]`.
92    //
93    // As of writing this, it's unstable to directly deref a raw pointer in
94    // const code. We can get around this by transmuting (using the
95    // const-transmute union trick) to transmute from `*const u8` to `&[u8; N]`,
96    // and the dereferencing that.
97    //
98    // ... I'm a little surprised that this is allowed, but in general I do
99    // remember a motivation behind stabilizing transmute in `const fn` was that
100    // the union trick existed as a workaround.
101    //
102    // Anyway, this trick is courtesy of rodrimati1992 (that means you have to
103    // blame them if it blows up :p).
104    #[repr(C)]
105    pub union ConstPtrDeref<Arr: Copy + 'static> {
106        pub p: *const u8,
107        pub a: &'static Arr,
108    }
109    pub use crate::arc_str::StaticArcStrInner;
110    pub use core::primitive::{str, u8};
111}
arcstr/lib.rs

arcstr/
lib.rs
