bitstream-io

一个Rust库，用于从/向可能未以整字节对齐的流中读取/写入二进制值。

此库旨在足够灵活，可以包装实现 Read 或 Write 特性的任何流。它还支持一系列整数数据类型作为那些二进制值的容器。

最低编译器版本

从版本2.4开始，最低编译器版本已更新到Rust 1.79，以支持在 const 块中进行编译时断言，这可以在编译时而不是运行时检查一类错误。

lib.rs:

位流处理功能特性和辅助函数

位流读取器用于从可能不是整字节的流中读取有符号和无符号整数值。位流写入器用于将有符号和无符号整数值写入流，也可能不是整字节对齐。

支持大端和小端流。

包装读取流的要求是它们必须实现 Read 特性，而包装写入流的要求是它们必须实现 Write 特性。

此外，读取流不会从底层读取比必要更多的字节，只根据需要缓冲单个部分字节。写入流也会随着积累的字节写入所有整字节。

读取器和写入器还设计为与任何可能的整数类型一起工作。许多Rust内置的整数类型默认支持。

最低编译器版本

从版本2.4开始，最低编译器版本已更新到Rust 1.79。

问题是，向无法容纳它们的类型读取过多的位，或从过小的类型写入过多的位，始终是错误。

use std::io::{Read, Cursor};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0; 10];
let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
let x: Result<u32, _> = r.read(64);  // reading 64 bits to u32 always fails at runtime
assert!(x.is_err());

但是这些错误只有在程序运行时才会被发现，这对于在编译时已知位数的情况来说并不理想。

但是从Rust 1.79版本开始，我们现在可以拥有读取和写入方法，这些方法接受一个固定数量的位数，并且可以在编译时验证位数是否足够小，以便于读取/写入的类型。

use std::io::{Read, Cursor};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0; 10];
let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
let x: Result<u32, _> = r.read_in::<64, _>();  // doesn't compile at all

由于在编译时捕获潜在的bug比在运行时遇到错误更可取，因此这可能会在长期内带来改进。

从1.0.0之前的版本迁移

现在有BitRead和BitWrite特质用于位流读取和写入（类似于标准库中的Read和Write特质），您也需要导入这些特质。这种方法的优点是，库消费者现在可以创建通用的函数和方法，这些函数和方法可以针对任何类型的位读取器或位写入器，无论其底层字节流来源或字节序。