nonempty_tools 0.1.0

# nonempty_tools


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

## ✨ 特性


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

## 📦 包含类型


| 类型 | 描述 |
|------|------|
| `NonEmptyVec<T>` | 非空向量 |
| `NonEmptySliceRef<'a, T>` | 非空切片引用（不可变） |
| `NonEmptySliceRefMut<'a, T>` | 非空切片引用（可变） |
| `NonEmptyString` | 非空字符串 |
| `NonEmptyStr<'a>` | 非空字符串切片引用 |
| `NonEmptyVecDeque<T>` | 非空双端队列 |

## 🚀 快速开始


```rust
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();
```

## 💡 设计原则


### 仅初始化时检验


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

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

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

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


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

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

### 提供 `into_inner` 方法


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

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

## 📚 API 示例


### NonEmptyVec


```rust
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


```rust
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


```rust
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