Modify the Encodable API to mirror core functionality form Decodable

- `encode` now takes a `Bufferfish` and writes directly to it
- `encode_value` is a new function that writes a raw value, without
encoding it as a "packet"; eg. it will not encode a header
- `to_bufferfish` remains the same

Author: robertwayne

rust/bufferfish-core/src/decodable.rs

@@ -4,10 +4,10 @@ use crate::{Bufferfish, BufferfishError};
 
 /// Types implementing this trait are able to be decoded from a `Bufferfish`.
 pub trait Decodable: Sized {
-    /// Decode the type from a `Bufferfish`.
+    /// Decode the type from a given `Bufferfish`.
     fn decode(bf: &mut Bufferfish) -> Result<Self, BufferfishError>;
 
-    /// Creates a checked generic type from a `Bufferfish`.
+    /// Creates a checked, generic type from a `Bufferfish`.
     ///
     /// If the `Bufferfish` does not contain enough bytes to properly
     /// decode the type, an error is returned.

rust/bufferfish-core/src/encodable.rs

@@ -4,100 +4,104 @@ use crate::{Bufferfish, BufferfishError};
 
 /// Types implementing this trait are able to be encoded to a `Bufferfish`.
 pub trait Encodable: Sized {
-    /// Encode the type into a given `Bufferfish`.
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError>;
+    /// Encode this type into a given `Bufferfish`.
+    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+        self.encode_value(bf)
+    }
+
+    /// Encodes a raw value into a given `Bufferfish`.
+    ///
+    /// Note: This is generally not what you want to call on types
+    /// implementing `Encodable`, as it will not encode the header value.
+    /// Instead, use `encode` to encode an entire type.
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError>;
 
     /// Encode the type into a new `Bufferfish`.
+    ///
+    /// Note: As this allocates a new `Bufferfish`, consider using
+    /// `encode` instead and reusing a previously allocated `Bufferfish`.
     fn to_bufferfish(&self) -> Result<Bufferfish, BufferfishError> {
         let mut bf = Bufferfish::new();
         self.encode(&mut bf)?;
 
         Ok(bf)
     }
-
-    /// Encode this type into a provided `Bufferfish` buffer.
-    ///
-    /// This is useful when you want to reuse an existing buffer to avoid
-    /// allocations.
-    fn encode_into(self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
-        self.encode(bf)
-    }
 }
 
 impl Encodable for u8 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_u8(*self)
     }
 }
 
 impl Encodable for u16 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_u16(*self)
     }
 }
 
 impl Encodable for u32 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_u32(*self)
     }
 }
 
 impl Encodable for u64 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_u64(*self)
     }
 }
 
 impl Encodable for u128 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_u128(*self)
     }
 }
 
 impl Encodable for i8 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_i8(*self)
     }
 }
 
 impl Encodable for i16 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_i16(*self)
     }
 }
 
 impl Encodable for i32 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_i32(*self)
     }
 }
 
 impl Encodable for i64 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_i64(*self)
     }
 }
 
 impl Encodable for i128 {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_i128(*self)
     }
 }
 
 impl Encodable for bool {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_bool(*self)
     }
 }
 
 impl Encodable for String {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_string(self)
     }
 }
 
 impl<T: Encodable> Encodable for Vec<T> {
-    fn encode(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
+    fn encode_value(&self, bf: &mut Bufferfish) -> Result<(), BufferfishError> {
         bf.write_array(self)
     }
 }

rust/bufferfish-core/src/lib.rs

@@ -366,7 +366,7 @@ impl Bufferfish {
         self.write_u16(vec.len() as u16)?;
 
         for item in vec {
-            item.encode(self)?;
+            item.encode_value(self)?;
         }
 
         Ok(())

rust/bufferfish-derive/src/lib.rs

@@ -55,23 +55,22 @@ pub fn bufferfish_impl_encodable(input: proc_macro::TokenStream) -> proc_macro::
 
     let generated = quote! {
         impl bufferfish::Encodable for #name {
-            fn encode(&self, bf: &mut bufferfish::Bufferfish) -> Result<(), bufferfish::BufferfishError> {
+            fn encode_value(&self, bf: &mut bufferfish::Bufferfish) -> Result<(), bufferfish::BufferfishError> {
                 #(#encoded_snippets)*
                 Ok(())
             }
 
             fn to_bufferfish(&self) -> Result<bufferfish::Bufferfish, bufferfish::BufferfishError> {
                 let mut bf = bufferfish::Bufferfish::new();
-                #packet_id_snippet
                 self.encode(&mut bf)?;
 
                 Ok(bf)
             }
 
-            fn encode_into(self, bf: &mut bufferfish::Bufferfish) -> Result<(), bufferfish::BufferfishError>
+            fn encode(&self, bf: &mut bufferfish::Bufferfish) -> Result<(), bufferfish::BufferfishError>
             {
                 #packet_id_snippet
-                self.encode(bf)
+                self.encode_value(bf)
             }
         }
     };

rust/bufferfish/src/lib.rs

@@ -689,7 +689,7 @@ mod tests {
         };
         let packet = JoinPacket { user };
 
-        packet.encode_into(&mut bf).unwrap();
+        packet.encode(&mut bf).unwrap();
 
         assert_eq!(
             bf.as_ref(),
@@ -722,7 +722,7 @@ mod tests {
         ];
 
         let mut bf = Bufferfish::new();
-        users.encode_into(&mut bf).unwrap();
+        users.encode(&mut bf).unwrap();
 
         assert_eq!(
             bf.as_ref(),
@@ -776,7 +776,7 @@ mod tests {
             class: Class::Warrior,
         };
 
-        packet.encode_into(&mut bf).unwrap();
+        packet.encode(&mut bf).unwrap();
 
         assert_eq!(bf.as_ref(), &[0, 0, 0]);
     }