net-bytes 0.3.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) 两种标准。

## 功能


- **零依赖**：纯 Rust 实现，无外部依赖
- **文件大小格式化**：自动选择合适的单位格式化文件大小（B、KB/KiB、MB/MiB 等）
- **下载速度计算**：计算和格式化下载速度，支持纳秒级精度
- **下载加速度**：测量和格式化下载加速度，支持 ETA 预测
- **双标准支持**：同时支持 SI (base-1000) 和 IEC (base-1024) 标准
- **定点数精度**：使用整数运算保持 6 位小数精度，避免浮点误差
- **高性能**：使用 `u128`/`i128` 进行防溢出计算

## 安装


在 `Cargo.toml` 中添加：

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

## 使用示例


### 文件大小


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

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

// 使用 IEC 标准 (base-1024)
println!("大小 (IEC): {}", size.to_iec_string()); // 输出: 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

// 获取不同格式的值
println!("字节/秒: {}", speed.as_u64());  // 整数值
println!("字节/秒: {}", speed.as_f64());  // 浮点值
```

### 下载加速度


```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; // 2 MB/s
let remaining_bytes = 10_000_000; // 10 MB
if let Some(eta) = accel.predict_eta(current_speed, remaining_bytes) {
    println!("预计剩余时间: {:.1} 秒", eta);
}
```

## API 参考


### FileSize


| 方法 | 描述 |
|------|------|
| `new(bytes: u64) -> Self` | 创建新的文件大小 |
| `as_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` | 获取字节数 |
| `get_nonzero() -> NonZeroU64` | 获取 NonZeroU64 类型的字节数 |
| `to_si_string() -> String` | 使用 SI 单位格式化 |
| `to_iec_string() -> String` | 使用 IEC 单位格式化 |

### DownloadSpeed


| 方法 | 描述 |
|------|------|
| `new(bytes: u64, duration: Duration) -> Self` | 从字节数和时间创建 |
| `from_raw(bytes_per_second: u64) -> Self` | 从字节/秒创建 |
| `as_u64() -> u64` | 获取速度值（向下取整） |
| `as_f64() -> f64` | 获取浮点类型的速度值 |
| `as_scaled() -> u128` | 获取内部缩放值 |
| `to_si_string() -> String` | 使用 SI 单位格式化 (KB/s, MB/s 等) |
| `to_iec_string() -> String` | 使用 IEC 单位格式化 (KiB/s, MiB/s 等) |

### DownloadAcceleration


| 方法 | 描述 |
|------|------|
| `new(initial_speed: u64, final_speed: u64, duration: Duration) -> Self` | 从速度变化和时间创建 |
| `from_raw(bytes_per_second_sq: i64) -> Self` | 从字节/秒²创建 |
| `as_i64() -> i64` | 获取加速度值（向下取整） |
| `as_f64() -> f64` | 获取浮点类型的加速度值 |
| `as_scaled() -> i128` | 获取内部缩放值 |
| `predict_eta(current_speed: u64, remaining_bytes: u64) -> Option<f64>` | 预测剩余时间（秒） |
| `to_si_string() -> String` | 使用 SI 单位格式化 (KB/s², MB/s² 等) |
| `to_iec_string() -> String` | 使用 IEC 单位格式化 (KiB/s², MiB/s² 等) |

## 许可证


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

- [MIT 许可证](LICENSE-MIT)
- [Apache 许可证 2.0 版](LICENSE-APACHE)