ustr

快速、FFI 友好的字符串池化。

A Ustr (Unique str) 是一个轻量级的句柄，代表全局字符串缓存中的静态不可变条目，允许进行

• 极快的字符串赋值和比较。

• 高效存储。只在内存中保留一个字符串副本，访问它只是指针间接。

• 快速哈希 - 预计算的哈希值与字符串一起存储。

• 快速 FFI - 字符串以终止空字节存储，可以直接传递给 C 而无需进行 CString 舞蹈。

缺点是永远不会释放字符串，所以如果你创建了很多很多字符串，可能会耗尽内存。另一方面，战争与和平 只有 3MB，所以应该没问题。

此 crate 基于 OpenImageIO 的 (OIIO) ustring，但它不是二进制兼容的（目前还不是）。底层哈希图实现直接从 OIIO 端口。

用法

use ustr::{Ustr, ustr};

// Creation is quick and easy using either `Ustr::from` or the `ustr` short
// function and only one copy of any string is stored
let h1 = Ustr::from("hello");
let h2 = ustr("hello");

// Comparisons and copies are extremely cheap
let h3 = h1;
assert_eq!(h2, h3);

// You can pass straight to FFI
let len = unsafe {
    libc::strlen(h1.as_char_ptr())
};
assert_eq!(len, 5);

// For best performance when using Ustr as key for a HashMap or HashSet,
// you'll want to use the precomputed hash. To make this easier, just use
// the UstrMap and UstrSet exports:
use ustr::UstrMap;

// Key type is always Ustr
let mut map: UstrMap<usize> = UstrMap::default();
map.insert(u1, 17);
assert_eq!(*map.get(&u1).unwrap(), 17);

通过启用 "serde" 功能，您可以使用 serde 序列化单个 Ustr 或整个缓存。

use ustr::{Ustr, ustr};

let u_ser = ustr("serialization is fun!");
let json = serde_json::to_string(&u_ser).unwrap();
let u_de : Ustr = serde_json::from_str(&json).unwrap();

assert_eq!(u_ser, u_de);

由于缓存是全局的，请使用 ustr::DeserializedCache 模拟对象来驱动反序列化。

ustr("Send me to JSON and back");
let json = serde_json::to_string(ustr::cache()).unwrap();

// ... some time later ...
let _: ustr::DeserializedCache = serde_json::from_str(&json).unwrap();
assert_eq!(ustr::num_entries(), 1);
assert_eq!(ustr::string_cache_iter().collect::<Vec<_>>(), vec!["Send me to JSON and back"]);

C/C++ 调用

如果您正在编写使用 ustr 的库，并希望用户能够从 C 创建 Ustr 并将其传递给您的 API，请将 ustr_extern.rs 添加到您的 crate 中，并使用 include/ustr.h 或 include/ustr.hpp 进行函数声明。

变更日志

自 0.10 以来更改

• 实际上将 "serialization" 功能的名称重命名为 "serde"

自 0.9 以来更改

• 修复了会导致 Ustr 在 wasm32-unknown-unknown 上无法工作的问题（由 bouk 贡献）

并感谢 virtualritz

• Ustr::get_cache() 已更名为 cache()

• 所有依赖项都已升级到最新版本

• 移除了所有功能（有良好的默认值）除 serialization 外

• serialization 功能已更名为 serde

• ustr 现在使用 Rust 2021

自 0.8 以来更改

• 添加 existing_ustr 函数（由 macprog-guy 贡献）

  这个想法是在 Ustr 已经存在的情况下才创建一个 Ustr。这在使用不受信任的用户输入（例如来自 Web 服务器或 API）创建 Ustr 时特别有用。在这种情况下，通过在每次调用中提供不同的值，我们最终会消耗越来越多的内存，最终耗尽（DoS）。

• 添加 Ord 实现（由 zigazeljko 贡献）

• 内联了一些简单函数（由 g-plane 贡献）

• 修复了测试，改为锁定而不是依赖于 RUST_TEST_THREADS=1（由 kornelski 贡献）

• 修复了测试，以便在启用时正确处理 serialization 功能（由 kornelski 贡献）

• 添加了对分配器中潜在分配失败检查（由 kornelski 贡献）

• 添加 FromStr 实现（由 martinmr 贡献）

• 将 rustfmt.toml 添加到仓库

自 0.7 以来的更改

• 更新依赖项

  已更新 parking_lot 和 ahash 的版本。

• 使用 NonNull 进行空间优化

  内部指针现在是 NonNull，以利用 Option 等中的布局优化。

• 添加 as_cstr() 方法

  添加了 as_cstr(&self) -> std::ffi::CStr 以便于与依赖于 CStr 的 API 进行交互。

自 0.6 以来的更改

• 为 Ustr 导入 Ord

  因此现在您可以按字典顺序对 Vec 中的 Ustr 进行排序。

自 0.5 以来的更改

• 为 &str 添加 From<Ustr>

  此 impl 使将 Ustr 传递给期望 Into<&str> 的方法的函数变得更加容易。

自 0.4 以来的更改

• 添加了对 32 位支持

  已移除对64位系统的限制，并修复了与指针算术相关的错误。感谢agaussman提出这个问题。

• 重新启用了Miri泄漏检查

  感谢RalfJung指出Miri现在忽略了“从静态中泄漏”。

• PartialOrd现在是字典序的

• 感谢macprog-guy实现了通过延迟到&str来实现的PartialOrd的PR。这将比之前仅进行指针比较的派生实现慢，但要好得多令人惊讶。

自0.3以来的变更

• 将Miri添加到CI测试中

  Miri会检查代码的不安全部分以防止某些类型的未定义行为。

• 将默认哈希器切换到ahash

  Ahash是一个快速的非加密纯Rust哈希器。纯Rust很重要，以便能够运行Miri，ahash是我能找到的运行速度最快的。旧版本的fasthash/cityhash可以通过启用--features=hashcity来使用

/cgi-bin/images/admin
/modules/templates/cache
/libraries/themes/wp-includes
... etc.