`arcstr`：更优秀的引用计数字符串

最低 Rust 版本

这个 crate 定义了 ArcStr，一个引用计数的字符串类型。它本质上试图成为一个更好的 Arc<str> 或 Arc<String>，至少对于大多数用例而言是如此。

ArcStr 有意放弃了一些 Arc 中很少用于 Arc<str> 的功能（如 Weak、Arc::make_mut 等）。作为交换，它获得了许多非常有用的功能，特别是对于字符串而言。值得注意的是，它对持有静态数据（例如，字符串字面量）的廉价/零成本 ArcStr 提供了强大支持。

（除此之外，它还是一个单指针，这对性能和 FFI 都有好处）

此外，如果启用了 substr 功能（默认启用），我们还提供了一个 Substr 类型，它本质上是一个具有更好人体工程学和更多功能的 (ArcStr, Range<usize>)，表示 "父" ArcStr 的共享切片（注意，实际上使用 u32 作为索引类型，但这在 API 中并未暴露，可以通过 cargo 功能透明地更改）。

功能概览

快速浏览一下其独特功能（注意，在 ArcStr 文档中有一个优势列表，涵盖了你可能想使用它而不是其他替代方案的一些原因）。请注意，它提供了你可能期望从不可变字符串类型中获得的几乎全套字符串功能 — 以下只是独特的卖点：

use arcstr::ArcStr;
// 可在 const 中使用：
const AMAZING: ArcStr = arcstr::literal!("amazing constant");
assert_eq!(AMAZING, "amazing constant");

// `arcstr::literal!` 的输入也可以来自 `include_str!`：
const MY_BEST_FILES: ArcStr = arcstr::literal!(include_str!("my-best-files.txt"));

或者，你可以在普通表达式中定义字面量。注意，这些字面量本质上是"零成本"的。具体来说，下面我们不仅不需要分配任何堆内存来实例化 wow 或任何克隆，在克隆或删除它们（或对它们进行任何其他操作）时也不需要执行任何原子读取或写入。

let wow: ArcStr = arcstr::literal!("Wow!");
assert_eq!("Wow!", wow);
// 这行可能不是你想经常做的事，
// 但如前所述，它不会导致额外的分配，也不会执行任何
// 原子加载、存储、读-修改-写等操作。
let wowzers = wow.clone().clone().clone().clone();

// 在将来的某个时候，我们也可以从字面量 `ArcStr` 中
// 获取一个 `&'static str`。
let static_str: Option<&'static str> = ArcStr::as_static(&wowzers);
assert_eq!(static_str, Some("Wow!"));

// 注意，对于动态分配的 `ArcStr`，这会返回 `None`：
let dynamic_arc = ArcStr::from(format!("cool {}", 123));
assert_eq!(ArcStr::as_static(&dynamic_arc), None);

待办事项：在这里包含 Substr 的用法，因为它也有一些引人注目的用例！

使用方法

这是一个普通的 rust crate，将其放入你的 Cargo.toml 的依赖部分。如果你不知道怎么做（虽然这种情况不太可能）：

[dependencies]
# ...
arcstr = { version = "...", features = ["..."] }

以下是可用的 cargo 功能。目前只有 substr 是默认启用的。

std（默认关闭）：启用以使用 std::process 的中止功能，而不是使用"双重恐慌技巧"触发中止。

本质上，我们只有在一种情况下需要中止，那就是在灾难性错误中，你在 32 位系统上泄漏了 2^31 个相同的（动态）ArcStr，或在 64 位系统上泄漏了 2^63 个。如果发生这种情况，我们遵循 libstd 的做法，直接中止，因为无论如何我们都已经完蛋了。如果启用了 std，我们使用真正的 std::process::abort。如果没有启用 std，我们通过在另一个恐慌展开时触发恐慌来触发 abort，这要么被定义为导致中止，要么在实践中导致中止。

实际上你永远不会遇到这种边缘情况，而且它在 no_std 中仍然有效，所以 no_std 是默认的。如果你必须打开这个，因为你遇到了这种荒谬的情况并发现我们的处理不好，请告诉我。

具体来说，这里的区别是，如果不启用这个功能，这种情况会变成对 core::intrinsics::abort 的调用，而不是 std::process::abort。这是一个极不可能遇到的边缘情况，但如果你真的遇到了，std::process::abort 会导致 SIGABRT，而 core::intrinsics::abort 会导致 SIGILL，前者的用户体验明显更好。也就是说，你极不可能泄漏 2^31 或 2^63 个相同 ArcStr 的副本，所以我们认为默认依赖 std 并不值得。
serde（默认关闭）：启用 ArcStr 的 serde 序列化。注意，这不会进行任何花哨的去重或其他操作。
substr（默认启用）：实现 Substr 类型及相关函数。
substr-usize-indices（默认关闭，隐含 substr）：在底层使用 usize 作为边界，而不是 u32。

如果不启用这个功能，当你使用 Substr 且索引会溢出 u32 时，我们会直接抛出 panic。

`unsafe` 的使用和测试策略

虽然这个 crate 确实包含相当数量的不安全代码，但我们通过以下方式来证明这是合理的：

我们有非常高的测试覆盖率（基本上唯一未覆盖的函数是内存不足处理程序（它只是调用 alloc::handle_alloc_error），以及一个极其病态的整数溢出情况，我们只是简单地中止）。
所有测试都在各种 sanitizer 下通过：asan、msan、tsan 和 miri。
我们有一些 loom 模型，尽管我希望能有更多。
我们的测试在大量不同的目标上都能通过（感谢 cross 使许多测试变得可能 — 甚至很容易）：
- Linux x86、x86_64、armv7（arm32）、aarch64（arm64）、riscv64、mips32 和 mips64（mips32 和 mips64 目标允许我们检查大端序 32 位和 64 位。尽管我们目前没有任何特定于字节序的代码）。
- Windows 32 位和 64 位，在 GNU 和 MSVC 工具链上。
- MacOS 上的 x86_64。

此外，我们在 Rust stable、beta、nightly 和我们的 MSRV（最小支持的 Rust 版本，见上面的徽章）上进行测试。

支持的平台

请注意，上面的列表并不是支持平台的列表。一般来说，我期望 arcstr 支持 Rust 支持的所有平台，除了那些 target_pointer_width="16" 的平台，如果你关闭 substr 功能，这些平台应该也能工作。也就是说，如果你希望我在 CI 覆盖中添加一个平台以确保它不会出现问题，只需问一声*（不过，如果这比为另一个 cross 目标添加一行更难，我可能需要你解释为什么现有的平台测试可能无法覆盖它）。

* 这就是为什么有 riscv64 的原因。