Lib.rs

› 嵌入式开发 | 内存管理
#vec #fallible #collection #no-std

no-std fallible_vec

为 Rust 标准库中的 Vec 类型提供可能失败的分配函数

由 Daniel Paoliello 和 2 位贡献者 提供。 由 Arlo Siemsen 共同拥有。

4 个版本 (2 个破坏性更新)

0.3.1 2023 年 4 月 26 日
0.3.0 2023 年 3 月 15 日
0.2.0 2023 年 3 月 14 日
0.1.0 2023 年 3 月 9 日

#252 在 嵌入式开发

Download history 4/week @ 2024-03-27 7/week @ 2024-04-03 12/week @ 2024-04-10 32/week @ 2024-04-17 159/week @ 2024-04-24 73/week @ 2024-05-01 41/week @ 2024-05-08 48/week @ 2024-05-15 85/week @ 2024-05-22 48/week @ 2024-05-29 61/week @ 2024-06-05 31/week @ 2024-06-12 83/week @ 2024-06-19 67/week @ 2024-06-26

每月 260 次下载

自定义许可证

57KB
814 行

Vec 的可能失败分配函数

为 Rust 标准库中的 alloc::vec::Vec 类型提供可能失败的分配函数。

这些函数旨在与 #![no_std]、#[cfg(no_global_oom_handling)] (见 https://github.com/rust-lang/rust/pull/84266) 和分配器 (见 https://github.com/rust-lang/wg-allocators) 一起使用。

默认情况下，此 crate 需要 nightly 编译器，但如果禁用所有功能，则可以使用稳定编译器 (即，为依赖项指定 default-features = false)。

使用方法

将这些函数添加到 Vec 的推荐方法是添加一个 use 声明来指定 FallibleVec 特性：use fallible_vec::FallibleVec

use fallible_vec::{FallibleVec, try_vec};

let mut vec = try_vec![1, 2]?;
vec.try_push(3)?;
assert_eq!(vec, [1, 2, 3]);

恐慌安全性

这些方法都是“panic 安全”的，这意味着如果调用外部代码（例如，迭代器的 next() 方法或 Clone::clone() 的实现）发生 panic，则这些方法会将 Vec 留在一个一致的状态

  • len() 将小于或等于 capacity()。
  • 0..len() 中的项将只包括最初在 Vec 中的项或正在添加到 Vec 中的项。它永远不会包括未初始化的内存、重复的项或已删除的项。
  • 原本（但不再）在 Vec 中或正在添加到（但尚未在）Vec 中的项可能会泄漏——任何可能泄漏此类项的方法都将有注释来指定其行为。

每个方法的详细行为在它的文档中指定。

代码来源

大部分代码是从 Rust 的标准库 分支出来的。虽然我们会尽力保持代码和文档的一致性，但如果您发现任何问题，请首先检查它们是否已在标准库中修复。

此 API 不完整

在 Vec 上还有许多尚未移植的不可靠函数。如果您缺少特定的 API，请随时打开一个 PR 或提交一个问题，以便将其添加。

为什么这些还没有在标准库中？

有一个 PR 将这些和其他功能添加到标准库中，随后是一个 RFC 来讨论是否应该这样做。

为什么我会使用这个包而不是类似的包？

通常，fallible_vec 只在需要 #[cfg(no_global_oom_handling)] 的情况下有用，或者在使用分配器 API（以 _in 结尾的函数）。其他包使用在 #[cfg(no_global_oom_handling)] 启用时不存在（例如，vec::push）的 API，而 fallible_vec 重新实现了每个函数以避免这些 API，并在其 CI 中构建 #[cfg(no_global_oom_handling)]。

fallible_vec 专注于 vec 本身，而其他包提供对其他类型（如 Box 和 HashMap）的支持。

比较 fallible_vec 与 fallible_collections

fallible_vec v0.3.1 fallible_collections v0.4.7
支持 no_std X X
支持 #[cfg(no_global_oom_handling)] X
默认情况下需要使用nightly rust编译器 X
支持稳定的rust编译器 X X
vec::try_append X
vec::try_extend X
vec::try_extend_from_slice X X
vec::try_insert X X
vec::try_push X X
vec::try_push_give_back X
vec::try_resize X X
vec::try_resize_with X X
vec::try_splice_in X
try_collect X X
try_collect_in X
try_from_iterator X
try_with_capacity X
try_with_capacity_in X
try_vec! X
try_vec_in! X
Box::* X
Arc::* X
Rc::* X
HashMap::* X
try_format! X

本地构建

本地构建推荐使用 build.ps1 脚本：这将使用所有功能组合构建crate，运行测试，检查格式，运行clippy，并启用 #[cfg(no_global_oom_handling)] 构建。

为了运行此脚本，您需要

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当装饰PR（例如，状态检查，评论）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的存储库中进行一次此操作。

本项目已采用 Microsoft Open Source Code of Conduct。有关更多信息，请参阅 行为准则常见问题解答 或联系 [email protected] 询问任何额外的问题或评论。

商标

本项目可能包含项目、产品或服务的商标或徽标。授权使用Microsoft商标或徽标需遵守并遵循 Microsoft的商标 & 品牌指南。在修改本项目版本的商标或徽标中使用Microsoft商标或徽标不得引起混淆或暗示Microsoft赞助。任何使用第三方商标或徽标的使用均受那些第三方政策的约束。

依赖关系

~43KB