qubit_io/std_io/ext/

read_ext.rs

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Extension operations for standard byte readers.

use std::io::Read;
use std::io::Result;
use std::io::Write;
use std::io::copy as copy_all;

use crate::Streams;
use crate::std_io::ext::internal::read_ext_impl;
use crate::util::UncheckedSlice;

/// Extension methods for [`Read`] values.
///
/// `ReadExt` fills small semantic gaps in the standard [`Read`] trait while
/// keeping the same blocking and error model. The methods are implemented for
/// every type that implements [`Read`], including `dyn Read` trait objects.
///
/// # Examples
/// ```
/// use qubit_io::std_io::ext::ReadExt;
/// use std::io::Cursor;
///
/// let mut input = Cursor::new(b"abcdef".to_vec());
/// let header = input.read_exact_array::<2>()?;
/// let payload = input.read_exact_vec_limited(4, 16)?;
///
/// assert_eq!(*b"ab", header);
/// assert_eq!(b"cdef", payload.as_slice());
/// # Ok::<(), std::io::Error>(())
/// ```
pub trait ReadExt: Read {
    /// Reads bytes into a range of `buffer` without checking the range bounds
    /// in release builds.
    ///
    /// This method delegates to [`Read::read`] after creating the target slice
    /// with raw pointer arithmetic. It performs at most one read operation and
    /// returns the number of bytes read, keeping the same short-read and error
    /// behavior as [`Read::read`].
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Maximum number of bytes to read.
    ///
    /// # Returns
    /// The number of bytes written into `buffer[start_index..start_index +
    /// count]`. The value is in `0..=count`.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read`].
    ///
    /// # Panics
    /// Panics in debug builds if the requested destination range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is a
    /// valid range within `buffer` and that `start_index + count` does not
    /// overflow `usize`.
    unsafe fn read_unchecked(&mut self, buffer: &mut [u8], start_index: usize, count: usize) -> Result<usize>;

    /// Reads exactly `count` bytes into a range of `buffer` without checking
    /// the range bounds in release builds.
    ///
    /// This method delegates to [`Read::read_exact`] after creating the target
    /// slice with raw pointer arithmetic. It keeps the same blocking and error
    /// behavior as [`Read::read_exact`].
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Number of bytes to read.
    ///
    /// # Returns
    /// `Ok(())` after the requested range has been filled.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read_exact`], including
    /// [`std::io::ErrorKind::UnexpectedEof`] when EOF is reached before `count`
    /// bytes are read.
    ///
    /// # Panics
    /// Panics in debug builds if the requested destination range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is a
    /// valid range within `buffer` and that `start_index + count` does not
    /// overflow `usize`.
    unsafe fn read_exact_unchecked(&mut self, buffer: &mut [u8], start_index: usize, count: usize) -> Result<()>;

    /// Reads bytes into a range of `buffer` until that range is full or EOF is
    /// reached, without checking the range bounds in release builds.
    ///
    /// This method has the same EOF and retry behavior as
    /// [`ReadExt::read_exact_or_eof`], but writes into
    /// `buffer[start_index..start_index + count]` using raw pointer
    /// arithmetic.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Number of bytes to try to read.
    ///
    /// # Returns
    /// The number of bytes written into `buffer[start_index..start_index +
    /// count]`. The value is in `0..=count`.
    ///
    /// # Errors
    /// Returns the first non-[`std::io::ErrorKind::Interrupted`] error reported
    /// by the underlying reader. Interrupted reads are retried. Returns
    /// [`std::io::ErrorKind::InvalidData`] if the reader reports more bytes
    /// than requested.
    ///
    /// # Panics
    /// Panics in debug builds if the requested destination range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is a
    /// valid range within `buffer` and that `start_index + count` does not
    /// overflow `usize`.
    unsafe fn read_exact_or_eof_unchecked(
        &mut self,
        buffer: &mut [u8],
        start_index: usize,
        count: usize,
    ) -> Result<usize>;

