io: add read_i8_into to ReadBytesExt

The `read_i8_into` method is useful for client code
that wants to avoid `unsafe`.

PR #147 

1 files changed, 36 insertions, 0 deletions

diff --git a/src/io.rs b/src/io.rs
index bc49a1c..ed6a848 100644
--- a/src/io.rs
+++ b/src/io.rs
@@ -685,6 +685,42 @@ pub trait ReadBytesExt: io::Read {
         Ok(())
     }
 
+    /// Reads a sequence of signed 8 bit integers from the underlying reader.
+    ///
+    /// The given buffer is either filled completely or an error is returned.
+    /// If an error is returned, the contents of `dst` are unspecified.
+    ///
+    /// Note that since each `i8` is a single byte, no byte order conversions
+    /// are used. This method is included because it provides a safe, simple
+    /// way for the caller to read into a `&mut [i8]` buffer. (Without this
+    /// method, the caller would have to either use `unsafe` code or convert
+    /// each byte to `i8` individually.)
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Read::read_exact`].
+    ///
+    /// [`Read::read_exact`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact
+    ///
+    /// # Examples
+    ///
+    /// Read a sequence of signed 8 bit integers from a `Read`:
+    ///
+    /// ```rust
+    /// use std::io::Cursor;
+    /// use byteorder::{BigEndian, ReadBytesExt};
+    ///
+    /// let mut rdr = Cursor::new(vec![2, 251, 3]);
+    /// let mut dst = [0; 3];
+    /// rdr.read_i8_into(&mut dst).unwrap();
+    /// assert_eq!([2, -5, 3], dst);
+    /// ```
+    #[inline]
+    fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<()> {
+        let buf = unsafe { slice_to_u8_mut(dst) };
+        self.read_exact(buf)
+    }
+
     /// Reads a sequence of signed 16 bit integers from the underlying
     /// reader.
     ///