Revise API for fixed integer coding

Author: dermesser

src/fixed.rs

@@ -1,30 +1,32 @@
 use std::convert::TryInto;
 use std::mem::size_of;
 
-/// `FixedInt` provides encoding/decoding to and from fixed int representations.
+/// `FixedInt` provides encoding/decoding to and from fixed int representations. Note that current
+/// Rust versions already provide this functionality via the `to_le_bytes()` and `to_be_bytes()`
+/// methods.
 ///
 /// The emitted bytestring contains the bytes of the integer in machine endianness.
 pub trait FixedInt: Sized + Copy {
     type Bytes: AsRef<[u8]>;
+    const ENCODED_SIZE: usize = size_of::<Self>();
 
-    /// Encode a value into the given slice. `dst` must be exactly `REQUIRED_SPACE` bytes.
-    fn encode_fixed(self, dst: &mut [u8]);
-    /// Decode a value from the given slice. `src` must be exactly `REQUIRED_SPACE` bytes.
-    fn decode_fixed(src: &[u8]) -> Self;
+    /// Encode a value into the given slice using machine endianness. Returns `None` if `dst`
+    /// doesn't provide enough space to encode this integer.
+    fn encode_fixed(self, dst: &mut [u8]) -> Option<()>;
     /// Returns the representation of [`FixedInt`] as [`Bytes`], the little-endian representation
     /// of self in the stack.
     fn encode_fixed_light(self) -> Self::Bytes;
 
+    /// Decode a value from the given slice assuming little-endian.
+    fn decode_le_fixed(src: &[u8]) -> Option<Self>;
+    /// Decode a value from the given slice assuming big-endian.
+    fn decode_be_fixed(src: &[u8]) -> Option<Self>;
+
     /// Helper: Encode the value and return a Vec.
     fn encode_fixed_vec(self) -> Vec<u8> {
         self.encode_fixed_light().as_ref().to_vec()
     }
 
-    /// Helper: Decode the value from the Vec.
-    fn decode_fixed_vec(v: &Vec<u8>) -> Self {
-        Self::decode_fixed(&v[..])
-    }
-
     /// integer-encoding-rs always emits and receives little-endian integers (converting implicitly
     /// on big-endian machines). If you receive a big-endian integer, and would like it to be
     /// treated correctly, use this helper method to convert between endiannesses.
@@ -36,23 +38,33 @@ macro_rules! impl_fixedint {
         impl FixedInt for $t {
             type Bytes = [u8; size_of::<$t>()];
 
-            fn encode_fixed_light(self) -> Self::Bytes {
-                self.to_le_bytes()
+            fn encode_fixed(self, dst: &mut [u8]) -> Option<()> {
+                if dst.len() == size_of::<Self>() {
+                    dst.clone_from_slice(&self.to_le_bytes());
+                    Some(())
+                } else {
+                    None
+                }
             }
 
-            fn encode_fixed(self, dst: &mut [u8]) {
-                assert_eq!(dst.len(), size_of::<Self>());
-                dst.clone_from_slice(&self.to_le_bytes());
+            fn encode_fixed_light(self) -> Self::Bytes {
+                self.to_le_bytes()
             }
 
-            #[cfg(target_endian = "little")]
-            fn decode_fixed(src: &[u8]) -> Self {
-                Self::from_le_bytes(src.try_into().unwrap())
+            fn decode_le_fixed(src: &[u8]) -> Option<Self> {
+                if src.len() == size_of::<Self>() {
+                    Some(Self::from_le_bytes(src.try_into().unwrap()))
+                } else {
+                    None
+                }
             }
 
-            #[cfg(target_endian = "big")]
-            fn decode_fixed(src: &[u8]) -> $t {
-                Self::from_be_bytes(src.try_into().unwrap())
+            fn decode_be_fixed(src: &[u8]) -> Option<Self> {
+                if src.len() == size_of::<Self>() {
+                    Some(Self::from_be_bytes(src.try_into().unwrap()))
+                } else {
+                    None
+                }
             }
 
             fn switch_endianness(self) -> Self {

src/reader.rs

@@ -115,35 +115,47 @@ impl<R: Read> VarIntReader for R {
 }
 
 /// A trait for reading FixedInts from any other `Reader`.
+///
+/// On EOF, an io::Error with io::ErrorKind::UnexpectedEof is returned.
 pub trait FixedIntReader {
-    /// Read a fixed integer from a reader. How many bytes are read depends on `FI`.
-    ///
-    /// On EOF, an io::Error with io::ErrorKind::UnexpectedEof is returned.
-    fn read_fixedint<FI: FixedInt>(&mut self) -> Result<FI>;
+    fn read_le_fixedint<FI: FixedInt>(&mut self) -> Result<FI>;
+    fn read_be_fixedint<FI: FixedInt>(&mut self) -> Result<FI>;
 }
 
 /// Like FixedIntReader, but returns a future.
 #[cfg(any(feature = "tokio_async", feature = "futures_async"))]
 #[async_trait::async_trait]
 pub trait FixedIntAsyncReader {
-    async fn read_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI>;
+    async fn read_le_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI>;
+    async fn read_be_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI>;
 }
 
 #[cfg(any(feature = "tokio_async", feature = "futures_async"))]
 #[async_trait::async_trait]
 impl<AR: AsyncRead + Unpin + Send> FixedIntAsyncReader for AR {
-    async fn read_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI> {
+    async fn read_le_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI> {
+        let mut buf = [0 as u8; 8];
+        self.read_exact(&mut buf[0..std::mem::size_of::<FI>()])
+            .await?;
+        Ok(FI::decode_le_fixed(&buf[0..std::mem::size_of::<FI>()]).unwrap())
+    }
+    async fn read_be_fixedint_async<FI: FixedInt>(&mut self) -> Result<FI> {
         let mut buf = [0 as u8; 8];
         self.read_exact(&mut buf[0..std::mem::size_of::<FI>()])
             .await?;
-        Ok(FI::decode_fixed(&buf[0..std::mem::size_of::<FI>()]))
+        Ok(FI::decode_be_fixed(&buf[0..std::mem::size_of::<FI>()]).unwrap())
     }
 }
 
 impl<R: Read> FixedIntReader for R {
-    fn read_fixedint<FI: FixedInt>(&mut self) -> Result<FI> {
+    fn read_le_fixedint<FI: FixedInt>(&mut self) -> Result<FI> {
+        let mut buf = [0 as u8; 8];
+        self.read_exact(&mut buf[0..std::mem::size_of::<FI>()])?;
+        Ok(FI::decode_le_fixed(&buf[0..std::mem::size_of::<FI>()]).unwrap())
+    }
+    fn read_be_fixedint<FI: FixedInt>(&mut self) -> Result<FI> {
         let mut buf = [0 as u8; 8];
         self.read_exact(&mut buf[0..std::mem::size_of::<FI>()])?;
-        Ok(FI::decode_fixed(&buf[0..std::mem::size_of::<FI>()]))
+        Ok(FI::decode_be_fixed(&buf[0..std::mem::size_of::<FI>()]).unwrap())
     }
 }