add zero_copy method

Author: antonilol

heed-traits/src/lib.rs

@@ -27,12 +27,33 @@ pub trait BytesEncode<'a> {
     /// The error type to return when decoding goes wrong.
     type Error: StdError + Send + Sync + 'static;
 
+    /// This function can be used to hint callers of the
+    /// [`bytes_encode`][BytesEncode::bytes_encode] function to use
+    /// [`bytes_encode_into_writer`][BytesEncode::bytes_encode_into_writer] instead, if the latter
+    /// runs faster (for example if it needs less heap allocations).
+    ///
+    /// The default implementation returns `true` because the default implementation of
+    /// [`bytes_encode_into_writer`][BytesEncode::bytes_encode_into_writer] is to forward to
+    /// [`bytes_encode`][BytesEncode::bytes_encode].
+    fn zero_copy(item: &Self::EItem) -> bool {
+        // This is preferred to renaming the function parameter (to _item) because IDEs can
+        // autofill trait implementations, which will default the paramter name to _item then and
+        // this could probably also mess with clippy's renamed_function_params lint.
+        let _ = item;
+
+        true
+    }
+
     /// Encode the given item as bytes.
     fn bytes_encode(item: &'a Self::EItem) -> Result<Self::ReturnBytes, Self::Error>;
 
     /// Encode the given item as bytes and write it into the writer. Returns the amount of bytes
-    /// that were written. This function by default forwards to
-    /// [`bytes_encode`][BytesEncode::bytes_encode].
+    /// that were written.
+    ///
+    /// When implementing this, also take a look at [`zero_copy`][BytesEncode::zero_copy]'s
+    /// documentation.
+    ///
+    /// The default implementation forwards to [`bytes_encode`][BytesEncode::bytes_encode].
     fn bytes_encode_into_writer<W: io::Write>(
         item: &'a Self::EItem,
         writer: &mut W,