Trait DataSource

pub trait DataSource {
    // Required methods
    fn available(&self) -> usize;
    fn request(&mut self, count: usize) -> Result<bool>;
    fn skip(&mut self, count: usize) -> Result<usize>;
    fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>;

    // Provided methods
    fn require(&mut self, count: usize) -> Result { ... }
    fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]> { ... }
    fn read_aligned_bytes<'a>(
        &mut self,
        buf: &'a mut [u8],
        alignment: usize,
    ) -> Result<&'a [u8]> { ... }
    fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>
       where Self: Sized { ... }
    fn read_u8(&mut self) -> Result<u8> { ... }
    fn read_i8(&mut self) -> Result<i8> { ... }
    fn read_u16(&mut self) -> Result<u16> { ... }
    fn read_i16(&mut self) -> Result<i16> { ... }
    fn read_u16_le(&mut self) -> Result<u16> { ... }
    fn read_i16_le(&mut self) -> Result<i16> { ... }
    fn read_u32(&mut self) -> Result<u32> { ... }
    fn read_i32(&mut self) -> Result<i32> { ... }
    fn read_u32_le(&mut self) -> Result<u32> { ... }
    fn read_i32_le(&mut self) -> Result<i32> { ... }
    fn read_u64(&mut self) -> Result<u64> { ... }
    fn read_i64(&mut self) -> Result<i64> { ... }
    fn read_u64_le(&mut self) -> Result<u64> { ... }
    fn read_i64_le(&mut self) -> Result<i64> { ... }
    fn read_u128(&mut self) -> Result<u128> { ... }
    fn read_i128(&mut self) -> Result<i128> { ... }
    fn read_u128_le(&mut self) -> Result<u128> { ... }
    fn read_i128_le(&mut self) -> Result<i128> { ... }
    fn read_usize(&mut self) -> Result<usize> { ... }
    fn read_isize(&mut self) -> Result<isize> { ... }
    fn read_usize_le(&mut self) -> Result<usize> { ... }
    fn read_isize_le(&mut self) -> Result<isize> { ... }
}

A source stream of data.

Required Methods

fn available(&self) -> usize

Returns the number of bytes available for reading. This does not necessarily mean more data isn’t available, just that at least this count is may be read.

Example

use data_streams::DataSource;
 
let buf: &[u8] = b"Hello!";
assert_eq!(buf.available(), 6);

fn request(&mut self, count: usize) -> Result<bool>

Reads at most count bytes into an internal buffer, returning whether enough bytes are available. To return an end-of-stream error, use require instead.

Note that a request returning false doesn’t necessarily mean the stream has ended. More bytes may be read after.

Errors

If the byte count exceeds the spare buffer capacity, Error::InsufficientBuffer is returned and both the internal buffer and underlying streams remain unchanged.

Example

use data_streams::DataSource;

let mut buf: &[u8] = b"Hello!";
assert_eq!(buf.request(3)?, true);
assert_eq!(buf.request(50)?, false);

fn skip(&mut self, count: usize) -> Result<usize>

Consumes up to count bytes in the stream, returning the number of bytes consumed if successful. At least the available count may be consumed.

Errors

Returns any IO errors encountered.

Example

use data_streams::DataSource;
 
let mut buf: &[u8] = b"Hello!";
assert_eq!(buf.skip(3)?, 3);
assert_eq!(buf.skip(8)?, 3);

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

Reads bytes into a slice, returning the bytes read. This method is greedy; it consumes as many bytes as it can, until buf is filled or no more bytes are read.

Errors

Returns any IO errors encountered.

Example

use data_streams::DataSource;
 
let mut input: &[u8] = b"Hello!";
let buf: &mut [u8] = &mut [0; 5];
assert_eq!(input.read_bytes(&mut buf[..3])?, b"Hel");
assert_eq!(input.read_bytes(buf)?, b"lo!");

Provided Methods

fn require(&mut self, count: usize) -> Result

Reads at least count bytes into an internal buffer, returning Ok if successful, or an end-of-stream error if not. For a softer version that returns whether enough bytes are available, use request.

Errors

Returns Error::End if the stream ended before count bytes could be read. If the byte count exceeds the spare buffer capacity, Error::InsufficientBuffer is returned instead.

Example

use data_streams::{DataSource, Error};
 
let mut buf: &[u8] = b"Hello!";
assert!(buf.require(3).is_ok());
assert!(matches!(buf.require(50), Err(Error::End { .. })));

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

Reads the exact length of bytes into a slice, returning the bytes read if successful, or an end-of-stream error if not. Bytes are not consumed if an end-of-stream error is returned.

