Lib.rs

Mitsein 是一个 Rust 库，提供非空集合和视图的强类型 API，包括（但不限于）迭代器、切片和向量。

基本用法

从一个或多个项目（必定成功）分配 Vec1

use mitsein::prelude::*;

let xs = Vec1::from_one(0i32);
let xs = Vec1::from([0i32, 1, 2]);
let xs = Vec1::from_head_and_tail(0i32, [1, 2]);

let xs: Vec1<_> = [0i32].into_iter1().collect1();

let xs = vec1![0i32, 1, 2];

从零个或多个项目（可能失败）分配 Vec1

use mitsein::prelude::*;

let ys = vec![0i32, 1, 2];

let xs = Vec1::try_from(ys).unwrap();
let xs = Vec1::try_from(&[0i32, 1, 2]).unwrap();
let xs = Vec1::try_from_iter([0i32, 1, 2]).unwrap();

let xs: Vec1<_> = [0i32].into_iter().try_collect1().unwrap();

遍历 Vec1 中的项目

use mitsein::prelude::*;

let xs = Vec1::from([0i32, 1, 2]);
let ys: Vec1<_> = xs.into_iter1().map(|x| x + 1).collect1();

从 Vec1 中移除项目

use mitsein::prelude::*;

let mut xs = Vec1::from([0i32, 1, 2]);
while let Ok(item) = xs.pop_or_get_only() { ... }

let mut xs = Vec1::from([0i32, 1, 2]);
xs.tail().clear();

在 Iterator 和 Iterator1 之间桥接

use mitsein::iter1;
use mitsein::prelude::*;

let xs = iter1::head_and_tail(0i32, [1, 2]);
let xs: Vec1<_> = xs.into_iter().skip(3).or_non_empty([3]).collect1();
assert_eq!(xs.as_slice(), &[3]);

功能和比较

非空迭代器 API 与标准 API 一样，通过熟悉的模式和语法分离关注点。 Mitsein 无需在非空集合中公开组合函数集的固有迭代器-like 函数。例如，vec1 包支持通过 Vec1::mapped、Vec1::mapped_ref 和 Vec1::mapped_mut 函数对其 Vec1 类型的映射操作。Mitsein 通过 Iterator1 提供映射操作，它支持任何具有更典型 API 的非空视图或集合（Iterator1::map）。

非空切片 API 允许借用和写时复制，因此 Mitsein 支持标准的 Cow 类型，与像 nonempty 和 vec1 这样的其他非空 Vec 实现。

物品在Mitsein中一致存储。 没有头项被分配得不同。例如，nonempty 包直接暴露一个头项，与尾项不同，不是在堆上分配的。这可能会引起令人惊讶的行为或性能。

表现出不同行为的非空集合API与Mitsein中的对应者不同。例如，vec1 包提供了 Vec1::pop 和 Vec1::remove，这在上下文中可能不清楚。相反，Mitsein提供了例如 Vec1::pop_or_get_only 和 Vec1::remove_or_replace_only 这样的API。

Mitsein将许多非空错误关注点分离成一个分段API。 分段覆盖了一个集合的范围，并支持拓扑突变（例如，删除项）。例如，在删除操作之前可以对非空集合进行分段。例如，nonempty 和 nunny 包对删除的支持有限（或没有），而 vec1 包提供了可失败但定制的对应者。

use mitsein::prelude::*;

let mut xs = Vec1::from([0i32, 1, 2, 3, 4]);
xs.tail().clear();
assert_eq!(xs.as_slice(), &[0i32]);

let mut xs = Vec1::from([0i32, 1, 2, 3, 4]);
xs.tail().rtail().drain(..);
assert_eq!(xs.as_slice(), &[0i32, 4]);

let mut xs = Vec1::from([0i32, 1, 2, 3, 4]);
xs.segment(1..).truncate(2);
assert_eq!(xs.as_slice(), &[0i32, 1, 2]);

Mitsein在core和alloc中提供了有序集合和堆容器API的完整覆盖。 这包括slice、BTreeMap、BTreeSet、Box和Arc。（BinaryHeap是一个有意外的例外。）nonempty 和 vec1 包不支持如slice这样的原始类型以及除了Vec之外的其他集合。

Mitsein是一个no_std库，且alloc是可选的。非空切片、迭代器和数组可以在没有操作系统功能或分配的环境中使用的上下文中使用。 与arrayvec的集成也在no_std环境中工作。

Cargo功能

Mitsein通过以下Cargo功能提供了一些可选功能和集成。

某些功能启用其他包和依赖项的功能。例如，std启用了alloc，并且这两个功能在适用时都启用了可选依赖项中类似的功能。