robin/bitbuffer
1
0
Fork 0
mirror of https://codeberg.org/icewind/bitbuffer.git synced 2026-06-03 16:44:06 +02:00
Code Issues Releases Wiki Activity

doc improvements

Browse source
This commit is contained in:
Robin Appelman 2019-02-27 17:21:03 +01:00
commit 3f77c851b3
5 changed files with 170 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

27
src/buffer.rs
View file

@ -109,7 +109,7 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the buffer
/// ///
/// # Examples /// # Examples
/// ///
@ -124,6 +124,8 @@ where
/// let result = buffer.read_bool(5).unwrap(); /// let result = buffer.read_bool(5).unwrap();
/// assert_eq!(result, true); /// assert_eq!(result, true);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_bool(&self, position: usize) -> Result<bool> { pub fn read_bool(&self, position: usize) -> Result<bool> {
let byte_index = position / 8; let byte_index = position / 8;
let bit_offset = position & 7; let bit_offset = position & 7;
@ -144,8 +146,8 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the buffer
/// - [`ReadError::TooManyBits`](enum.ReadError.html#variant.TooManyBits): to many bits requested for the chosen integer type /// - [`ReadError::TooManyBits`]: to many bits requested for the chosen integer type
/// ///
/// # Examples /// # Examples
/// ///
@ -160,6 +162,9 @@ where
/// let result = buffer.read_int::<u16>(10, 9).unwrap(); /// let result = buffer.read_int::<u16>(10, 9).unwrap();
/// assert_eq!(result, 0b100_0110_10); /// assert_eq!(result, 0b100_0110_10);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
/// [`ReadError::TooManyBits`]: enum.ReadError.html#variant.TooManyBits
pub fn read_int<T>(&self, position: usize, count: usize) -> Result<T> pub fn read_int<T>(&self, position: usize, count: usize) -> Result<T>
where where
T: PrimInt + BitOrAssign + IsSigned, T: PrimInt + BitOrAssign + IsSigned,
@ -223,7 +228,7 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the buffer
/// ///
/// # Examples /// # Examples
/// ///
@ -241,6 +246,8 @@ where
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]); /// ]);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_bytes(&self, position: usize, byte_count: usize) -> Result<Vec<u8>> { pub fn read_bytes(&self, position: usize, byte_count: usize) -> Result<Vec<u8>> {
let mut data = vec![]; let mut data = vec![];
data.reserve_exact(byte_count); data.reserve_exact(byte_count);
@ -264,8 +271,8 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the buffer
/// - [`ReadError::Utf8Error`](enum.ReadError.html#variant.Utf8Error): the read bytes are not valid utf8 /// - [`ReadError::Utf8Error`]: the read bytes are not valid utf8
/// ///
/// # Examples /// # Examples
/// ///
@ -286,6 +293,9 @@ where
/// // null terminated /// // null terminated
/// assert_eq!(buffer.read_string(0, None).unwrap(), "Hello world".to_owned()); /// assert_eq!(buffer.read_string(0, None).unwrap(), "Hello world".to_owned());
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
/// [`ReadError::Utf8Error`]: enum.ReadError.html#variant.Utf8Error
pub fn read_string(&self, position: usize, byte_len: Option<usize>) -> Result<String> { pub fn read_string(&self, position: usize, byte_len: Option<usize>) -> Result<String> {
let bytes = match byte_len { let bytes = match byte_len {
Some(len) => self.read_bytes(position, len)?, Some(len) => self.read_bytes(position, len)?,
@ -311,8 +321,7 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the buffer
/// - [`ReadError::TooManyBits`](enum.ReadError.html#variant.TooManyBits): to many bits requested for the chosen integer type
/// ///
/// # Examples /// # Examples
/// ///
@ -326,6 +335,8 @@ where
/// # let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let result = buffer.read_float::<f32>(10).unwrap(); /// let result = buffer.read_float::<f32>(10).unwrap();
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_float<T>(&self, position: usize) -> Result<T> pub fn read_float<T>(&self, position: usize) -> Result<T>
where where
T: Float, T: Float,

4
src/endianness.rs
View file

@ -6,10 +6,10 @@ pub trait Endianness {
fn is_be() -> bool; fn is_be() -> bool;
} }
/// Trait for specifying that the bit buffer is big endian /// Marks the buffer or stream as big endian
pub struct BigEndian; pub struct BigEndian;
/// Trait for specifying that the bit buffer is little endian /// Marks the buffer or stream as little endian
pub struct LittleEndian; pub struct LittleEndian;
macro_rules! impl_endianness { macro_rules! impl_endianness {

23
src/lib.rs
View file

@ -1,5 +1,17 @@
//! Tools for reading integers of arbitrary bit length and non byte-aligned integers and other data types //! Tools for reading integers of arbitrary bit length and non byte-aligned integers and other data types
//! //!
//! The main way of handling with the binary data is to first create a [`BitBuffer`]
//! ,wrap it into a [`BitStream`] and then read from the stream.
//!
//! If performance is critical, working directly on the BitBuffer can be faster.
//!
//! Once you have a BitStream, there are 2 different approaches of reading data
//!
//! - read primitives, Strings and byte arrays, using [`read_bool`], [`read_int`], [`read_float`], [`read_byes`] and [`read_string`]
//! - read any type implementing the [`Read`] or [`ReadSized`] traits using [`read`] and [`read_sized`]
//! - [`Read`] is for types that can be read without requiring any size info (e.g. null-terminal strings, floats, whole integers, etc)
//! - [`ReadSized`] is for types that require external sizing information to be read (fixed length strings, arbitrary length integers
//!
//! //!
//! //!
//! # Examples //! # Examples
@ -13,6 +25,17 @@
//! ]; //! ];
//! let buffer = BitBuffer::new(bytes, LittleEndian); //! let buffer = BitBuffer::new(bytes, LittleEndian);
//! let stream = BitStream::new(buffer); //! let stream = BitStream::new(buffer);
//! ```
//!
//! [`BitBuffer`]: struct.BitBuffer.html
//! [`BitStream`]: struct.BitStream.html
//! [`read_bool`]: struct.BitStream.html#method.read_bool
//! [`read_int`]: struct.BitStream.html#method.read_int
//! [`read_float`]: struct.BitStream.html#method.read_float
//! [`read_byes`]: struct.BitStream.html#method.read_bytes
//! [`read_string`]: struct.BitStream.html#method.read_string
//! [`Read`]: trait.Read.html
//! [`ReadSized`]: trait.ReadSized.html
#![warn(missing_docs)] #![warn(missing_docs)]
//#![feature(test)] //#![feature(test)]

3
src/read.rs
View file

@ -91,7 +91,7 @@ impl<E: Endianness> ReadSized<E> for String {
} }
} }
/// Read a boolean, if true, read the value, else return None /// Read a boolean, if true, read `T`, else return `None`
impl<E: Endianness, T: Read<E>> Read<E> for Option<T> { impl<E: Endianness, T: Read<E>> Read<E> for Option<T> {
fn read(stream: &mut BitStream<E>) -> Result<Self> { fn read(stream: &mut BitStream<E>) -> Result<Self> {
if stream.read()? { if stream.read()? {
@ -102,6 +102,7 @@ impl<E: Endianness, T: Read<E>> Read<E> for Option<T> {
} }
} }
/// Read `T` `size` times and return as `Vec<T>`
impl<E: Endianness, T: Read<E>> ReadSized<E> for Vec<T> { impl<E: Endianness, T: Read<E>> ReadSized<E> for Vec<T> {
fn read(stream: &mut BitStream<E>, size: usize) -> Result<Self> { fn read(stream: &mut BitStream<E>, size: usize) -> Result<Self> {
let mut vec = Vec::with_capacity(size); let mut vec = Vec::with_capacity(size);

231
src/stream.rs
View file

@ -9,7 +9,7 @@ use crate::is_signed::IsSigned;
use crate::BitBuffer; use crate::BitBuffer;
use crate::{Read, ReadError, ReadSized, Result}; use crate::{Read, ReadError, ReadSized, Result};
/// Stream that provides an easy way to iterate trough a BitBuffer /// Stream that provides an easy way to iterate trough a [`BitBuffer`]
/// ///
/// # Examples /// # Examples
/// ///
@ -23,6 +23,8 @@ use crate::{Read, ReadError, ReadSized, Result};
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// let mut stream = BitStream::new(buffer);
/// ``` /// ```
///
/// [`BitBuffer`]: struct.BitBuffer.html
pub struct BitStream<E> pub struct BitStream<E>
where where
E: Endianness, E: Endianness,
@ -37,12 +39,7 @@ impl<E> BitStream<E>
where where
E: Endianness, E: Endianness,
{ {
/// Create a new stream for a buffer /// Create a new stream for a [`BitBuffer`]
///
/// # Panics
///
/// - If the start_pos is higher than the bit length of the buffer
///
/// ///
/// # Examples /// # Examples
/// ///
@ -56,6 +53,8 @@ where
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// let mut stream = BitStream::new(buffer);
/// ``` /// ```
///
/// [`BitBuffer`]: struct.BitBuffer.html
pub fn new(buffer: BitBuffer<E>) -> Self { pub fn new(buffer: BitBuffer<E>) -> Self {
BitStream { BitStream {
start_pos: 0, start_pos: 0,
@ -80,23 +79,25 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.read_bool().unwrap(), true); /// assert_eq!(stream.read_bool().unwrap(), true);
/// assert_eq!(stream.read_bool().unwrap(), false); /// assert_eq!(stream.read_bool().unwrap(), false);
/// assert_eq!(stream.pos(), 2); /// assert_eq!(stream.pos(), 2);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_bool(&mut self) -> Result<bool> { pub fn read_bool(&mut self) -> Result<bool> {
self.verify_bits_left(1)?; self.verify_bits_left(1)?;
let result = self.buffer.read_bool(self.pos); let result = self.buffer.read_bool(self.pos);
@ -110,24 +111,27 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// - [`ReadError::TooManyBits`](enum.ReadError.html#variant.TooManyBits): to many bits requested for the chosen integer type /// - [`ReadError::TooManyBits`]: to many bits requested for the chosen integer type
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.read_int::<u16>(3).unwrap(), 0b101); /// assert_eq!(stream.read_int::<u16>(3).unwrap(), 0b101);
/// assert_eq!(stream.read_int::<u16>(3).unwrap(), 0b110); /// assert_eq!(stream.read_int::<u16>(3).unwrap(), 0b110);
/// assert_eq!(stream.pos(), 6); /// assert_eq!(stream.pos(), 6);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
/// [`ReadError::TooManyBits`]: enum.ReadError.html#variant.TooManyBits
pub fn read_int<T>(&mut self, count: usize) -> Result<T> pub fn read_int<T>(&mut self, count: usize) -> Result<T>
where where
T: PrimInt + BitOrAssign + IsSigned, T: PrimInt + BitOrAssign + IsSigned,
@ -144,22 +148,24 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// let result = stream.read_float::<f32>().unwrap(); /// let result = stream.read_float::<f32>().unwrap();
/// assert_eq!(stream.pos(), 32); /// assert_eq!(stream.pos(), 32);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_float<T>(&mut self) -> Result<T> pub fn read_float<T>(&mut self) -> Result<T>
where where
T: Float, T: Float,
@ -177,22 +183,24 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.read_bytes(3).unwrap(), &[0b1011_0101, 0b0110_1010, 0b1010_1100]); /// assert_eq!(stream.read_bytes(3).unwrap(), &[0b1011_0101, 0b0110_1010, 0b1010_1100]);
/// assert_eq!(stream.pos(), 24); /// assert_eq!(stream.pos(), 24);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_bytes(&mut self, byte_count: usize) -> Result<Vec<u8>> { pub fn read_bytes(&mut self, byte_count: usize) -> Result<Vec<u8>> {
let count = byte_count * 8; let count = byte_count * 8;
self.verify_bits_left(count)?; self.verify_bits_left(count)?;
@ -209,22 +217,22 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// - [`ReadError::Utf8Error`](enum.ReadError.html#variant.Utf8Error): the read bytes are not valid utf8 /// - [`ReadError::Utf8Error`]: the read bytes are not valid utf8
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0x48, 0x65, 0x6c, 0x6c, /// # 0x48, 0x65, 0x6c, 0x6c,
/// 0x6f, 0x20, 0x77, 0x6f, /// # 0x6f, 0x20, 0x77, 0x6f,
/// 0x72, 0x6c, 0x64, 0, /// # 0x72, 0x6c, 0x64, 0,
/// 0, 0, 0, 0 /// # 0, 0, 0, 0
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// // Fixed length string /// // Fixed length string
/// stream.set_pos(0); /// stream.set_pos(0);
/// assert_eq!(stream.read_string(Some(11)).unwrap(), "Hello world".to_owned()); /// assert_eq!(stream.read_string(Some(11)).unwrap(), "Hello world".to_owned());
@ -238,6 +246,9 @@ where
/// assert_eq!(stream.read_string(None).unwrap(), "Hello world".to_owned()); /// assert_eq!(stream.read_string(None).unwrap(), "Hello world".to_owned());
/// assert_eq!(12 * 8, stream.pos()); // 1 more for the terminating null byte /// assert_eq!(12 * 8, stream.pos()); // 1 more for the terminating null byte
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
/// [`ReadError::Utf8Error`]: enum.ReadError.html#variant.Utf8Error
pub fn read_string(&mut self, byte_len: Option<usize>) -> Result<String> { pub fn read_string(&mut self, byte_len: Option<usize>) -> Result<String> {
let result = self.buffer.read_string(self.pos, byte_len)?; let result = self.buffer.read_string(self.pos, byte_len)?;
let read = match byte_len { let read = match byte_len {
@ -252,19 +263,19 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// let mut bits = stream.read_bits(3).unwrap(); /// let mut bits = stream.read_bits(3).unwrap();
/// assert_eq!(stream.pos(), 3); /// assert_eq!(stream.pos(), 3);
/// assert_eq!(bits.pos(), 0); /// assert_eq!(bits.pos(), 0);
@ -272,6 +283,8 @@ where
/// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110); /// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110);
/// assert_eq!(bits.read_int::<u8>(3).unwrap(), 0b101); /// assert_eq!(bits.read_int::<u8>(3).unwrap(), 0b101);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn read_bits(&mut self, count: usize) -> Result<Self> { pub fn read_bits(&mut self, count: usize) -> Result<Self> {
self.verify_bits_left(count)?; self.verify_bits_left(count)?;
let result = BitStream { let result = BitStream {
@ -288,23 +301,25 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::NotEnoughData`](enum.ReadError.html#variant.NotEnoughData): not enough bits available in the buffer to skip /// - [`ReadError::NotEnoughData`]: not enough bits available in the stream to skip
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// stream.skip(3).unwrap(); /// stream.skip(3).unwrap();
/// assert_eq!(stream.pos(), 3); /// assert_eq!(stream.pos(), 3);
/// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110); /// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110);
/// ``` /// ```
///
/// [`ReadError::NotEnoughData`]: enum.ReadError.html#variant.NotEnoughData
pub fn skip(&mut self, count: usize) -> Result<()> { pub fn skip(&mut self, count: usize) -> Result<()> {
self.verify_bits_left(count)?; self.verify_bits_left(count)?;
self.pos += count; self.pos += count;
@ -315,23 +330,25 @@ where
/// ///
/// # Errors /// # Errors
/// ///
/// - [`ReadError::IndexOutOfBounds`](enum.ReadError.html#variant.IndexOutOfBounds): new position is outside the bounds of the stream /// - [`ReadError::IndexOutOfBounds`]: new position is outside the bounds of the stream
/// ///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// stream.set_pos(3).unwrap(); /// stream.set_pos(3).unwrap();
/// assert_eq!(stream.pos(), 3); /// assert_eq!(stream.pos(), 3);
/// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110); /// assert_eq!(stream.read_int::<u8>(3).unwrap(), 0b110);
/// ``` /// ```
///
/// [`ReadError::IndexOutOfBounds`]: enum.ReadError.html#variant.IndexOutOfBounds
pub fn set_pos(&mut self, pos: usize) -> Result<()> { pub fn set_pos(&mut self, pos: usize) -> Result<()> {
if pos > self.bit_len { if pos > self.bit_len {
return Err(ReadError::IndexOutOfBounds { return Err(ReadError::IndexOutOfBounds {
@ -348,14 +365,14 @@ where
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.bit_len(), 64); /// assert_eq!(stream.bit_len(), 64);
/// ``` /// ```
pub fn bit_len(&self) -> usize { pub fn bit_len(&self) -> usize {
@ -367,14 +384,14 @@ where
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.pos(), 0); /// assert_eq!(stream.pos(), 0);
/// stream.skip(5).unwrap(); /// stream.skip(5).unwrap();
/// assert_eq!(stream.pos(), 5); /// assert_eq!(stream.pos(), 5);
@ -388,14 +405,14 @@ where
/// # Examples /// # Examples
/// ///
/// ``` /// ```
/// use bitstream_reader::{BitBuffer, BitStream, LittleEndian}; /// # use bitstream_reader::{BitBuffer, BitStream, LittleEndian};
/// /// #
/// let bytes = vec![ /// # let bytes = vec![
/// 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001, /// # 0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
/// 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111 /// # 0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
/// ]; /// # ];
/// let buffer = BitBuffer::new(bytes, LittleEndian); /// # let buffer = BitBuffer::new(bytes, LittleEndian);
/// let mut stream = BitStream::new(buffer); /// # let mut stream = BitStream::new(buffer);
/// assert_eq!(stream.bits_left(), 64); /// assert_eq!(stream.bits_left(), 64);
/// stream.skip(5).unwrap(); /// stream.skip(5).unwrap();
/// assert_eq!(stream.bits_left(), 59); /// assert_eq!(stream.bits_left(), 59);