Errors

Returns Error::End with the slice length if the exact number of bytes cannot be read. The bytes that were read remain in the buffer, but have been consumed from the source.

Example

use data_streams::{DataSource, Error};
 
let mut input: &[u8] = b"Hello!";
let buf: &mut [u8] = &mut [0; 5];
assert_eq!(input.read_exact_bytes(&mut buf[..3])?, b"Hel");
assert!(matches!(input.read_exact_bytes(buf), Err(Error::End { .. })));

fn read_aligned_bytes<'a>( &mut self, buf: &'a mut [u8], alignment: usize, ) -> Result<&'a [u8]>

Reads bytes into a slice in multiples of alignment, returning the bytes read. This method is greedy; it consumes as many bytes as it can, until buf is filled or less than alignment bytes could be read.

If the alignment is zero, the returned slice is empty.

Errors

Returns any IO errors encountered.

Example

use data_streams::DataSource;
 
let mut input: &[u8] = b"Hello?!";
let buf: &mut [u8] = &mut [0; 10];
assert_eq!(input.read_aligned_bytes(buf, 2)?, b"Hello?");
assert_eq!(input.read_aligned_bytes(buf, 2)?, b"");

fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>

where Self: Sized,

Reads an array with a size of N bytes.

Errors

Returns Error::End with the array length if [N] bytes cannot be read.

Example

use data_streams::DataSource;
 
let mut input: &[u8] = b"Hello!";
assert_eq!(input.read_array::<3>()?, *b"Hel");

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

Reads a u8.

Errors

Returns Error::End if the stream ends before exactly 1 byte can be read.

Example

use data_streams::DataSource;
 
let mut buf: &[u8] = &[2, 3, 5, 7, 11];
 
let mut sum = 0;
while let Ok(byte) = buf.read_u8() {
    sum += byte;
}
assert_eq!(sum, 28);

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

Reads an i8.

Errors

Returns Error::End if the stream ends before exactly 1 byte can be read.

use data_streams::DataSource;

let mut buf: &[u8] = &[2, (-3i8) as u8, 5, (-7i8) as u8, 11];
 
let mut sum = 0;
while let Ok(byte) = buf.read_i8() {
    sum += byte;
}
assert_eq!(sum, 8);

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

Reads a big-endian u16.

Errors

Returns Error::End if the stream ends before exactly 2 bytes can be read.

Example

use data_streams::DataSource;
 
let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_u16()?, 0x1234);
assert_eq!(buf.read_u16()?, 0x5678);

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

Reads a big-endian i16.

Errors

Returns Error::End if the stream ends before exactly 2 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_i16()?, 0x1234);
assert_eq!(buf.read_i16()?, 0x5678);

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

Reads a little-endian u16.

Errors

Returns Error::End if the stream ends before exactly 2 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_u16_le()?, 0x3412);
assert_eq!(buf.read_u16_le()?, 0x7856);

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

Reads a little-endian i16.

Errors

Returns Error::End if the stream ends before exactly 2 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_i16_le()?, 0x3412);
assert_eq!(buf.read_i16_le()?, 0x7856);

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

Reads a big-endian u32.

Errors

Returns Error::End if the stream ends before exactly 4 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_u32()?, 0x12345678);

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

Reads a big-endian i32.

Errors

Returns Error::End if the stream ends before exactly 4 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_i32()?, 0x12345678);

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

Reads a little-endian u32.

Errors

Returns Error::End if the stream ends before exactly 4 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_u32_le()?, 0x78563412);

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

Reads a little-endian i32.

Errors

Returns Error::End if the stream ends before exactly 4 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[0x12, 0x34, 0x56, 0x78];
assert_eq!(buf.read_i32_le()?, 0x78563412);

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

Reads a big-endian u64.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_u64()?, 0x1234_5678_9ABC_DEF0);

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

Reads a big-endian i64.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_i64()?, 0x1234_5678_9ABC_DEF0);

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

Reads a little-endian u64.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_u64_le()?, 0xF0DE_BC9A_7856_3412);

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

Reads a little-endian i64.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_i64_le()?, 0xF0DE_BC9A_7856_3412u64 as i64);

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

Reads a big-endian u128.

Errors

Returns Error::End if the stream ends before exactly 16 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0,
    0x0F, 0xED, 0xCB, 0xA9,
    0x87, 0x65, 0x43, 0x21
];
assert_eq!(buf.read_u128()?, 0x1234_5678_9ABC_DEF0_0FED_CBA9_8765_4321);

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

Reads a big-endian i128.

