consensus_encoding: rename min_bytes_needed

The `min_bytes_needed` name is a bit of a misnomer because it implies a
lower bound instead of an upper. I believe the original intention was
to capture "minimum bytes needed to advance the state of the decoder",
but that is a little wordy. Updated to `read_limit` since this is an
upper bound to protect against over consuming bytes the decoder doesn't
know what to do with.

Author: nyonson

consensus_encoding/src/decode/decoders.rs

@@ -95,9 +95,9 @@ impl Decoder for ByteVecDecoder {
         }
     }
 
-    fn min_bytes_needed(&self) -> usize {
+    fn read_limit(&self) -> usize {
         if let Some(prefix_decoder) = &self.prefix_decoder {
-            prefix_decoder.min_bytes_needed()
+            prefix_decoder.read_limit()
         } else {
             self.bytes_expected - self.bytes_written
         }
@@ -193,20 +193,20 @@ impl<T: Decodable> Decoder for VecDecoder<T> {
         }
     }
 
-    fn min_bytes_needed(&self) -> usize {
+    fn read_limit(&self) -> usize {
         if let Some(prefix_decoder) = &self.prefix_decoder {
-            prefix_decoder.min_bytes_needed()
+            prefix_decoder.read_limit()
         } else if let Some(decoder) = &self.decoder {
-            decoder.min_bytes_needed()
+            decoder.read_limit()
         } else if self.buffer.len() == self.length {
             // Totally done.
             0
         } else {
             let items_left_to_decode = self.length - self.buffer.len();
             let decoder = T::decoder();
             // This could be inaccurate (eg 1 for a `ByteVecDecoder`) but its the best we can do.
-            let min_per_decoder = decoder.min_bytes_needed();
-            items_left_to_decode * min_per_decoder
+            let limit_per_decoder = decoder.read_limit();
+            items_left_to_decode * limit_per_decoder
         }
     }
 }
@@ -274,7 +274,7 @@ impl<const N: usize> Decoder for ArrayDecoder<N> {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { N - self.bytes_written }
+    fn read_limit(&self) -> usize { N - self.bytes_written }
 }
 
 /// A decoder which wraps two inner decoders and returns the output of both.
@@ -395,11 +395,11 @@ where
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize {
+    fn read_limit(&self) -> usize {
         match &self.state {
             Decoder2State::First(first_decoder, second_decoder) =>
-                first_decoder.min_bytes_needed() + second_decoder.min_bytes_needed(),
-            Decoder2State::Second(_, second_decoder) => second_decoder.min_bytes_needed(),
+                first_decoder.read_limit() + second_decoder.read_limit(),
+            Decoder2State::Second(_, second_decoder) => second_decoder.read_limit(),
             Decoder2State::Errored => 0,
             Decoder2State::Transitioning => 0,
         }
@@ -453,7 +453,7 @@ where
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.inner.read_limit() }
 }
 
 /// A decoder which decodes four objects, one after the other.
@@ -509,7 +509,7 @@ where
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.inner.read_limit() }
 }
 
 /// A decoder which decodes six objects, one after the other.
@@ -590,7 +590,7 @@ where
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.inner.read_limit() }
 }
 
 /// Decodes a compact size encoded integer.
@@ -679,7 +679,7 @@ impl Decoder for CompactSizeDecoder {
         }
     }
 
-    fn min_bytes_needed(&self) -> usize {
+    fn read_limit(&self) -> usize {
         match self.buf.len() {
             0 => 1,
             already_read => match self.buf[0] {
@@ -984,7 +984,7 @@ mod tests {
             Ok(Inner(n))
         }
 
-        fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.0.read_limit() }
     }
 
     #[cfg(feature = "alloc")]
@@ -1016,7 +1016,7 @@ mod tests {
             Ok(Test(v))
         }
 
-        fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.0.read_limit() }
     }
 
     #[cfg(feature = "alloc")]

