net-bytes 0.2.0

# Net Bytes


[![Crates.io](https://img.shields.io/crates/v/net-bytes)](https://crates.io/crates/net-bytes)
[![文档](https://docs.rs/net-bytes/badge.svg)](https://docs.rs/net-bytes)
[![许可证](https://img.shields.io/crates/l/net-bytes)](LICENSE-MIT)

一个用于处理文件大小、下载速度和下载加速度的 Rust 库，支持 SI (base-1000) 和 IEC (base-1024) 两种标准。

## 功能


- **文件大小格式化**：自动选择合适的单位格式化文件大小（B、KB/KiB、MB/MiB 等）
- **下载速度计算**：计算和格式化下载速度
- **下载加速度**：测量和格式化下载加速度，支持 ETA 预测
- **双标准支持**：同时支持 SI (base-1000) 和 IEC (base-1024) 标准
- **精确的十进制处理**：使用 `rust_decimal` 进行精确计算
- **零成本抽象**：高效实现，零运行时开销

## 安装


在 `Cargo.toml` 中添加：

```toml
[dependencies]
net-bytes = "0.2.0"
```

## 使用示例


### 文件大小


```rust
use net_bytes::{FileSize, NonZeroFileSize};
use std::num::NonZeroU64;

// 创建 1.5 MB 的文件大小（SI 标准）
let size = FileSize::new(1_500_000);
let formatted = size.to_si_string();
println!("大小: {}", formatted); // 输出: 1.50 MB

// 使用 IEC 标准 (base-1024)
let formatted_iec = size.to_iec_string();
println!("大小 (IEC): {}", formatted_iec); // 输出: 1.43 MiB

// 非零文件大小
let non_zero = NonZeroFileSize::new(NonZeroU64::new(1_500_000).unwrap());
println!("非零大小: {}", non_zero.to_si_string());
```

### 下载速度


```rust
use net_bytes::DownloadSpeed;
use std::time::Duration;

// 从字节数和时间创建下载速度
let speed = DownloadSpeed::new(10_000_000, Duration::from_secs(2));
println!("速度: {}", speed.to_si_string()); // 输出: 5.00 MB/s

// 或者从原始字节/秒创建
let speed = DownloadSpeed::from_raw(5_000_000);
println!("速度: {}", speed.to_iec_string()); // 输出: 4.77 MiB/s
```

### 下载加速度


```rust
use net_bytes::DownloadAcceleration;
use std::time::Duration;

// 从速度变化和时间创建下载加速度
let accel = DownloadAcceleration::new(
    1_000_000,              // 初速度 1 MB/s
    5_000_000,              // 末速度 5 MB/s
    Duration::from_secs(4), // 4 秒内
);
println!("加速度: {}", accel.to_si_string()); // 输出: 1.00 MB/s²

// 预测带加速的 ETA
let current_speed = 2_000_000.0; // 2 MB/s
let remaining_bytes = 10_000_000; // 10 MB
if let Some(eta) = accel.predict_eta(current_speed.into(), remaining_bytes) {
    println!("预计剩余时间: {:.1} 秒", eta);
}
```

## API 参考


### FileSize


- `new(bytes: u64) -> Self` - 创建新的文件大小
- `as_u64() -> u64` - 获取字节数 (u64)
- `to_si_string() -> String` - 使用 SI 单位格式化 (KB, MB, GB 等)
- `to_iec_string() -> String` - 使用 IEC 单位格式化 (KiB, MiB, GiB 等)
- `get_si_parts() -> (String, &'static str)` - 获取 SI 标准下的 (值, 单位) 对
- `get_iec_parts() -> (String, &'static str)` - 获取 IEC 标准下的 (值, 单位) 对
- `to_nonzero() -> Option<NonZeroFileSize>` - 如果非零则转换为 NonZeroFileSize

### NonZeroFileSize


- `new(bytes: NonZeroU64) -> Self` - 创建新的非零文件大小
- `as_u64() -> u64` - 获取字节数 (u64)
- `get_nonzero() -> NonZeroU64` - 获取 NonZeroU64 类型的字节数
- `to_si_string() -> String` - 使用 SI 单位格式化
- `to_iec_string() -> String` - 使用 IEC 单位格式化
- `get_si_parts() -> (String, &'static str)` - 获取 SI 标准下的 (值, 单位) 对
- `get_iec_parts() -> (String, &'static str)` - 获取 IEC 标准下的 (值, 单位) 对

### DownloadSpeed


- `new(bytes: u64, duration: Duration) -> Self` - 从字节数和时间创建
- `from_raw(bytes_per_second: u64) -> Self` - 从字节/秒创建
- `as_decimal() -> Decimal` - 获取 Decimal 类型的速度值
- `as_u64() -> u64` - 获取 u64 类型的速度值（向下取整）
- `to_si_string() -> String` - 使用 SI 单位格式化 (KB/s, MB/s 等)
- `to_iec_string() -> String` - 使用 IEC 单位格式化 (KiB/s, MiB/s 等)
- `get_si_parts() -> (String, &'static str)` - 获取 SI 标准下的 (值, 单位) 对
- `get_iec_parts() -> (String, &'static str)` - 获取 IEC 标准下的 (值, 单位) 对

### DownloadAcceleration


- `new(initial_speed: u64, final_speed: u64, duration: Duration) -> Self` - 从速度变化和时间创建
- `from_raw(bytes_per_second_sq: i64) -> Self` - 从字节/秒²创建
- `as_decimal() -> Decimal` - 获取 Decimal 类型的加速度值
- `as_i64() -> i64` - 获取 i64 类型的加速度值（向下取整）
- `predict_eta(current_speed: Decimal, remaining_bytes: u64) -> Option<Decimal>` - 考虑加速度预测 ETA
- `to_si_string() -> String` - 使用 SI 单位格式化 (KB/s², MB/s² 等)
- `to_iec_string() -> String` - 使用 IEC 单位格式化 (KiB/s², MiB/s² 等)
- `get_si_parts() -> (String, &'static str)` - 获取 SI 标准下的 (值, 单位) 对
- `get_iec_parts() -> (String, &'static str)` - 获取 IEC 标准下的 (值, 单位) 对

## 许可证


根据您的选择，使用以下任一许可证：

- [MIT 许可证](LICENSE-MIT)
- [Apache 许可证 2.0 版](http://www.apache.org/licenses/LICENSE-2.0)