18 个稳定版本
| 新 1.1.9 | 2024年8月18日 |
|---|---|
| 1.1.7 | 2024年5月14日 |
| 1.1.6 | 2023年7月12日 |
| 1.1.4 | 2023年3月10日 |
| 1.0.4 | 2021年3月19日 |
#2 in 文件系统
2,887,422 每月下载量
在 2,519 个 Crates 中使用 (294 直接使用)
125KB
1.5K SLoC
camino - UTF-8 路径
此仓库包含 camino 的源代码，它是 std::path 模块的一个扩展，添加了新的 Utf8PathBuf 和 Utf8Path 类型。
什么是 camino？
camino 的 Utf8PathBuf 和 Utf8Path 类型类似于标准库中的 PathBuf 和 Path 类型，但它们保证只包含 UTF-8 编码的数据。因此，它们可以以字符串的形式获取其内容，实现了 Display 等功能。
std::path 类型并不保证是有效的 UTF-8。对于标准库来说，这是一个正确的决定，因为它必须尽可能地通用。然而，由于许多原因，所有平台上的非 Unicode 路径极其罕见。
- Unicode 获胜了。仍然有一些遗留代码库将路径存储在类似 Shift JIS 的编码中，但大多数都已经转换为 Unicode。
- Unicode 是 Windows 和 Unix 平台支持的路径的公共子集。（在 Windows 上，Rust 将路径存储为 UTF-8 的扩展，并在 Win32 API 边界处转换为 UTF-16。）
- 已经有许多系统，如Cargo，仅支持UTF-8路径。如果您的工具与任何此类系统交互，您可以在不增加任何额外负担的情况下假定路径是有效的UTF-8。
- “makefile问题”（见"makefile问题"链接）询问：给定一个Makefile或其他元数据文件（例如
Cargo.toml），其中列出了其他文件的名称，如何将Makefile中的名称与磁盘上的名称匹配？在支持非UTF-8路径的系统中，这没有通用的跨平台解决方案。然而，将路径限制为UTF-8可以消除这个问题。
因此，许多想要操作路径的程序确实假设它们包含UTF-8数据，并在必要时将它们转换为str。然而，因为此不变性没有编码在Path类型中，因此需要重复进行类似path.to_str()unwrap()的转换，这造成了一种令人沮丧的体验。
相反，camino允许您检查您的路径是否为UTF-8 一次，然后从那里开始将它们作为有效的UTF-8进行操作，从而避免重复的损失性和令人困惑的转换。
示例
Utf8PathBuf和Utf8Path的文档包含几个示例。
有关如何与其他库（如serde和clap）一起使用camino的示例，请参阅camino-examples目录。
API设计
camino是围绕std::path的一个非常薄的包装。 Utf8Path和Utf8PathBuf是Path和PathBuf的直接替换。
大多数API是相同的，但与str的边界API有所不同。以下是一些示例
Path::to_str()已被重命名为Utf8Path::as_str()。Utf8Path实现了Display，并且已删除Path::display()。- 遍历一个
Utf8Path返回&str，而不是&OsStr。
每个Utf8Path都是一个有效的Path，因此Utf8Path实现了AsRef<Path>。任何接受impl AsRef<Path>的API都将继续与Utf8Path实例一起工作。
你应该使用camino吗？
camino在简洁性与一些实用性之间做了权衡。是否使用camino取决于项目本身，是一个个案决定。以下是一些一般性指南，可能会有所帮助。
以下情况下，你应该考虑使用camino...
- 你正在构建可移植的、跨平台软件。尽管Unix和Windows平台都支持不同类型的非Unicode路径，但Unicode是它们共同支持的子集。
- 你的系统中包含包含其他文件名称的文件。如果你不使用UTF-8路径，你将遇到上面描述的makefile问题，这个问题没有通用的、跨平台的解决方案。
- 你正在与已经假设使用UTF-8路径的现有系统交互。在这种情况下，你不会给下游消费者带来任何新的负担。
- 你正在构建全新的东西，并且愿意在必要时要求用户重命名它们的路径。不需要担心向后兼容性的项目在选择支持哪些路径方面有更多的灵活性。
一般来说，使用camino是大多数项目的正确选择。
以下情况下，你不应该使用camino...
- 你正在编写核心系统实用工具。如果你正在编写，比如
mv或cat的替代品，你应该不使用camino。相反，使用std::path::Path并为非UTF-8路径添加广泛的测试。 - 你有向后兼容性的限制。例如，Git支持非UTF-8路径。如果你的工具需要处理任意的Git仓库，它应该使用其自己的路径类型，该类型是围绕
Vec<u8>的包装。std::path::Path在Unix上支持任意字节数组，但在Windows上不支持。
- 你有其他需要支持非UTF-8路径的原因。一些工具，如磁盘恢复实用工具，需要处理可能损坏的文件名：仅能处理UTF-8路径将大大降低它们的实用性。
可选功能
默认情况下，camino除了std之外没有其他依赖。有一些可选功能可以启用依赖。
serde1为Utf8PathBuf和Utf8Path（零拷贝）添加了serdeSerialize和Deserialize实现。proptest1为 proptest 添加了Arbitrary实现用于Utf8PathBuf和Box<Utf8Path>。
注意：启用
serde或proptest功能将不会做任何事情。您必须分别启用serde1和proptest1功能。
Rust 版本支持
默认功能下，camino 的最低支持 Rust 版本（MSRV）为 1.34。本项目在 CI 中与 Rust 的最新稳定版本和 MSRV 进行了测试。
- 后续 Rust 版本中添加的 稳定 API 通过
build.rs中的条件编译或在也适用于旧版本的回补中支持。 - 弃用 与它们添加的 Rust 版本保持同步。
- 不稳定 API 目前不支持。如果您需要不稳定 API，请在 GitHub 上 提交一个问题。
camino 被设计为一个核心库，并具有保守的 MSRV 策略。只有在有足够充分的理由时，MSRV 才会增加，并且至少涉及一个次要版本的增加。
可选功能可能会引入需要较新版本 Rust 的依赖项。
许可证
本项目可在 Apache 2.0 许可证 或 MIT 许可证 的条款下获得。
本项目的文档是从 Rust 编程语言 中改编的，该语言可在 Apache 2.0 许可证 或 MIT 许可证 的条款下获得。
依赖项
~0–680KB
~13K SLoC