consensus_encoding/src/decode/mod.rs

@@ -59,13 +59,12 @@ pub trait Decoder: Sized {
     #[must_use = "must check result to avoid panics on subsequent calls"]
     fn end(self) -> Result<Self::Output, Self::Error>;
 
-    /// Returns the minimum number of bytes needed to advance the state of the
-    /// decoder while ensuring there are no over-reads.
+    /// Returns the maximum number of bytes this decoder can consume without over-reading.
     ///
     /// Returns 0 if the decoder is complete and ready to finalize with [`Self::end`].
     /// This is used by [`decode_from_read_unbuffered`] to optimize read sizes,
-    /// avoiding both inefficient under reads and unnecessary over-reads.
-    fn min_bytes_needed(&self) -> usize;
+    /// avoiding both inefficient under-reads and unnecessary over-reads.
+    fn read_limit(&self) -> usize;
 }
 
 /// Decodes an object from a byte slice.
@@ -192,9 +191,9 @@ where
     let mut decoder = T::decoder();
     let mut buffer = [0u8; BUFFER_SIZE];
 
-    while decoder.min_bytes_needed() > 0 {
+    while decoder.read_limit() > 0 {
         // Only read what we need, up to buffer size.
-        let clamped_buffer = &mut buffer[..decoder.min_bytes_needed().min(BUFFER_SIZE)];
+        let clamped_buffer = &mut buffer[..decoder.read_limit().min(BUFFER_SIZE)];
         match reader.read(clamped_buffer) {
             Ok(0) => {
                 // EOF, but still try to finalize the decoder.
@@ -288,7 +287,7 @@ mod tests {
 
         fn end(self) -> Result<Self::Output, Self::Error> { self.inner.end().map(TestArray) }
 
-        fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.inner.read_limit() }
     }
 
     #[test]

consensus_encoding/tests/composition.rs

@@ -69,7 +69,7 @@ impl Decoder for CompositeDataDecoder {
         Ok(CompositeData { first, second })
     }
 
-    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.inner.read_limit() }
 }
 
 impl Decodable for CompositeData {
@@ -220,7 +220,7 @@ fn composition_error_unification() {
             Ok((first, second))
         }
 
-        fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.inner.read_limit() }
     }
 
     /// Another test composite decoder.
@@ -245,7 +245,7 @@ fn composition_error_unification() {
             Ok(result)
         }
 
-        fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.inner.read_limit() }
     }
 
     /// A decoder which can fail.
@@ -274,7 +274,7 @@ fn composition_error_unification() {
             }
         }
 
-        fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
+        fn read_limit(&self) -> usize { self.inner.read_limit() }
     }
 
     // A multi-layer, nested, decoder structure with a unified top level error type.

units/src/amount/unsigned.rs

@@ -610,7 +610,7 @@ impl encoding::Decoder for AmountDecoder {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.0.read_limit() }
 }
 
 #[cfg(feature = "encoding")]

units/src/block.rs

@@ -193,7 +193,7 @@ impl encoding::Decoder for BlockHeightDecoder {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.0.read_limit() }
 }
 
 #[cfg(feature = "encoding")]

units/src/locktime/absolute/mod.rs

@@ -451,7 +451,7 @@ impl encoding::Decoder for LockTimeDecoder {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.0.read_limit() }
 }
 
 #[cfg(feature = "encoding")]

units/src/sequence.rs

@@ -316,7 +316,7 @@ impl encoding::Decoder for SequenceDecoder {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.0.read_limit() }
 }
 
 #[cfg(feature = "encoding")]

units/src/time.rs

@@ -126,7 +126,7 @@ impl encoding::Decoder for BlockTimeDecoder {
     }
 
     #[inline]
-    fn min_bytes_needed(&self) -> usize { self.0.min_bytes_needed() }
+    fn read_limit(&self) -> usize { self.0.read_limit() }
 }
 
 #[cfg(feature = "encoding")]