    /// Reads bytes until `buffer` is full or EOF is reached.
    ///
    /// This method differs from [`Read::read_exact`] by treating EOF as a
    /// successful partial result. It keeps retrying short reads until the
    /// caller-provided buffer is full, EOF is reached, or a non-interrupted
    /// I/O error occurs.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer to fill.
    ///
    /// # Returns
    /// The number of bytes written into `buffer`. The value is in
    /// `0..=buffer.len()`.
    ///
    /// # Errors
    /// Returns the first non-[`std::io::ErrorKind::Interrupted`] error reported
    /// by the underlying reader. Interrupted reads are retried. Returns
    /// [`std::io::ErrorKind::InvalidData`] if the reader reports more bytes
    /// than requested.
    fn read_exact_or_eof(&mut self, buffer: &mut [u8]) -> Result<usize>;

    /// Reads exactly `N` bytes into a stack-allocated array.
    ///
    /// This method uses [`Read::read_exact`] and therefore requires the reader
    /// to provide exactly `N` bytes before EOF.
    ///
    /// # Type Parameters
    /// - `N`: Number of bytes in the returned array.
    ///
    /// # Returns
    /// An array containing exactly `N` bytes read from this reader.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read_exact`], including
    /// [`std::io::ErrorKind::UnexpectedEof`] when EOF is reached before the
    /// array is full.
    fn read_exact_array<const N: usize>(&mut self) -> Result<[u8; N]>;

    /// Reads exactly `len` bytes into a new vector after checking a limit.
    ///
    /// If `len` is greater than `max_len`, this method returns
    /// [`std::io::ErrorKind::InvalidData`] before reading any bytes.
    ///
    /// # Parameters
    /// - `len`: Exact number of bytes to read.
    /// - `max_len`: Maximum accepted exact read length.
    ///
    /// # Returns
    /// A vector containing exactly `len` bytes.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when `len > max_len`.
    /// Returns the [`std::io::ErrorKind::OutOfMemory`] error when the
    /// result vector cannot be allocated. Returns the error reported by
    /// [`Read::read_exact`], including
    /// [`std::io::ErrorKind::UnexpectedEof`] when EOF is reached before `len`
    /// bytes are read.
    fn read_exact_vec_limited(&mut self, len: usize, max_len: usize) -> Result<Vec<u8>>;

