Rust二进制流处理库binary-stream的使用指南

binary-stream是一个高效的Rust库，专门用于读写和解析二进制数据流。它提供了简单直观的API来处理各种二进制数据格式，特别适合网络协议解析、文件格式处理等场景。

主要特性

• 高效的二进制数据读写操作
• 支持大端序和小端序
• 类型安全的API设计
• 零拷贝操作优化
• 支持异步I/O操作

安装

在Cargo.toml中添加依赖：

[dependencies]
binary-stream = "0.3"

基本使用方法

创建写入流

use binary_stream::{BinaryWriter, Endian};

let mut writer = BinaryWriter::new(Endian::Big);
writer.write_u8(0x42);  // 写入1字节无符号整数
writer.write_i16(-100);  // 写入2字节有符号整数
writer.write_f32(3.14);  // 写入4字节浮点数
writer.write_string("Hello");  // 写入字符串

let data = writer.into_bytes();  // 获取最终字节数据

创建读取流

use binary_stream::{BinaryReader, Endian};

let data = vec![0x42, 0x00, 0x9C, 0x40, 0x48, 0x65, 0x6C, 0x6C, 0x6F];
let mut reader = BinaryReader::from_bytes(&data, Endian::Big);

let num1 = reader.read_u8().unwrap();    // 读取1字节无符号整数
let num2 = reader.read_i16().unwrap();   // 读取2字节有符号整数
let float = reader.read_f32().unwrap(); // 读取4字节浮点数
let string = reader.read_string().unwrap(); // 读取字符串

println!("u8: {}, i16: {}, f32: {}, string: {}", num1, num2, float, string);

高级用法

处理自定义结构

use binary_stream::{BinaryWriter, BinaryReader, Endian, Serializable};

#[derive(Debug)]
struct Point {
    x: f32,
    y: f32,
}

impl Serializable for Point {
    fn write(&self, writer: &mut BinaryWriter) {
        writer.write_f32(self.x);
        writer.write_f32(self.y);
    }

    fn read(reader: &mut BinaryReader) -> Self {
        Point {
            x: reader.read_f32().unwrap(),
            y: reader.read_f32().unwrap(),
        }
    }
}

// 写入Point结构
let point = Point { x: 1.0, y: 2.0 };
let mut writer = BinaryWriter::new(Endian::Little);
writer.write_serializable(&point);
let data = writer.into_bytes();

// 读取Point结构
let mut reader = BinaryReader::from_bytes(&data, Endian::Little);
let read_point: Point = reader.read_serializable();
println!("Read point: {:?}", read_point);

异步处理

use binary_stream::{AsyncBinaryWriter, AsyncBinaryReader, Endian};
use tokio::io::{AsyncWriteExt, AsyncReadExt};

async fn async_example() {
    let mut writer = AsyncBinaryWriter::new(Endian::Big);
    writer.write_u16(0x1234).await.unwrap();
    writer.write_string("Async").await.unwrap();
    
    let mut buffer = Vec::new();
    writer.into_inner().read_to_end(&mut buffer).await.unwrap();
    
    let mut reader = AsyncBinaryReader::from_bytes(&buffer, Endian::Big);
    let num = reader.read_u16().await.unwrap();
    let text = reader.read_string().await.unwrap();
    
    println!("Async read: {}, {}", num, text);
}

性能优化技巧

1. 对于已知长度的数据，预分配缓冲区：

let mut writer = BinaryWriter::with_capacity(1024, Endian::Little);

1. 批量写入数据：

writer.write_bytes(&[0x01, 0x02, 0x03]);

1. 使用零拷贝操作：

let slice = reader.read_slice(4).unwrap();  // 不复制数据，直接引用原始缓冲区

完整示例demo

下面是一个结合了基本读写和自定义结构处理的完整示例：

use binary_stream::{BinaryWriter, BinaryReader, Endian, Serializable};

// 自定义数据结构
#[derive(Debug, PartialEq)]
struct User {
    id: u32,
    name: String,
    active: bool,
    balance: f64,
}

impl Serializable for User {
    fn write(&self, writer: &mut BinaryWriter) {
        writer.write_u32(self.id);
        writer.write_string(&self.name);
        writer.write_bool(self.active);
        writer.write_f64(self.balance);
    }

    fn read(reader: &mut BinaryReader) -> Self {
        User {
            id: reader.read_u32().unwrap(),
            name: reader.read_string().unwrap(),
            active: reader.read_bool().unwrap(),
            balance: reader.read_f64().unwrap(),
        }
    }
}

fn main() {
    // 创建用户数据
    let user = User {
        id: 42,
        name: "Alice".to_string(),
        active: true,
        balance: 123.45,
    };

    // 写入二进制数据
    let mut writer = BinaryWriter::with_capacity(128, Endian::Little);
    writer.write_serializable(&user);
    let data = writer.into_bytes();

    // 读取二进制数据
    let mut reader = BinaryReader::from_bytes(&data, Endian::Little);
    let read_user: User = reader.read_serializable();
    
    // 验证数据
    println!("Original: {:?}", user);
    println!("Read: {:?}", read_user);
    assert_eq!(user, read_user);
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_user_serialization() {
        let user = User {
            id: 1001,
            name: "Bob".to_string(),
            active: false,
            balance: 99.99,
        };
        
        let mut writer = BinaryWriter::new(Endian::Big);
        writer.write_serializable(&user);
        let data = writer.into_bytes();
        
        let mut reader = BinaryReader::from_bytes(&data, Endian::Big);
        let read_user: User = reader.read_serializable();
        
        assert_eq!(user, read_user);
    }
}

这个完整示例展示了如何：

1. 定义自定义数据结构
2. 实现Serializable trait
3. 使用预分配缓冲区写入数据
4. 从二进制流中读取数据
5. 包含单元测试验证功能

binary-stream库通过其简洁的API和高效的实现，使得Rust中的二进制数据处理变得简单而高效。无论是简单的数据类型还是复杂的二进制协议，都能轻松应对。