diff options
Diffstat (limited to '')
-rw-r--r-- | third_party/rust/scroll/src/pread.rs | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/third_party/rust/scroll/src/pread.rs b/third_party/rust/scroll/src/pread.rs new file mode 100644 index 0000000000..72ba877054 --- /dev/null +++ b/third_party/rust/scroll/src/pread.rs @@ -0,0 +1,178 @@ +use core::result; + +use crate::ctx::TryFromCtx; +use crate::error; + +/// A very generic, contextual pread interface in Rust. +/// +/// Like [Pwrite](trait.Pwrite.html) — but for reading! +/// +/// Implementing `Pread` on a data store allows you to then read almost arbitrarily complex types +/// efficiently. +/// +/// To this end the Pread trait works in conjuction with the [TryFromCtx](ctx/trait.TryFromCtx.html); +/// The `TryFromCtx` trait implemented on a type defines how to convert data to an object of that +/// type, the Pread trait implemented on a data store defines how to extract said data from that +/// store. +/// +/// It should be noted though that in this context, data does not necessarily mean `&[u8]` — +/// `Pread` and `TryFromCtx` are generic over what 'data' means and could be implemented instead +/// over chunks of memory or any other indexable type — but scroll does come with a set of powerful +/// blanket implementations for data being a continous block of byte-addressable memory. +/// +/// Pread provides two main groups of functions: pread and gread. +/// +/// `pread` is the basic function that simply extracts a given type from a given data store - either +/// using a provided Context in the case of [pread_with](trait.Pread.html#method.pread_with) or +/// with the default context for the given type in the case of [pread](trait.Pread.html#method.pread) +/// +/// `gread` does in addition to that update the offset it's currently at, allowing for a cursored +/// read — `gread_inout` expands on that and reads a number of continous types from the data store. +/// gread again comes with `_with` variants to allow using a specific context. +/// +/// Since pread and friends are very generic functions their types are rather complex, but very +/// much understandable; `TryFromCtx` is generic over `Ctx` ([described +/// here](ctx/index.html#context)), `Output` and `Error`. The Error type is hopefully +/// self-explanatory, however the `Output` type is rather important; it defines what Pread extracts +/// from the data store and has to match up with what `TryFromCtx` expects as input to convert into +/// the resulting type. scroll defaults to `&[u8]` here. +/// +/// Unless you need to implement your own data store — that is either can't convert to `&[u8]` or +/// have a data that does not expose a `&[u8]` — you will probably want to implement +/// [TryFromCtx](ctx/trait.TryFromCtx.html) on your Rust types to be extracted. +/// +pub trait Pread<Ctx: Copy, E> { + #[inline] + /// Reads a value from `self` at `offset` with a default `Ctx`. For the primitive numeric values, this will read at the machine's endianness. + /// # Example + /// ```rust + /// use scroll::Pread; + /// let bytes = [0x7fu8; 0x01]; + /// let byte = bytes.pread::<u8>(0).unwrap(); + fn pread<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: usize, + ) -> result::Result<N, E> + where + Ctx: Default, + { + self.pread_with(offset, Ctx::default()) + } + + #[inline] + /// Reads a value from `self` at `offset` with the given `ctx` + /// # Example + /// ```rust + /// use scroll::Pread; + /// let bytes: [u8; 2] = [0xde, 0xad]; + /// let dead: u16 = bytes.pread_with(0, scroll::BE).unwrap(); + /// assert_eq!(dead, 0xdeadu16); + fn pread_with<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: usize, + ctx: Ctx, + ) -> result::Result<N, E> { + let mut ignored = offset; + self.gread_with(&mut ignored, ctx) + } + + #[inline] + /// Reads a value from `self` at `offset` with a default `Ctx`. For the primitive numeric values, this will read at the machine's endianness. Updates the offset + /// # Example + /// ```rust + /// use scroll::Pread; + /// let offset = &mut 0; + /// let bytes = [0x7fu8; 0x01]; + /// let byte = bytes.gread::<u8>(offset).unwrap(); + /// assert_eq!(*offset, 1); + fn gread<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: &mut usize, + ) -> result::Result<N, E> + where + Ctx: Default, + { + let ctx = Ctx::default(); + self.gread_with(offset, ctx) + } + + /// Reads a value from `self` at `offset` with the given `ctx`, and updates the offset. + /// # Example + /// ```rust + /// use scroll::Pread; + /// let offset = &mut 0; + /// let bytes: [u8; 2] = [0xde, 0xad]; + /// let dead: u16 = bytes.gread_with(offset, scroll::BE).unwrap(); + /// assert_eq!(dead, 0xdeadu16); + /// assert_eq!(*offset, 2); + fn gread_with<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: &mut usize, + ctx: Ctx, + ) -> result::Result<N, E>; + + /// Tries to write `inout.len()` `N`s into `inout` from `Self` starting at `offset`, using the default context for `N`, and updates the offset. + /// # Example + /// ```rust + /// use scroll::Pread; + /// let mut bytes: Vec<u8> = vec![0, 0]; + /// let offset = &mut 0; + /// let bytes_from: [u8; 2] = [0x48, 0x49]; + /// bytes_from.gread_inout(offset, &mut bytes).unwrap(); + /// assert_eq!(&bytes, &bytes_from); + /// assert_eq!(*offset, 2); + #[inline] + fn gread_inout<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: &mut usize, + inout: &mut [N], + ) -> result::Result<(), E> + where + Ctx: Default, + { + for i in inout.iter_mut() { + *i = self.gread(offset)?; + } + Ok(()) + } + + /// Tries to write `inout.len()` `N`s into `inout` from `Self` starting at `offset`, using the context `ctx` + /// # Example + /// ```rust + /// use scroll::{ctx, LE, Pread}; + /// let mut bytes: Vec<u8> = vec![0, 0]; + /// let offset = &mut 0; + /// let bytes_from: [u8; 2] = [0x48, 0x49]; + /// bytes_from.gread_inout_with(offset, &mut bytes, LE).unwrap(); + /// assert_eq!(&bytes, &bytes_from); + /// assert_eq!(*offset, 2); + #[inline] + fn gread_inout_with<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: &mut usize, + inout: &mut [N], + ctx: Ctx, + ) -> result::Result<(), E> { + for i in inout.iter_mut() { + *i = self.gread_with(offset, ctx)?; + } + Ok(()) + } +} + +impl<Ctx: Copy, E: From<error::Error>> Pread<Ctx, E> for [u8] { + fn gread_with<'a, N: TryFromCtx<'a, Ctx, Self, Error = E>>( + &'a self, + offset: &mut usize, + ctx: Ctx, + ) -> result::Result<N, E> { + let start = *offset; + if start >= self.len() { + return Err(error::Error::BadOffset(start).into()); + } + N::try_from_ctx(&self[start..], ctx).map(|(n, size)| { + *offset += size; + n + }) + } +} |