Merge rust-bitcoin#5107: Rename min_bytes_needed to read_limit

38b47c7 Update API (Nick Johnson)
ac51770 consensus_encoding: rename min_bytes_needed (Nick Johnson)

Pull request description:

  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.


ACKs for top commit:
  apoelstra:
    ACK 38b47c7; successfully ran local tests
  tcharding:
    ACK 38b47c7


Tree-SHA512: 29f7d6d4bf9905c6cc8ee3f13d35c18326e91aa681916524a6d3ce8466088a544c727a0b5cb876144508f25d306daa020f3a2c5e08ae5fc42fc27008066584cd

Author: apoelstra

api/units/all-features.txt

@@ -1900,9 +1900,9 @@ pub fn bitcoin_units::Weight::try_from(s: alloc::boxed::Box<str>) -> core::resul
 pub fn bitcoin_units::Weight::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::amount::AmountDecoder::default() -> Self
 pub fn bitcoin_units::amount::AmountDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
-pub fn bitcoin_units::amount::AmountDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::amount::AmountDecoder::new() -> Self
 pub fn bitcoin_units::amount::AmountDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
+pub fn bitcoin_units::amount::AmountDecoder::read_limit(&self) -> usize
 pub fn bitcoin_units::amount::AmountEncoder::advance(&mut self) -> bool
 pub fn bitcoin_units::amount::AmountEncoder::current_chunk(&self) -> core::option::Option<&[u8]>
 pub fn bitcoin_units::amount::Denomination::arbitrary(u: &mut arbitrary::unstructured::Unstructured<'a>) -> arbitrary::error::Result<Self>
@@ -2014,9 +2014,9 @@ pub fn bitcoin_units::block::BlockHeight::try_from(s: alloc::boxed::Box<str>) ->
 pub fn bitcoin_units::block::BlockHeight::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::block::BlockHeightDecoder::default() -> Self
 pub fn bitcoin_units::block::BlockHeightDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
-pub fn bitcoin_units::block::BlockHeightDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::block::BlockHeightDecoder::new() -> Self
 pub fn bitcoin_units::block::BlockHeightDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
+pub fn bitcoin_units::block::BlockHeightDecoder::read_limit(&self) -> usize
 pub fn bitcoin_units::block::BlockHeightDecoderError::clone(&self) -> bitcoin_units::block::BlockHeightDecoderError
 pub fn bitcoin_units::block::BlockHeightDecoderError::eq(&self, other: &bitcoin_units::block::BlockHeightDecoderError) -> bool
 pub fn bitcoin_units::block::BlockHeightDecoderError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
@@ -2164,9 +2164,9 @@ pub fn bitcoin_units::locktime::absolute::LockTime::try_from(s: alloc::boxed::Bo
 pub fn bitcoin_units::locktime::absolute::LockTime::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::default() -> Self
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
-pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::new() -> Self
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
+pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::read_limit(&self) -> usize
 pub fn bitcoin_units::locktime::absolute::LockTimeEncoder::advance(&mut self) -> bool
 pub fn bitcoin_units::locktime::absolute::LockTimeEncoder::current_chunk(&self) -> core::option::Option<&[u8]>
 pub fn bitcoin_units::locktime::absolute::MedianTimePast::arbitrary(u: &mut arbitrary::unstructured::Unstructured<'a>) -> arbitrary::error::Result<Self>
@@ -2430,9 +2430,9 @@ pub fn bitcoin_units::sequence::Sequence::try_from(s: alloc::boxed::Box<str>) ->
 pub fn bitcoin_units::sequence::Sequence::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::sequence::SequenceDecoder::default() -> Self
 pub fn bitcoin_units::sequence::SequenceDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
-pub fn bitcoin_units::sequence::SequenceDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::sequence::SequenceDecoder::new() -> Self
 pub fn bitcoin_units::sequence::SequenceDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
+pub fn bitcoin_units::sequence::SequenceDecoder::read_limit(&self) -> usize
 pub fn bitcoin_units::sequence::SequenceDecoderError::clone(&self) -> bitcoin_units::sequence::SequenceDecoderError
 pub fn bitcoin_units::sequence::SequenceDecoderError::eq(&self, other: &bitcoin_units::sequence::SequenceDecoderError) -> bool
 pub fn bitcoin_units::sequence::SequenceDecoderError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
@@ -2442,9 +2442,9 @@ pub fn bitcoin_units::sequence::SequenceEncoder::advance(&mut self) -> bool
 pub fn bitcoin_units::sequence::SequenceEncoder::current_chunk(&self) -> core::option::Option<&[u8]>
 pub fn bitcoin_units::time::BlockTimeDecoder::default() -> Self
 pub fn bitcoin_units::time::BlockTimeDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
-pub fn bitcoin_units::time::BlockTimeDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::time::BlockTimeDecoder::new() -> Self
 pub fn bitcoin_units::time::BlockTimeDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
+pub fn bitcoin_units::time::BlockTimeDecoder::read_limit(&self) -> usize
 pub fn bitcoin_units::time::BlockTimeDecoderError::clone(&self) -> bitcoin_units::time::BlockTimeDecoderError
 pub fn bitcoin_units::time::BlockTimeDecoderError::eq(&self, other: &bitcoin_units::time::BlockTimeDecoderError) -> bool
 pub fn bitcoin_units::time::BlockTimeDecoderError::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result

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")]