Errors

Returns Error::End if the stream ends before exactly 16 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0,
    0x0F, 0xED, 0xCB, 0xA9,
    0x87, 0x65, 0x43, 0x21
];
assert_eq!(buf.read_i128()?, 0x1234_5678_9ABC_DEF0_0FED_CBA9_8765_4321);

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

Reads a little-endian u128.

Errors

Returns Error::End if the stream ends before exactly 16 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0,
    0x0F, 0xED, 0xCB, 0xA9,
    0x87, 0x65, 0x43, 0x21
];
assert_eq!(buf.read_u128_le()?, 0x2143_6587_A9CB_ED0F_F0DE_BC9A_7856_3412);

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

Reads a little-endian i128.

Errors

Returns Error::End if the stream ends before exactly 16 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0,
    0x0F, 0xED, 0xCB, 0xA9,
    0x87, 0x65, 0x43, 0x21
];
assert_eq!(buf.read_i128_le()?, 0x2143_6587_A9CB_ED0F_F0DE_BC9A_7856_3412);

fn read_usize(&mut self) -> Result<usize>

Reads a big-endian usize. To make streams consistent across platforms, usize is fixed to the size of u64 regardless of the target platform.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_usize()?, 0x1234_5678_9ABC_DEF0);

fn read_isize(&mut self) -> Result<isize>

Reads a big-endian isize. To make streams consistent across platforms, isize is fixed to the size of i64 regardless of the target platform.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_isize()?, 0x1234_5678_9ABC_DEF0);

fn read_usize_le(&mut self) -> Result<usize>

Reads a little-endian usize. To make streams consistent across platforms, usize is fixed to the size of u64 regardless of the target platform.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_usize_le()?, 0xF0DE_BC9A_7856_3412);

fn read_isize_le(&mut self) -> Result<isize>

Reads a little-endian isize. To make streams consistent across platforms, isize is fixed to the size of i64 regardless of the target platform.

Errors

Returns Error::End if the stream ends before exactly 8 bytes can be read.

Example

use data_streams::DataSource;

let mut buf: &[u8] = &[
    0x12, 0x34, 0x56, 0x78,
    0x9A, 0xBC, 0xDE, 0xF0
];
assert_eq!(buf.read_isize_le()?, 0xF0DE_BC9A_7856_3412usize as isize);

Implementations on Foreign Types

impl DataSource for &Empty

fn available(&self) -> usize

fn request(&mut self, _: usize) -> Result<bool>

fn skip(&mut self, _: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, _: &'a mut [u8]) -> Result<&'a [u8]>

impl DataSource for &[u8]

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_aligned_bytes<'a>( &mut self, buf: &'a mut [u8], alignment: usize, ) -> Result<&'a [u8]>

impl DataSource for VecDeque<u8>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_aligned_bytes<'a>( &mut self, buf: &'a mut [u8], alignment: usize, ) -> Result<&'a [u8]>

impl DataSource for Vec<u8>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_aligned_bytes<'a>( &mut self, buf: &'a mut [u8], alignment: usize, ) -> Result<&'a [u8]>

impl DataSource for Empty

fn available(&self) -> usize

fn request(&mut self, _: usize) -> Result<bool>

fn skip(&mut self, _: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, _: &'a mut [u8]) -> Result<&'a [u8]>

impl DataSource for Repeat

fn available(&self) -> usize

fn request(&mut self, _: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

impl<R: Read + ?Sized> DataSource for BufReader<R>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

impl<S: DataSource + ?Sized> DataSource for &mut S

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn require(&mut self, count: usize) -> Result

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fn read_usize(&mut self) -> Result<usize>

fn read_isize(&mut self) -> Result<isize>

fn read_usize_le(&mut self) -> Result<usize>

fn read_isize_le(&mut self) -> Result<isize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>

impl<S: DataSource + ?Sized> DataSource for Box<S>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn require(&mut self, count: usize) -> Result

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fn read_usize(&mut self) -> Result<usize>

fn read_isize(&mut self) -> Result<isize>

fn read_usize_le(&mut self) -> Result<usize>

fn read_isize_le(&mut self) -> Result<isize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>

impl<T: AsRef<[u8]>> DataSource for Cursor<T>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

impl<T: BufferAccess + BufRead> DataSource for Take<T>

fn available(&self) -> usize

fn request(&mut self, count: usize) -> Result<bool>

fn skip(&mut self, count: usize) -> Result<usize>

fn read_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

fn read_exact_bytes<'a>(&mut self, buf: &'a mut [u8]) -> Result<&'a [u8]>

Implementors