ustr

快速，FFI 兼容的字符串国际化。

[!NOTE] 这是 ustr 的分支，用 ahash 替换 fxhash 以实现一致的哈希。

一个 Ustr (Uique 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 以来更改

• 实际上将“序列化”功能的用法重命名为“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 已存在的情况下创建它。这在使用不可信用户输入（例如从 Web 服务器或 API）创建 Ustr 时特别有用。在这种情况下，通过在每次调用中提供不同的值，我们消耗越来越多的内存，最终耗尽（DoS）。

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

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

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

• 修复测试，以正确处理启用时的情况（由 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。这将比之前的派生实现要慢，因为之前的实现只是进行了指针比较，但要好得多。

自0.3以来的变更

• 将Miri添加到CI测试中

  Miri对代码中的不安全部分进行sanity-check，以防止某些类型的UB。

• 将默认哈希器切换为ahash

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

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