Struct binary_util::io::ByteReader

pub struct ByteReader { /* private fields */ }

ByteReader is a panic-free way to read bytes from the byte::Buf trait.

Example

use binary_util::io::ByteReader;

fn main() {
   let mut buf = ByteReader::from(&[0, 253, 255, 255, 255, 15][..]);
   assert_eq!(buf.read_u8().unwrap(), 0);
   assert_eq!(buf.read_var_i32().unwrap(), -2147483647);
}

Peek Ahead

ByteReader also provides a utility peek_ahead function that allows you to “peek ahead” at the next byte in the stream without advancing the stream.

Do not confuse this with any sort of “peek” function. This function does not increment the read position of the stream, but rather copies the byte at the specified position.

use binary_util::io::ByteReader;

fn main() {
   let mut buf = ByteReader::from(&[253, 255, 14, 255, 255, 15][..]);
   if buf.peek_ahead(3).unwrap() != 255 {
       // buffer is corrupted!
   } else {
       // read the varint
       let num = buf.read_var_i32().unwrap();
   }
}

Reading a struct without BinaryDecoder

This is useful if you are trying to read a struct or optional type and validate the type before reading the rest of the struct.

use binary_util::io::ByteReader;

struct PingPacket {
   pub id: u8,
   pub time: u64,
   pub ack_id: Option<i32>
}

fn main() {
    let mut buf = ByteReader::from(&[0, 253, 255, 255, 255, 255, 255, 255, 255, 0][..]);

    // Read the id
    let id = buf.read_u8().unwrap();

    if id == 0 {
        // Read the time
       let time = buf.read_u64().unwrap();
       // read ack
       if buf.read_bool().unwrap() {
           let ack_id = buf.read_var_i32().unwrap();
           let packet = PingPacket { id, time, ack_id: Some(ack_id) };
       } else {
           let packet = PingPacket { id, time, ack_id: None };
       }
   }
}

Implementations

impl ByteReader

pub fn peek_ahead(&mut self, pos: usize) -> Result<u8, Error>

ByteReader also provides a utility peek_ahead function that allows you to “peek ahead” at the next byte in the stream without advancing the stream.

Do not confuse this with any sort of “peek” function. This function does not increment the read position of the stream, but rather copies the byte at the specified position.

use binary_util::io::ByteReader;

fn main() {
   let mut buf = ByteReader::from(&[253, 255, 14, 255, 255, 15][..]);
   if buf.peek_ahead(3).unwrap() != 255 {
       // buffer is corrupted, varints can never have a leading byte less than 255 if
       // Their are bytes remaining!
   } else {
       // read the varint
       let num = buf.read_var_i32().unwrap();
   }
}

pub fn read_u8(&mut self) -> Result<u8, Error>

pub fn read_i8(&mut self) -> Result<i8, Error>

pub fn read_u16(&mut self) -> Result<u16, Error>

pub fn read_u16_le(&mut self) -> Result<u16, Error>

pub fn read_i16(&mut self) -> Result<i16, Error>

pub fn read_i16_le(&mut self) -> Result<i16, Error>

pub fn read_u24(&mut self) -> Result<u32, Error>

Reads a 3-byte unsigned integer from the stream.

pub fn read_u24_le(&mut self) -> Result<u32, Error>

Reads a 3-byte unsigned integer from the stream in little endian. This is the same as read_u24 but in little endian.

pub fn read_i24(&mut self) -> Result<i32, Error>

pub fn read_i24_le(&mut self) -> Result<i32, Error>

pub fn read_u32(&mut self) -> Result<u32, Error>

pub fn read_u32_le(&mut self) -> Result<u32, Error>

pub fn read_f32(&mut self) -> Result<f32, Error>

pub fn read_f32_le(&mut self) -> Result<f32, Error>

pub fn read_var_u32(&mut self) -> Result<u32, Error>

Reads a var-int 32-bit unsigned integer from the stream. This is a variable length integer that can be 1, 2, 3, or 4 bytes long.

This function is recoverable, meaning that if the stream ends before the var-int is fully read, it will return an error, and will not consume the bytes that were read.

pub fn read_i32(&mut self) -> Result<i32, Error>

pub fn read_i32_le(&mut self) -> Result<i32, Error>

pub fn read_var_i32(&mut self) -> Result<i32, Error>

Reads a var-int 32-bit signed integer from the stream. This method is the same as read_var_u32 but it will return a signed integer.

pub fn read_u64(&mut self) -> Result<u64, Error>

pub fn read_u64_le(&mut self) -> Result<u64, Error>