    /// Reads exactly `len` bytes and appends them to `output`.
    ///
    /// If `len` is greater than `max_len`, this method returns
    /// [`std::io::ErrorKind::InvalidData`] before reading any bytes and leaves
    /// `output` unchanged. On a read error, `output` is truncated back to
    /// its original length. The underlying reader may still have consumed
    /// bytes before the error because [`Read`] does not provide rollback.
    ///
    /// # Parameters
    /// - `output`: Destination vector to append to.
    /// - `len`: Exact number of bytes to read.
    /// - `max_len`: Maximum accepted exact read length.
    ///
    /// # Returns
    /// `Ok(())` after exactly `len` bytes have been appended to `output`.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when `len > max_len`,
    /// [`std::io::ErrorKind::InvalidInput`] when `output.len() + len`
    /// overflows, or [`std::io::ErrorKind::OutOfMemory`] when `output`
    /// cannot reserve the appended bytes. Returns the error reported by
    /// [`Read::read_exact`], including
    /// [`std::io::ErrorKind::UnexpectedEof`] when EOF is reached before `len`
    /// bytes are read.
    fn read_exact_vec_limited_into(&mut self, output: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()>;

    /// Discards up to `bytes` bytes from this reader.
    ///
    /// The method repeatedly reads into an internal stack buffer until the
    /// requested number of bytes has been consumed or EOF is reached. It does
    /// not allocate and does not require seeking support.
    ///
    /// # Parameters
    /// - `bytes`: Maximum number of bytes to discard.
    ///
    /// # Returns
    /// The number of bytes actually discarded. The value may be smaller than
    /// `bytes` when EOF is reached first.
    ///
    /// # Errors
    /// Returns the first non-[`std::io::ErrorKind::Interrupted`] error reported
    /// by the underlying reader. Interrupted reads are retried. Returns
    /// [`std::io::ErrorKind::InvalidData`] if the reader reports more bytes
    /// than requested.
    fn discard_exact_or_eof(&mut self, bytes: u64) -> Result<u64>;

    /// Copies all remaining bytes from this reader into `writer`.
    ///
    /// This method is a method-style wrapper around [`std::io::copy`]. It
    /// copies from the current reader position until EOF and does not close or
    /// flush either stream.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    ///
    /// # Returns
    /// The number of bytes copied.
    ///
    /// # Errors
    /// Returns the first read or write error reported by the underlying
    /// streams, using the same error behavior as [`std::io::copy`].
    fn copy_to(&mut self, writer: &mut dyn Write) -> Result<u64>;

    /// Copies at most `max_bytes` bytes from this reader into `writer`.
    ///
    /// This method stops successfully when either EOF is reached or
    /// `max_bytes` bytes have been copied. It does not close or flush either
    /// stream.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    /// - `max_bytes`: Maximum number of bytes to copy.
    ///
    /// # Returns
    /// The number of bytes copied.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the temporary copy buffer
    /// cannot be allocated. Returns the first
    /// non-[`std::io::ErrorKind::Interrupted`] read error or write error
    /// reported by the underlying streams. Interrupted reads are retried.
    fn copy_to_at_most(&mut self, writer: &mut dyn Write, max_bytes: u64) -> Result<u64>;

    /// Copies the remaining input if its total length is at most `max_bytes`.
    ///
    /// This method copies from the current reader position until EOF. If EOF is
    /// not reached within `max_bytes` bytes, it returns
    /// [`std::io::ErrorKind::InvalidData`]. Detecting oversized input consumes
    /// one excess byte from this reader; that excess byte is not written to
    /// `writer`.
    ///
    /// Unlike bounded reads into in-memory collections, this method cannot roll
    /// back bytes already accepted by `writer` when the limit is exceeded
    /// because [`Write`] does not provide truncation. On
    /// [`std::io::ErrorKind::InvalidData`], up to `max_bytes` bytes may remain
    /// in `writer`.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    /// - `max_bytes`: Maximum accepted number of bytes in the remaining input.
    ///
    /// # Returns
    /// The number of bytes copied when EOF is reached within the limit.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when the remaining input is
    /// longer than `max_bytes`. Returns [`std::io::ErrorKind::OutOfMemory`]
    /// if the temporary copy buffer cannot be allocated. Returns the first
    /// non-[`std::io::ErrorKind::Interrupted`] read error or write error
    /// reported by the underlying streams. Interrupted reads are retried.
    fn copy_to_end_limited(&mut self, writer: &mut dyn Write, max_bytes: u64) -> Result<u64>;

    /// Reads the remaining bytes into a vector with a maximum accepted length.
    ///
    /// This method consumes bytes from the current reader position until EOF is
    /// reached. If the stream contains more than `max_len` bytes, it returns
    /// [`std::io::ErrorKind::InvalidData`] after detecting the first excess
    /// byte. No vector is returned on failure.
    ///
    /// # Parameters
    /// - `max_len`: Maximum number of bytes accepted in the returned vector.
    ///
    /// # Returns
    /// A vector containing all remaining bytes when the stream length is within
    /// the limit.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when the stream contains
    /// more than `max_len` bytes. Returns
    /// [`std::io::ErrorKind::OutOfMemory`] when the result vector cannot
    /// grow. Returns the first non-[`std::io::ErrorKind::Interrupted`]
    /// error reported by the underlying reader; interrupted reads are
    /// retried. Returns [`std::io::ErrorKind::InvalidData`] if the reader
    /// reports more bytes than requested.
    fn read_to_end_limited(&mut self, max_len: usize) -> Result<Vec<u8>>;

    /// Reads the remaining bytes into `output` with a maximum accepted length.
    ///
    /// This method appends at most `max_len` bytes from the current reader
    /// position to `output`. If the stream contains more than `max_len` bytes,
    /// it returns [`std::io::ErrorKind::InvalidData`] after detecting the first
    /// excess byte and truncates `output` back to its original length. The
    /// underlying reader may still have consumed bytes before the error
    /// because [`Read`] does not provide rollback.
    ///
    /// # Parameters
    /// - `output`: Destination vector to append to.
    /// - `max_len`: Maximum number of bytes accepted from this reader.
    ///
    /// # Returns
    /// The number of bytes appended to `output`.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when the stream contains
    /// more than `max_len` bytes. Returns
    /// [`std::io::ErrorKind::OutOfMemory`] when `output` cannot
    /// grow. Returns the first non-[`std::io::ErrorKind::Interrupted`] error
    /// reported by the underlying reader; interrupted reads are retried.
    /// Returns [`std::io::ErrorKind::InvalidData`] if the reader reports
    /// more bytes than requested.
    fn read_to_end_limited_into(&mut self, output: &mut Vec<u8>, max_len: usize) -> Result<usize>;

    /// Reads the remaining bytes as UTF-8 text with a maximum accepted length.
    ///
    /// This method has the same size limit and read semantics as
    /// [`ReadExt::read_to_end_limited`], then validates the collected bytes as
    /// UTF-8.
    ///
    /// # Parameters
    /// - `max_len`: Maximum number of bytes accepted before UTF-8 decoding.
    ///
    /// # Returns
    /// The decoded UTF-8 string.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when the stream contains
    /// more than `max_len` bytes or when the collected bytes are not valid
    /// UTF-8. Returns [`std::io::ErrorKind::OutOfMemory`] when the result
    /// buffer cannot grow. Returns
    /// the first non-[`std::io::ErrorKind::Interrupted`] error reported by the
    /// underlying reader; interrupted reads are retried.
    fn read_to_string_limited(&mut self, max_len: usize) -> Result<String>;

    /// Reads the remaining bytes as UTF-8 text and appends to `output`.
    ///
    /// This method accepts at most `max_len` bytes from the current reader
    /// position, validates them as UTF-8, and appends the decoded text to
    /// `output`. If the input is oversized or invalid UTF-8, `output` is
    /// truncated back to its original length. Oversized input may still consume
    /// up to `max_len + 1` bytes from the reader while detecting the limit
    /// violation.
    ///
    /// # Parameters
    /// - `output`: Destination string to append to.
    /// - `max_len`: Maximum number of bytes accepted before UTF-8 decoding.
    ///
    /// # Returns
    /// The number of bytes appended to `output`.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::InvalidData`] when the stream contains
    /// more than `max_len` bytes or when the collected bytes are not valid
    /// UTF-8. Returns [`std::io::ErrorKind::OutOfMemory`] when the
    /// temporary byte buffer or `output` cannot grow. Returns the first
    /// non-[`std::io::ErrorKind::Interrupted`] error reported by the
    /// underlying reader; interrupted reads are retried.
    fn read_to_string_limited_into(&mut self, output: &mut String, max_len: usize) -> Result<usize>;
}

impl<T> ReadExt for T
where
    T: Read + ?Sized,
{
    /// Reads bytes from an unchecked range into a standard [`Read`] value.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Maximum number of bytes to read.
    ///
    /// # Returns
    /// The number of bytes read into the requested range.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read`].
    ///
    /// # Panics
    /// Panics in debug builds if the requested output range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is
    /// valid inside `buffer` and that the addition does not overflow.
    #[inline(always)]
    unsafe fn read_unchecked(&mut self, buffer: &mut [u8], start_index: usize, count: usize) -> Result<usize> {
        // SAFETY: The caller guarantees that the requested range is valid for
        // `buffer`.
        let target = unsafe { UncheckedSlice::subslice_mut(buffer, start_index, count) };
        self.read(target)
    }

    /// Reads an unchecked range until it is full or EOF is reached.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Number of bytes to try to read.
    ///
    /// # Returns
    /// The number of bytes read into the requested range.
    ///
    /// # Errors
    /// Returns the first non-interrupted read error, or
    /// [`std::io::ErrorKind::InvalidData`] if the reader reports more bytes
    /// than requested.
    ///
    /// # Panics
    /// Panics in debug builds if the requested output range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is
    /// valid inside `buffer` and that the addition does not overflow.
    #[inline(always)]
    unsafe fn read_exact_or_eof_unchecked(
        &mut self,
        buffer: &mut [u8],
        start_index: usize,
        count: usize,
    ) -> Result<usize> {
        let mut reader = self;
        // SAFETY: Forwarded from the trait caller.
        unsafe { read_ext_impl::read_exact_or_eof_unchecked_impl(&mut reader, buffer, start_index, count) }
    }

    /// Reads exactly the requested unchecked range.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    /// - `start_index`: Start offset inside `buffer`.
    /// - `count`: Number of bytes to read.
    ///
    /// # Returns
    /// `Ok(())` after the requested range has been filled.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read_exact`].
    ///
    /// # Panics
    /// Panics in debug builds if the requested output range does not fit.
    ///
    /// # Safety
    /// The caller must guarantee that `start_index..start_index + count` is
    /// valid inside `buffer` and that the addition does not overflow.
    #[inline(always)]
    unsafe fn read_exact_unchecked(&mut self, buffer: &mut [u8], start_index: usize, count: usize) -> Result<()> {
        // SAFETY: The caller guarantees that the requested range is valid for
        // `buffer`.
        let target = unsafe { UncheckedSlice::subslice_mut(buffer, start_index, count) };
        self.read_exact(target)
    }

    /// Reads the destination until it is full or EOF is reached.
    ///
    /// # Parameters
    /// - `buffer`: Destination buffer.
    ///
    /// # Returns
    /// The number of bytes read into `buffer`.
    ///
    /// # Errors
    /// Returns the first non-interrupted read error, or
    /// [`std::io::ErrorKind::InvalidData`] if the reader reports more bytes
    /// than requested.
    #[inline(always)]
    fn read_exact_or_eof(&mut self, buffer: &mut [u8]) -> Result<usize> {
        let mut reader = self;
        read_ext_impl::read_exact_or_eof(&mut reader, buffer)
    }

    /// Reads exactly `N` bytes into an array.
    ///
    /// # Type Parameters
    /// - `N`: Number of bytes in the returned array.
    ///
    /// # Returns
    /// An array containing exactly `N` bytes.
    ///
    /// # Errors
    /// Returns the error reported by [`Read::read_exact`].
    #[inline(always)]
    fn read_exact_array<const N: usize>(&mut self) -> Result<[u8; N]> {
        let mut reader = self;
        read_ext_impl::read_exact_array_impl(&mut reader)
    }

    /// Reads an exactly sized vector within a configured limit.
    ///
    /// # Parameters
    /// - `len`: Exact number of bytes to read.
    /// - `max_len`: Maximum accepted exact read length.
    ///
    /// # Returns
    /// A vector containing exactly `len` bytes.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the result vector cannot
    /// be allocated, a read error, or [`std::io::ErrorKind::InvalidData`]
    /// when `len > max_len`.
    #[inline(always)]
    fn read_exact_vec_limited(&mut self, len: usize, max_len: usize) -> Result<Vec<u8>> {
        let mut reader = self;
        read_ext_impl::read_exact_vec_limited_impl(&mut reader, len, max_len)
    }

    /// Reads exactly `len` bytes and appends them to a vector.
    ///
    /// # Parameters
    /// - `output`: Destination vector.
    /// - `len`: Exact number of bytes to read.
    /// - `max_len`: Maximum accepted exact read length.
    ///
    /// # Returns
    /// `Ok(())` after exactly `len` bytes have been appended.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if `output` cannot grow, a
    /// read error, [`std::io::ErrorKind::InvalidData`] when `len >
    /// max_len`, or [`std::io::ErrorKind::InvalidInput`] when `output.len()
    /// + len` overflows.
    #[inline(always)]
    fn read_exact_vec_limited_into(&mut self, output: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()> {
        let mut reader = self;
        read_ext_impl::read_exact_vec_limited_into(&mut reader, output, len, max_len)
    }

    /// Discards at most the requested number of bytes.
    ///
    /// # Parameters
    /// - `bytes`: Maximum number of bytes to discard.
    ///
    /// # Returns
    /// The number of bytes discarded before the limit or EOF was reached.
    ///
    /// # Errors
    /// Returns the first non-interrupted read error.
    #[inline(always)]
    fn discard_exact_or_eof(&mut self, bytes: u64) -> Result<u64> {
        let mut reader = self;
        read_ext_impl::discard_exact_or_eof_impl(&mut reader, bytes)
    }

    /// Copies all remaining bytes to a writer.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    ///
    /// # Returns
    /// The number of bytes copied.
    ///
    /// # Errors
    /// Returns the first read or write error.
    #[inline(always)]
    fn copy_to(&mut self, writer: &mut dyn Write) -> Result<u64> {
        copy_all(self, writer)
    }

    /// Copies at most the requested number of bytes to a writer.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    /// - `max_bytes`: Maximum number of bytes to copy.
    ///
    /// # Returns
    /// The number of bytes copied.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the temporary copy buffer
    /// cannot be allocated, or the first non-interrupted read error or
    /// write error. Returns [`std::io::ErrorKind::InvalidData`] if the
    /// reader reports more bytes than requested. Bytes from that invalid
    /// read are not written; previously copied bytes are not rolled back.
    #[inline(always)]
    fn copy_to_at_most(&mut self, writer: &mut dyn Write, max_bytes: u64) -> Result<u64> {
        let mut reader = self;
        Streams::copy_at_most(&mut reader, writer, max_bytes)
    }

    /// Copies the remaining input when it fits within a configured limit.
    ///
    /// # Parameters
    /// - `writer`: Destination writer.
    /// - `max_bytes`: Maximum accepted remaining byte count.
    ///
    /// # Returns
    /// The number of bytes copied.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the temporary copy buffer
    /// cannot be allocated, a read or write error, or
    /// [`std::io::ErrorKind::InvalidData`] when the remaining input exceeds
    /// `max_bytes` or the reader reports more bytes than requested. Bytes
    /// from an invalid read are not written; previously copied bytes are
    /// not rolled back.
    #[inline(always)]
    fn copy_to_end_limited(&mut self, writer: &mut dyn Write, max_bytes: u64) -> Result<u64> {
        let mut reader = self;
        Streams::copy_to_end_limited(&mut reader, writer, max_bytes)
    }

    /// Reads the remaining bytes into a bounded vector.
    ///
    /// # Parameters
    /// - `max_len`: Maximum accepted remaining byte count.
    ///
    /// # Returns
    /// A vector containing all remaining bytes.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the result vector cannot
    /// grow, a read error, or [`std::io::ErrorKind::InvalidData`] when the
    /// remaining input exceeds `max_len` or the reader reports more bytes
    /// than requested.
    #[inline(always)]
    fn read_to_end_limited(&mut self, max_len: usize) -> Result<Vec<u8>> {
        let mut reader = self;
        read_ext_impl::read_to_end_limited(&mut reader, max_len)
    }

    /// Appends the remaining bytes to a bounded vector.
    ///
    /// # Parameters
    /// - `output`: Destination vector.
    /// - `max_len`: Maximum accepted remaining byte count.
    ///
    /// # Returns
    /// The number of bytes appended to `output`.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if `output` cannot grow, a
    /// read error, or [`std::io::ErrorKind::InvalidData`] when the
    /// remaining input exceeds `max_len` or the reader reports more bytes
    /// than requested.
    #[inline(always)]
    fn read_to_end_limited_into(&mut self, output: &mut Vec<u8>, max_len: usize) -> Result<usize> {
        let mut reader = self;
        read_ext_impl::read_to_end_limited_into(&mut reader, output, max_len)
    }

    /// Reads the remaining bytes as bounded UTF-8 text.
    ///
    /// # Parameters
    /// - `max_len`: Maximum accepted remaining byte count.
    ///
    /// # Returns
    /// The decoded UTF-8 string.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the result buffer cannot
    /// grow, a read error, or [`std::io::ErrorKind::InvalidData`] when the
    /// input exceeds `max_len` or is not valid UTF-8.
    #[inline(always)]
    fn read_to_string_limited(&mut self, max_len: usize) -> Result<String> {
        let mut reader = self;
        read_ext_impl::read_to_string_limited_impl(&mut reader, max_len)
    }

    /// Appends the remaining bounded UTF-8 text to a string.
    ///
    /// # Parameters
    /// - `output`: Destination string.
    /// - `max_len`: Maximum accepted remaining byte count.
    ///
    /// # Returns
    /// The number of bytes appended to `output`.
    ///
    /// # Errors
    /// Returns [`std::io::ErrorKind::OutOfMemory`] if the temporary byte buffer
    /// or `output` cannot grow, a read error, or
    /// [`std::io::ErrorKind::InvalidData`] when the input exceeds `max_len`
    /// or is not valid UTF-8.
    #[inline(always)]
    fn read_to_string_limited_into(&mut self, output: &mut String, max_len: usize) -> Result<usize> {
        let mut reader = self;
        read_ext_impl::read_to_string_limited_into_impl(&mut reader, output, max_len)
    }
}