Trait scroll::IOread[][src]

pub trait IOread<Ctx: Copy>: Read {
    fn ioread<N: FromCtx<Ctx> + SizeWith<Ctx, Units = usize>>(
        &mut self
    ) -> Result<N>
    where
        Ctx: Default
, { ... }
fn ioread_with<N: FromCtx<Ctx> + SizeWith<Ctx, Units = usize>>(
        &mut self,
        ctx: Ctx
    ) -> Result<N> { ... } }

An extension trait to std::io::Read streams; this only deserializes simple types, like u8, i32, f32, usize, etc.

If you implement FromCtx and SizeWith for your type, you can then ioread::<YourType>() on a Read. Note: FromCtx is only meant for very simple types, and should never fail.

NB You should probably add repr(packed) or repr(C) and be very careful how you implement SizeWith, otherwise you will get IO errors failing to fill entire buffer (the size you specified in SizeWith), or out of bound errors (depending on your impl) in from_ctx

Example

use std::io::Cursor;
use scroll::{self, ctx, LE, Pread, IOread};

#[repr(packed)]
struct Foo {
    foo: i64,
    bar: u32,
}

impl ctx::FromCtx<scroll::Endian> for Foo {
    fn from_ctx(bytes: &[u8], ctx: scroll::Endian) -> Self {
        Foo { foo: bytes.pread_with::<i64>(0, ctx).unwrap(), bar: bytes.pread_with::<u32>(8, ctx).unwrap() }
    }
}

impl ctx::SizeWith<scroll::Endian> for Foo {
    type Units = usize;
    // our parsing context doesn't influence our size
    fn size_with(_: &scroll::Endian) -> Self::Units {
        ::std::mem::size_of::<Foo>()
    }
}

let bytes_ = [0x0b,0x0b,0x00,0x00,0x00,0x00,0x00,0x00, 0xef,0xbe,0x00,0x00,];
let mut bytes = Cursor::new(bytes_);
let foo = bytes.ioread_with::<i64>(LE).unwrap();
let bar = bytes.ioread_with::<u32>(LE).unwrap();
assert_eq!(foo, 0xb0b);
assert_eq!(bar, 0xbeef);
let error = bytes.ioread_with::<f64>(LE);
assert!(error.is_err());
let mut bytes = Cursor::new(bytes_);
let foo_ = bytes.ioread_with::<Foo>(LE).unwrap();
// Remember that you need to copy out fields from packed structs
// with a `{}` block instead of borrowing them directly
// ref: https://github.com/rust-lang/rust/issues/46043
assert_eq!({foo_.foo}, foo);
assert_eq!({foo_.bar}, bar);

Provided Methods

Reads the type N from Self, with a default parsing context. For the primitive numeric types, this will be at the host machine's endianness.

Example

use scroll::IOread;
use std::io::Cursor;
let bytes = [0xef, 0xbe];
let mut bytes = Cursor::new(&bytes[..]);
let beef = bytes.ioread::<u16>().unwrap();

#[cfg(target_endian = "little")]
assert_eq!(0xbeef, beef);
#[cfg(target_endian = "big")]
assert_eq!(0xefbe, beef);

Reads the type N from Self, with the parsing context ctx. NB: this will panic if the type you're reading has a size greater than 256. Plans are to have this allocate in larger cases.

For the primitive numeric types, this will be at the host machine's endianness.

Example

use scroll::{IOread, LE, BE};
use std::io::Cursor;
let bytes = [0xef, 0xbe, 0xb0, 0xb0, 0xfe, 0xed, 0xde, 0xad];
let mut bytes = Cursor::new(&bytes[..]);
let beef = bytes.ioread_with::<u16>(LE).unwrap();
assert_eq!(0xbeef, beef);
let b0 = bytes.ioread::<u8>().unwrap();
assert_eq!(0xb0, b0);
let b0 = bytes.ioread::<u8>().unwrap();
assert_eq!(0xb0, b0);
let feeddead = bytes.ioread_with::<u32>(BE).unwrap();
assert_eq!(0xfeeddead, feeddead);

Implementors