nonempty_tools

优雅的 Rust 非空集合类型库，在编译时保证集合非空。

✨ 特性

• 零运行时开销 - 仅在初始化时验证非空
• 类型安全 - 编译时保证集合至少包含一个元素
• API 完整 - 提供与标准库类似的丰富 API
• 符合人体工程学 - 实现 Deref、Index、IntoIterator 等标准 trait

📦 包含类型

🚀 快速开始

use nonempty_tools::{NonEmptyVec, NonEmptyString};

// 创建非空向量
let vec = NonEmptyVec::new(1, vec![2, 3, 4]);
assert_eq!(vec.first(), &1);  // 保证安全访问第一个元素
assert_eq!(vec.len(), 4);

// 从现有集合创建
let vec = NonEmptyVec::try_from_vec(vec![1, 2, 3])?;

// 非空字符串
let name = NonEmptyString::try_from_str("Alice")?;
assert_eq!(name.as_str(), "Alice");

// 使用 into_inner 获取内部值
let inner_vec = vec.into_inner();

💡 设计原则

仅初始化时检验

所有非空类型只在构造时验证是否为空，之后不再有运行时检查：

// ✅ 构造时检验
let vec = NonEmptyVec::try_from_vec(vec![1, 2, 3])?;

// ✅ 运行时零开销
let first = vec.first();  // 无需 unwrap

不提供可能导致空集合的操作

只提供安全的操作，不提供 pop、remove、clear 等可能导致空集合的方法：

let mut vec = NonEmptyVec::from_single(1);
vec.push(2);        // ✅ 允许
vec.push(3);        // ✅ 允许
// vec.pop();       // ❌ 不存在此方法

提供 into_inner 方法

如果需要执行可能导致空集合的操作，使用 into_inner 获取内部值：

let vec = NonEmptyVec::new(1, vec![2, 3]);
let mut inner = vec.into_inner();
inner.pop();  // 现在可以自由操作

📚 API 示例

NonEmptyVec

use nonempty_tools::NonEmptyVec;

// 创建
let vec = NonEmptyVec::new(1, vec![2, 3]);
let vec = NonEmptyVec::from_single(42);
let vec = NonEmptyVec::try_from_vec(vec![1, 2, 3])?;

// 访问
let first = vec.first();
let last = vec.last();
let len = vec.len();

// 修改
let mut vec = NonEmptyVec::from_single(1);
vec.push(2);
*vec.first_mut() = 10;

// 迭代
for item in &vec {
    println!("{}", item);
}

NonEmptyString

use nonempty_tools::NonEmptyString;

// 创建
let s = NonEmptyString::new('h', "ello");
let s = NonEmptyString::from_char('A');
let s = NonEmptyString::try_from_str("hello")?;
let s: NonEmptyString = "hello".parse()?;

// 操作
let mut s = NonEmptyString::from_char('h');
s.push('i');
s.push_str("!");
assert_eq!(s.as_str(), "hi!");

NonEmptyVecDeque

use nonempty_tools::NonEmptyVecDeque;
use std::collections::VecDeque;

let mut deque = NonEmptyVecDeque::from_single(2);
deque.push_front(1);
deque.push_back(3);

assert_eq!(deque.front(), &1);
assert_eq!(deque.back(), &3);

🔧 使用场景

• 用户输入验证 - 确保用户名、文件名等不为空
• 配置管理 - 保证至少有一个配置项
• 算法实现 - 需要非空保证的算法（如取最小值、最大值）
• API 设计 - 在类型层面表达"必须非空"的约束

📄 许可证

MIT OR Apache-2.0