pub fn read_i64(&mut self) -> Result<i64, Error>

pub fn read_i64_le(&mut self) -> Result<i64, Error>

pub fn read_f64(&mut self) -> Result<f64, Error>

pub fn read_f64_le(&mut self) -> Result<f64, Error>

pub fn read_var_u64(&mut self) -> Result<u64, Error>

Reads a var-int 64-bit unsigned integer from the stream. This is a variable length integer that can be 1, 2, 3, 4, 5, 6, 7, or 8 bytes long.

pub fn read_var_i64(&mut self) -> Result<i64, Error>

Reads a var-int 64-bit signed integer from the stream. This method is the same as read_var_u64 but it will return a signed integer.

For more information on how this works, see read_var_i32.

pub fn read_u128(&mut self) -> Result<u128, Error>

pub fn read_u128_le(&mut self) -> Result<u128, Error>

pub fn read_i128(&mut self) -> Result<i128, Error>

pub fn read_i128_le(&mut self) -> Result<i128, Error>

pub fn read_uint(&mut self, size: usize) -> Result<u64, Error>

Reads an unsigned integer from the stream with a varying size indicated by the size parameter.

pub fn read_uint_le(&mut self, size: usize) -> Result<u64, Error>

Reads an unsigned integer from the stream with a varying size in little endian indicated by the size parameter.

pub fn read_int(&mut self, size: usize) -> Result<i64, Error>

pub fn read_int_le(&mut self, size: usize) -> Result<i64, Error>

pub fn read_char(&mut self) -> Result<char, Error>

pub fn read_bool(&mut self) -> Result<bool, Error>

pub fn read_string(&mut self) -> Result<String, Error>

Reads a string from the stream. This is a reversable operation, meaning if it fails, the stream will be in the same state as before.

pub fn read_option<T: Reader<T>>(&mut self) -> Result<Option<T>, Error>

Reads an Option of T from the stream. T must implement the Reader trait and be sized.

This operation is not recoverable and will corrupt the stream if it fails. If this behavior is desired, you should use peek_ahead when implementing the Reader trait.

Example

use binary_util::io::ByteReader;
use binary_util::interfaces::Reader;

pub struct HelloWorld {
    pub magic: u32
}

impl Reader<HelloWorld> for HelloWorld {
    fn read(reader: &mut ByteReader) -> Result<HelloWorld, std::io::Error> {
        Ok(HelloWorld {
            magic: reader.read_u32()?
        })
    }
}

fn main() {
    // Nothing is here!
    let mut reader = ByteReader::from(&[0x00][..]);
    let hello_world = reader.read_option::<HelloWorld>().unwrap();
    assert_eq!(hello_world.is_some(), false);
}

pub fn read_sized_slice(&mut self) -> Result<Bytes, Error>

Reads a varu32 sized slice from the stream. For reading a slice of raw bytes, use read instead.

pub fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error>

Reads a slice from the stream into the slice passed by the caller. For reading a prefixed sized slice, use read_sized_slice instead.

pub fn read_struct<T: Reader<T>>(&mut self) -> Result<T, Error>

👎Deprecated: Use read_type instead

Reads T from the stream. T must implement the Reader trait and be sized.

Deprecrated

This function is deprecated and will be removed in v0.3.4.

pub fn read_type<T: Reader<T>>(&mut self) -> Result<T, Error>

Reads T from the stream. T must implement the Reader trait and be sized.

pub fn as_slice(&self) -> &[u8]

Returns the remaining bytes in the stream.

Trait Implementations

impl Clone for ByteReader

fn clone(&self) -> ByteReader

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ByteReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&[u8]> for ByteReader

fn from(buf: &[u8]) -> Self

Converts to this type from the input type.

impl From<ByteReader> for ByteWriter

fn from(reader: ByteReader) -> Self

Converts to this type from the input type.

impl From<ByteWriter> for ByteReader

fn from(writer: ByteWriter) -> Self

Converts to this type from the input type.

impl From<Bytes> for ByteReader

fn from(buf: Bytes) -> Self

Converts to this type from the input type.

impl From<Vec<u8, Global>> for ByteReader

fn from(buf: Vec<u8>) -> Self

Converts to this type from the input type.

impl Into<Bytes> for ByteReader

fn into(self) -> Bytes

Converts this type into the (usually inferred) input type.

impl Into<Vec<u8, Global>> for ByteReader

fn into(self) -> Vec<u8>

Converts this type into the (usually inferred) input type.

impl Into<VecDeque<u8, Global>> for ByteReader

fn into(self) -> VecDeque<u8>

Converts this type into the (usually inferred) input type.