peekable 0.6.1

#![doc = include_str!("../README.md")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(docsrs, allow(unused_attributes))]
#![deny(missing_docs)]

use buffer::Buffer;
use std::{
  io::{IoSliceMut, Read, Result, Write},
  mem,
};

#[doc(hidden)]
#[cfg(feature = "smallvec")]
pub type DefaultBuffer = smallvec::SmallVec<[u8; 64]>;

#[doc(hidden)]
#[cfg(not(feature = "smallvec"))]
pub type DefaultBuffer = Vec<u8>;

/// Chunk size used by `peek_to_end` / `peek_to_string` for growing
/// the peek buffer in unbounded read loops. Applies to both sync and
/// async implementations — the peek buffer itself is now the staging
/// area, so no separate fixed-size staging buffer is needed.
const READ_CHUNK: usize = 1024;

/// Extracts the successful type of a `Poll<T>`.
///
/// This macro bakes in propagation of `Pending` signals by returning early.
#[cfg(any(feature = "tokio", feature = "future"))]
#[macro_export]
macro_rules! ready {
  ($e:expr $(,)?) => {
    match $e {
      ::std::task::Poll::Ready(t) => t,
      ::std::task::Poll::Pending => return ::std::task::Poll::Pending,
    }
  };
}

/// Asynchronous peek I/O
///
/// This crate contains the `AsyncPeek` and `AsyncPeekExt`
/// traits, the asynchronous analogs to
/// `peekable::{Peek, Peekable}`. The primary difference is
/// that these traits integrate with the asynchronous task system.
///
/// All items of this library are only available when the `future` feature of this
/// library is activated, and it is not activated by default.
#[cfg(feature = "future")]
#[cfg_attr(docsrs, doc(cfg(feature = "future")))]
pub mod future;

/// Traits, helpers, and type definitions for asynchronous peekable I/O functionality.
///
/// This module is the asynchronous version of `peekable::{Peek, Peekable}`. Primarily, it
/// defines one trait, [`AsyncPeek`], which is asynchronous
/// version of the [`Peek`] trait.
#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub mod tokio;

/// The generic buffer trait used by the `Peekable` and `AsyncPeekable`.
pub mod buffer;

/// A wrapper around an [`Read`] types to make them support peek related methods.
pub struct Peekable<R, B = DefaultBuffer> {
  /// The inner reader.
  reader: R,
  /// The buffer used to store peeked bytes.
  buffer: B,
  buf_cap: Option<usize>,
}

impl<R, B> Read for Peekable<R, B>
where
  B: buffer::Buffer,
  R: Read,
{
  fn read(&mut self, mut buf: &mut [u8]) -> Result<usize> {
    let this = self;
    let want_peek = buf.len();
    let peek_buf = this.buffer.as_mut_slice();

    // check if the peek buffer has data
    let buffer_len = peek_buf.len();
    if buffer_len > 0 {
      if want_peek < buffer_len {
        buf.copy_from_slice(&peek_buf[..want_peek]);
        this.buffer.consume(..want_peek);
        return Ok(want_peek);
      } else if want_peek == buffer_len {
        buf.copy_from_slice(peek_buf);
        this.buffer.clear();
        return Ok(want_peek);
      } else {
        buf[..buffer_len].copy_from_slice(peek_buf);
        buf = &mut buf[buffer_len..];
        let result = this.reader.read(buf);
        // Always clear: the peek buffer's contents have been
        // delivered to the caller. `Read` contract forbids returning
        // Err after writing bytes, so surface the partial success on
        // inner error; the caller's next read() will delegate to the
        // inner reader and see the persistent error then.
        this.buffer.clear();
        return match result {
          Ok(bytes) => Ok(bytes + buffer_len),
          Err(_) => Ok(buffer_len),
        };
      }
    }

    this.reader.read(buf)
  }
}

impl<W, B> Write for Peekable<W, B>
where
  W: Write,
  B: Buffer,
{
  #[cfg_attr(not(tarpaulin), inline(always))]
  fn write(&mut self, buf: &[u8]) -> Result<usize> {
    self.reader.write(buf)
  }

  #[cfg_attr(not(tarpaulin), inline(always))]
  fn flush(&mut self) -> Result<()> {
    self.reader.flush()
  }
}

impl<R> From<R> for Peekable<R> {
  #[cfg_attr(not(tarpaulin), inline(always))]
  fn from(reader: R) -> Self {
    Peekable::new(reader)
  }
}

impl<R> From<(usize, R)> for Peekable<R> {
  #[cfg_attr(not(tarpaulin), inline(always))]
  fn from((cap, reader): (usize, R)) -> Self {
    Peekable::with_capacity(reader, cap)
  }
}

impl<R> Peekable<R> {
  /// Creates a new peekable wrapper around the given reader.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  ///
  /// let peekable = peekable::Peekable::new(Cursor::new([1, 2, 3, 4]));
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn new(reader: R) -> Self {
    Self::construct(reader, DefaultBuffer::new(), None)
  }

  /// Creates a new peekable wrapper around the given reader with the specified
  /// capacity for the peek buffer.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  ///
  /// let peekable = peekable::Peekable::with_capacity(Cursor::new([0; 1024]), 1024);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn with_capacity(reader: R, capacity: usize) -> Self {
    Self::construct(
      reader,
      DefaultBuffer::with_capacity(capacity),
      Some(capacity),
    )
  }
}

impl<R, B> Peekable<R, B> {
  /// Creates a new peekable wrapper around the given reader.
  /// This method allows you to specify a custom buffer type.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::{io::Cursor, vec::Vec};
  /// use peekable::Peekable;
  ///
  /// let peekable: Peekable<_, Vec<u8>> = Peekable::with_buffer(Cursor::new([1, 2, 3, 4]));
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn with_buffer(reader: R) -> Self
  where
    B: Buffer,
  {
    Self::construct(reader, B::new(), None)
  }

  /// Creates a new peekable wrapper around the given reader with the specified
  /// capacity for the peek buffer, this method allows you to specify a custom buffer type.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::{io::Cursor, vec::Vec};
  /// use peekable::Peekable;
  ///
  /// let peekable: Peekable<_, Vec<u8>>  = Peekable::with_capacity_and_buffer(Cursor::new([0; 1024]), 1024);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn with_capacity_and_buffer(reader: R, capacity: usize) -> Self
  where
    B: Buffer,
  {
    Self::construct(reader, B::with_capacity(capacity), Some(capacity))
  }

  #[cfg_attr(not(tarpaulin), inline(always))]
  fn construct(reader: R, buffer: B, capacity: Option<usize>) -> Self
  where
    B: Buffer,
  {
    Self {
      reader,
      buffer,
      buf_cap: capacity,
    }
  }

  /// Clears the peek buffer.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  /// use peekable::Peekable;
  ///
  /// let mut peekable: Peekable<_> = Peekable::from(Cursor::new([1, 2, 3, 4]));
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2]);
  ///
  /// let consumed = peekable.consume();
  /// assert_eq!(consumed.as_slice(), [1, 2].as_slice());
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [3, 4]);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn consume(&mut self) -> B
  where
    B: Buffer,
  {
    let buf = match self.buf_cap {
      Some(capacity) => B::with_capacity(capacity),
      None => B::new(),
    };
    mem::replace(&mut self.buffer, buf)
  }

  /// Consumes the peek buffer in place so that the peek buffer can be reused and avoid allocating.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  /// use peekable::Peekable;
  ///
  /// let mut peekable: Peekable<_> = Peekable::from(Cursor::new([1, 2, 3, 4]));
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2]);
  ///
  /// peekable.consume_in_place();
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [3, 4]);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn consume_in_place(&mut self)
  where
    B: Buffer,
  {
    self.buffer.clear();
  }

  /// Returns the bytes already be peeked into memory and a mutable reference to the underlying reader.
  ///
  /// **WARNING: If you invoke `AsyncRead` or `AsyncReadExt` methods on the underlying reader, may lead to unexpected read behaviors.**
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  ///
  /// let mut peekable = peekable::Peekable::new(Cursor::new([1, 2, 3, 4]));
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2]);
  ///
  /// let (peeked, reader) = peekable.get_mut();
  /// assert_eq!(peeked, [1, 2]);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn get_mut(&mut self) -> (&[u8], &mut R)
  where
    B: AsRef<[u8]>,
  {
    (self.buffer.as_ref(), &mut self.reader)
  }

  /// Returns the bytes already be peeked into memory and a reference to the underlying reader.
  ///
  /// **WARNING: If you invoke `AsyncRead` or `AsyncReadExt` methods on the underlying reader, may lead to unexpected read behaviors.**
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  ///
  /// let mut peekable = peekable::Peekable::new(Cursor::new([1, 2, 3, 4]));
  ///
  /// let mut output = [0u8; 2];
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2]);
  ///
  /// let (peeked, reader) = peekable.get_ref();
  /// assert_eq!(peeked, [1, 2]);
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn get_ref(&self) -> (&[u8], &R)
  where
    B: AsRef<[u8]>,
  {
    (self.buffer.as_ref(), &self.reader)
  }

  /// Consumes the `AsyncPeekable`, returning the a vec may contain the bytes already be peeked into memory and the wrapped reader.
  ///
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io::Cursor;
  ///
  /// let mut peekable = peekable::Peekable::new(Cursor::new([1, 2, 3, 4]));
  ///
  /// let mut output = [0u8; 2];
  ///
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2]);
  ///
  /// let (peeked, reader) = peekable.into_components();
  ///
  /// assert_eq!(peeked.as_slice(), [1, 2].as_slice());
  /// ```
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub fn into_components(self) -> (B, R) {
    (self.buffer, self.reader)
  }
}

impl<R, B> Peekable<R, B>
where
  B: Buffer,
  R: Read,
{
  /// Pull some bytes from this source into the specified buffer, returning
  /// how many bytes were peeked.
  ///
  /// This function does not provide any guarantees about whether it blocks
  /// waiting for data, but if an object needs to block for a peek and cannot,
  /// it will typically signal this via an [`Err`] return value.
  ///
  /// If the return value of this method is [`Ok(n)`], then implementations must
  /// guarantee that `0 <= n <= buf.len()`. A nonzero `n` value indicates
  /// that the buffer `buf` has been filled in with `n` bytes of data from this
  /// source. If `n` is `0`, then it can indicate one of two scenarios:
  ///
  /// 1. This peeker has reached its "end of file" and will likely no longer
  ///    be able to produce bytes. Note that this does not mean that the
  ///    peeker will *always* no longer be able to produce bytes. As an example,
  ///    on Linux, this method will call the `recv` syscall for a [`TcpStream`],
  ///    where returning zero indicates the connection was shut down correctly. While
  ///    for [`File`], it is possible to reach the end of file and get zero as result,
  ///    but if more data is appended to the file, future calls to `peek` will return
  ///    more data.
  /// 2. The buffer specified was 0 bytes in length.
  ///
  /// It is not an error if the returned value `n` is smaller than the buffer size,
  /// even when the peeker is not at the end of the stream yet.
  /// This may happen for example because fewer bytes are actually available right now
  /// (e. g. being close to end-of-file) or because peek() was interrupted by a signal.
  ///
  /// As this trait is safe to implement, callers in unsafe code cannot rely on
  /// `n <= buf.len()` for safety.
  /// Extra care needs to be taken when `unsafe` functions are used to access the peek bytes.
  /// Callers have to ensure that no unchecked out-of-bounds accesses are possible even if
  /// `n > buf.len()`.
  ///
  /// No guarantees are provided about the contents of `buf` when this
  /// function is called, so implementations cannot rely on any property of the
  /// contents of `buf` being true. It is recommended that *implementations*
  /// only write data to `buf` instead of peeking its contents.
  ///
  /// Correspondingly, however, *callers* of this method in unsafe code must not assume
  /// any guarantees about how the implementation uses `buf`. The trait is safe to implement,
  /// so it is possible that the code that's supposed to write to the buffer might also peek
  /// from it. It is your responsibility to make sure that `buf` is initialized
  /// before calling `peek`. Calling `peek` with an uninitialized `buf` (of the kind one
  /// obtains via [`MaybeUninit<T>`]) is not safe, and can lead to undefined behavior.
  ///
  /// [`MaybeUninit<T>`]: crate::mem::MaybeUninit
  ///
  /// # Errors
  ///
  /// If this function encounters any form of I/O or other error, an error
  /// variant will be returned. If an error is returned then it must be
  /// guaranteed that no bytes were peek.
  ///
  /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the peek
  /// operation should be retried if there is nothing else to do.
  ///
  /// # Examples
  ///
  ///
  /// [`Ok(n)`]: Ok
  /// [`File`]: std::fs::File
  /// [`TcpStream`]: std::net::TcpStream
  ///
  /// ```rust
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// # fn main() -> io::Result<()> {
  ///
  /// let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
  /// let mut output = [0u8; 5];
  ///
  /// let bytes = peekable.peek(&mut output[..3])?;
  ///
  /// // This is only guaranteed to be 4 because `&[u8]` is a synchronous
  /// // reader. In a real system you could get anywhere from 1 to
  /// // `output.len()` bytes in a single read.
  /// assert_eq!(bytes, 3);
  /// assert_eq!(output, [1, 2, 3, 0, 0]);
  ///
  /// // you can peek mutiple times
  ///
  /// let bytes = peekable.peek(&mut output[..])?;
  /// assert_eq!(bytes, 4);
  /// assert_eq!(output, [1, 2, 3, 4, 0]);
  ///
  /// // you can read after peek
  /// let mut output = [0u8; 5];
  /// let bytes = peekable.read(&mut output[..2])?;
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [1, 2, 0, 0, 0]);
  ///
  /// // peek after read
  /// let mut output = [0u8; 5];
  /// let bytes = peekable.peek(&mut output[..])?;
  /// assert_eq!(bytes, 2);
  /// assert_eq!(output, [3, 4, 0, 0, 0]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn peek(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
    let want_peek = buf.len();

    // check if the peek buffer has data
    let buffer_len = self.buffer.len();

    if buffer_len > 0 {
      if want_peek < buffer_len {
        buf.copy_from_slice(&self.buffer.as_slice()[..want_peek]);
        return Ok(want_peek);
      } else if want_peek == buffer_len {
        buf.copy_from_slice(self.buffer.as_slice());
        return Ok(want_peek);
      }
      // Need to top up from the reader.
      self.buffer.resize(want_peek)?;
      // Retry on `Interrupted` per the documented contract.
      let result = loop {
        match self
          .reader
          .read(&mut self.buffer.as_mut_slice()[buffer_len..])
        {
          Ok(n) => break Ok(n),
          Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
          Err(e) => break Err(e),
        }
      };
      return match result {
        Ok(n) => {
          self.buffer.truncate(n + buffer_len);
          buf[..buffer_len + n].copy_from_slice(self.buffer.as_slice());
          Ok(buffer_len + n)
        }
        Err(e) => {
          // Roll back the resize so the peek buffer doesn't carry
          // ghost zero-bytes that a subsequent call would return as
          // "real" peeked data.
          self.buffer.truncate(buffer_len);
          Err(e)
        }
      };
    }

    if want_peek == 0 {
      return Ok(0);
    }

    // Read directly into the peek buffer's tail so the inner reader
    // only advances for bytes that are already recorded for replay —
    // a fallible Buffer can fail on `resize` before we touch the
    // reader, and truncation rolls back on any read error.
    let this = self;
    let old_len = this.buffer.len();
    this.buffer.resize(old_len + want_peek)?;
    loop {
      match this.reader.read(&mut this.buffer.as_mut_slice()[old_len..]) {
        Ok(n) => {
          this.buffer.truncate(old_len + n);
          buf[..n].copy_from_slice(&this.buffer.as_slice()[old_len..old_len + n]);
          return Ok(n);
        }
        Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
        Err(e) => {
          this.buffer.truncate(old_len);
          return Err(e);
        }
      }
    }
  }

  /// Like `peek`, except that it peeks into a slice of buffers.
  ///
  /// Data is copied to fill each buffer in order, with the final buffer
  /// written to possibly being only partially filled. This method must
  /// behave equivalently to a single call to `peek` with concatenated
  /// buffers.
  ///
  /// The default implementation calls `peek` with either the first nonempty
  /// buffer provided, or an empty one if none exists.
  pub fn peek_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize> {
    for b in bufs {
      if !b.is_empty() {
        return self.peek(b);
      }
    }

    self.peek(&mut [])
  }

  /// Peek all bytes until EOF in this source, placing them into `buf`.
  ///
  /// All bytes peek from this source will be appended to the specified buffer
  /// `buf`. This function will continuously call [`peek()`] to append more data to
  /// `buf` until [`peek()`] returns either [`Ok(0)`] or an error of
  /// non-[`ErrorKind::Interrupted`] kind.
  ///
  /// If successful, this function will return the total number of bytes peek.
  ///
  /// # Errors
  ///
  /// If this function encounters an error of the kind
  /// [`ErrorKind::Interrupted`] then the error is ignored and the operation
  /// will continue.
  ///
  /// If any other peek error is encountered then this function immediately
  /// returns. Any bytes which have already been peeked will be appended
  /// to `buf`, matching [`std::io::Read::read_to_end`]'s contract.
  ///
  /// # Examples
  ///
  /// [`peek()`]: Peekable::peek
  /// [`Ok(0)`]: Ok
  ///
  /// ```rust
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// # fn main() -> io::Result<()> {
  /// let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
  /// let mut output = Vec::with_capacity(4);
  ///
  /// let bytes = peekable.peek_to_end(&mut output)?;
  ///
  /// assert_eq!(bytes, 4);
  /// assert_eq!(output, vec![1, 2, 3, 4]);
  ///
  /// // read after peek
  /// let mut output = Vec::with_capacity(4);
  ///
  /// let bytes = peekable.read_to_end(&mut output)?;
  ///
  /// assert_eq!(bytes, 4);
  /// assert_eq!(output, vec![1, 2, 3, 4]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn peek_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
    let this = &mut *self;

    // Copy the existing peek-buffer prefix into the caller's buf up
    // front, then read successive chunks directly into the peek
    // buffer's tail and copy them into `buf` once mirrored. This way
    // the reader only advances for bytes already recorded for replay.
    buf.extend_from_slice(this.buffer.as_slice());

    loop {
      let old_len = this.buffer.len();
      let growth = grow_peek_buffer(&mut this.buffer)?;
      match this
        .reader
        .read(&mut this.buffer.as_mut_slice()[old_len..old_len + growth])
      {
        Ok(0) => {
          this.buffer.truncate(old_len);
          return Ok(this.buffer.len());
        }
        Ok(n) => {
          this.buffer.truncate(old_len + n);
          buf.extend_from_slice(&this.buffer.as_slice()[old_len..old_len + n]);
        }
        Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {
          this.buffer.truncate(old_len);
          continue;
        }
        Err(e) => {
          // Partial bytes from successful prior iterations are already
          // in both the peek buffer and `buf`; leaving them in `buf`
          // matches std `Read::read_to_end`.
          this.buffer.truncate(old_len);
          return Err(e);
        }
      }
    }
  }

  /// Peek all bytes until EOF in this source, appending them to `buf`.
  ///
  /// If successful, this function returns the number of bytes which were peek
  /// and appended to `buf`.
  ///
  /// # Errors
  ///
  /// If the data in this stream is *not* valid UTF-8 then an error is
  /// returned and `buf` is unchanged.
  ///
  /// If an I/O error occurs, any bytes the reader has already produced
  /// remain in the internal peek buffer (accessible via
  /// [`get_ref`](Self::get_ref)). The longest valid-UTF-8 prefix of
  /// those bytes is appended to `buf` before the error is returned.
  /// If the reader errored in the middle of a multi-byte UTF-8
  /// sequence, the bytes up to — but not including — the incomplete
  /// sequence are appended; the incomplete bytes are dropped from
  /// `buf` but remain available in the peek buffer. This is slightly
  /// more permissive than [`std::io::Read::read_to_string`], which
  /// would drop the entire segment; the peek-buffer abstraction lets
  /// us preserve more data without corrupting `String`'s UTF-8
  /// invariant.
  ///
  /// [`peek_to_end`]: Peek::peek_to_end
  ///
  /// # Examples
  ///
  ///
  /// ```rust
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// # fn main() -> io::Result<()> {
  ///
  /// let mut peekable = Cursor::new(&b"1234"[..]).peekable();
  /// let mut buffer = String::with_capacity(4);
  ///
  /// let bytes = peekable.peek_to_string(&mut buffer)?;
  ///
  /// assert_eq!(bytes, 4);
  /// assert_eq!(buffer, String::from("1234"));
  ///
  /// // read after peek
  /// let mut buffer = String::with_capacity(4);
  /// let bytes = peekable.peek_to_string(&mut buffer)?;
  ///
  /// assert_eq!(bytes, 4);
  /// assert_eq!(buffer, String::from("1234"));
  ///
  /// // peek invalid utf-8
  /// let mut peekable = Cursor::new([255; 4]).peekable();
  /// let mut buffer = String::with_capacity(4);
  /// assert!(peekable.peek_to_string(&mut buffer).is_err());
  /// # Ok(())
  /// # }
  /// ```
  pub fn peek_to_string(&mut self, buf: &mut String) -> Result<usize> {
    // Validate the existing peek buffer up front, but only fail fast
    // for definitively invalid UTF-8. An error with `error_len() ==
    // None` means the buffer ends with an incomplete code point (e.g.
    // a prior `peek_exact` split a multi-byte sequence), which may
    // become valid once more bytes are read from the reader.
    if let Err(e) = core::str::from_utf8(self.buffer.as_slice()) {
      if e.error_len().is_some() {
        return Err(invalid_utf8_io_error(e));
      }
    }

    // Read directly into the peek buffer so the reader only advances
    // for bytes that are simultaneously recorded for replay. Accumulate
    // the reader outcome and validate UTF-8 at the end — on I/O error
    // we still want to preserve the longest valid-UTF-8 prefix.
    let loop_result: Result<()> = loop {
      let old_len = self.buffer.len();
      let growth = match grow_peek_buffer(&mut self.buffer) {
        Ok(g) => g,
        Err(e) => break Err(e),
      };
      match self
        .reader
        .read(&mut self.buffer.as_mut_slice()[old_len..old_len + growth])
      {
        Ok(0) => {
          self.buffer.truncate(old_len);
          break Ok(());
        }
        Ok(n) => {
          self.buffer.truncate(old_len + n);
        }
        Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {
          self.buffer.truncate(old_len);
          continue;
        }
        Err(e) => {
          self.buffer.truncate(old_len);
          break Err(e);
        }
      }
    };

    match (loop_result, core::str::from_utf8(self.buffer.as_slice())) {
      (Ok(()), Ok(s)) => {
        buf.push_str(s);
        Ok(self.buffer.len())
      }
      (Ok(()), Err(e)) => Err(invalid_utf8_io_error(e)),
      (Err(io), Ok(s)) => {
        buf.push_str(s);
        Err(io)
      }
      (Err(io), Err(utf8_err)) => {
        // Preserve the longest valid-UTF-8 prefix: bytes before
        // `valid_up_to()` are guaranteed to be a complete valid
        // UTF-8 sequence. The bytes after are either invalid or an
        // incomplete multi-byte sequence — dropped from `buf` but
        // still available in the peek buffer via `get_ref()`.
        let vut = utf8_err.valid_up_to();
        if vut != 0 {
          let s = core::str::from_utf8(&self.buffer.as_slice()[..vut])
            .expect("valid_up_to() must point to a valid UTF-8 prefix");
          buf.push_str(s);
        }
        Err(io)
      }
    }
  }

  /// Peek the exact number of bytes required to fill `buf`.
  ///
  /// This function peeks as many bytes as necessary to completely fill the
  /// specified buffer `buf`.
  ///
  /// No guarantees are provided about the contents of `buf` when this
  /// function is called, so implementations cannot rely on any property of the
  /// contents of `buf` being true. It is recommended that implementations
  /// only write data to `buf` instead of peeking its contents. The
  /// documentation on [`peek`] has a more detailed explanation on this
  /// subject.
  ///
  /// # Errors
  ///
  /// If this function encounters an error of the kind
  /// [`ErrorKind::Interrupted`](std::io::ErrorKind::Interrupted) then the error is ignored and the operation
  /// will continue.
  ///
  /// If this function encounters an "end of file" before completely filling
  /// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`](std::io::ErrorKind::Interrupted).
  /// The contents of `buf` are unspecified in this case.
  ///
  /// If any other peek error is encountered then this function immediately
  /// returns. The contents of `buf` are unspecified in this case.
  ///
  /// If this function returns an error, it is unspecified how many bytes it
  /// has peek, but it will never peek more than would be necessary to
  /// completely fill the buffer.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// # fn main() -> io::Result<()> {
  ///
  /// let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
  /// let mut output = [0u8; 4];
  ///
  /// peekable.peek_exact(&mut output)?;
  ///
  /// assert_eq!(output, [1, 2, 3, 4]);
  ///
  /// // read after peek
  /// let mut output = [0u8; 2];
  ///
  /// peekable.read_exact(&mut output[..])?;
  ///
  /// assert_eq!(output, [1, 2]);
  ///
  /// // peek after read
  /// let mut output = [0u8; 2];
  /// peekable.peek_exact(&mut output)?;
  ///
  /// assert_eq!(output, [3, 4]);
  /// # Ok(())
  /// # }
  /// ```
  ///
  /// ## EOF is hit before `buf` is filled
  ///
  /// ```
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// # fn main() -> io::Result<()> {
  ///
  /// let mut peekable = Cursor::new([1, 2, 3, 4]).peekable();
  /// let mut output = [0u8; 5];
  ///
  /// let result = peekable.peek_exact(&mut output);
  /// assert_eq!(
  ///   result.unwrap_err().kind(),
  ///   std::io::ErrorKind::UnexpectedEof
  /// );
  ///
  /// let result = peekable.peek_exact(&mut output[..4]);
  /// assert!(result.is_ok());
  /// assert_eq!(output, [1, 2, 3, 4, 0]);
  ///
  /// # Ok(())
  /// # }
  /// ```
  pub fn peek_exact(&mut self, buf: &mut [u8]) -> Result<()> {
    let this = self;

    let total = buf.len();
    let peek_buf_len = this.buffer.len();

    if total <= peek_buf_len {
      buf.copy_from_slice(&this.buffer.as_slice()[..total]);
      return Ok(());
    }

    buf[..peek_buf_len].copy_from_slice(this.buffer.as_slice());
    let mut filled = peek_buf_len;

    while filled < total {
      let old_len = this.buffer.len();
      let want = total - filled;
      this.buffer.resize(old_len + want)?;

      let n = loop {
        match this.reader.read(&mut this.buffer.as_mut_slice()[old_len..]) {
          Ok(n) => break n,
          Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
          Err(e) => {
            this.buffer.truncate(old_len);
            return Err(e);
          }
        }
      };
      this.buffer.truncate(old_len + n);
      if n == 0 {
        return Err(std::io::ErrorKind::UnexpectedEof.into());
      }
      buf[filled..filled + n].copy_from_slice(&this.buffer.as_slice()[old_len..old_len + n]);
      filled += n;
    }

    Ok(())
  }

  /// Try to fill the peek buffer with more data. Returns the number of bytes peeked.
  ///
  /// # Examples
  ///
  /// ```rust
  /// use std::io;
  /// use std::io::{Cursor, Read};
  /// use peekable::PeekExt;
  ///
  /// let mut peekable = Cursor::new([1, 2, 3, 4]).peekable_with_capacity(5);
  /// let mut output = [0u8; 4];
  ///
  /// peekable.peek_exact(&mut output[..1]).unwrap();
  /// assert_eq!(output, [1, 0, 0, 0]);
  ///
  /// let bytes = peekable.fill_peek_buf().unwrap();
  /// assert_eq!(bytes, 3);
  ///
  /// let bytes = peekable.peek(&mut output).unwrap();
  /// assert_eq!(output, [1, 2, 3, 4].as_slice());
  /// ````
  pub fn fill_peek_buf(&mut self) -> Result<usize> {
    let cap = self.buffer.capacity();
    let cur = self.buffer.len();
    self.buffer.resize(cap)?;
    // Retry on `Interrupted` and roll back the resize on error so the
    // peek buffer doesn't end up holding ghost zero-bytes.
    let result = loop {
      match self.reader.read(&mut self.buffer.as_mut_slice()[cur..]) {
        Ok(n) => break Ok(n),
        Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
        Err(e) => break Err(e),
      }
    };
    match result {
      Ok(peeked) => {
        self.buffer.truncate(cur + peeked);
        Ok(peeked)
      }
      Err(e) => {
        self.buffer.truncate(cur);
        Err(e)
      }
    }
  }
}

/// An extension trait which adds utility methods to [`Read`] types.
pub trait PeekExt: Read {
  /// Wraps a [`Read`] type in a `Peekable` which provides a `peek` related methods.
  fn peekable(self) -> Peekable<Self>
  where
    Self: Sized,
  {
    Peekable::from(self)
  }

  /// Wraps a [`Read`] type in a `Peekable` which provides a `peek` related methods with a specified capacity.
  fn peekable_with_capacity(self, capacity: usize) -> Peekable<Self>
  where
    Self: Sized,
  {
    Peekable::from((capacity, self))
  }

  /// Creates a new `Peekable` which will wrap the given reader.
  ///
  /// This method allows you to specify a custom buffer type.
  fn peekable_with_buffer<B>(self) -> Peekable<Self, B>
  where
    Self: Sized,
    B: Buffer,
  {
    Peekable::with_buffer(self)
  }

  /// Wraps a [`Read`] type in a `Peekable` which provides a `peek` related methods with a specified capacity.
  ///
  /// This method allows you to specify a custom buffer type.
  fn peekable_with_capacity_and_buffer<B>(self, capacity: usize) -> Peekable<Self, B>
  where
    Self: Sized,
    B: Buffer,
  {
    Peekable::with_capacity_and_buffer(self, capacity)
  }
}

impl<R: Read + ?Sized> PeekExt for R {}

#[cfg_attr(not(tarpaulin), inline(always))]
fn invalid_utf8_io_error(e: core::str::Utf8Error) -> std::io::Error {
  std::io::Error::new(std::io::ErrorKind::InvalidData, e)
}

/// Grow the peek buffer by up to `READ_CHUNK` bytes, halving the
/// requested growth on each [`Buffer::resize`] failure down to 1.
/// Returns the growth that actually succeeded, or the last error
/// if no growth by ≥ 1 byte is possible.
///
/// Used by the unbounded-size `peek_to_end` / `peek_to_string` paths
/// so they work with small-capacity fallible `Buffer` implementations
/// when the remaining stream fits. A bounded `Buffer` whose capacity
/// is strictly greater than the final stream size will succeed; the
/// pathological case — capacity exactly equal to stream size — still
/// fails, because detecting EOF requires reading one more byte.
#[cfg_attr(not(tarpaulin), inline)]
pub(crate) fn grow_peek_buffer<B: Buffer>(buffer: &mut B) -> std::io::Result<usize> {
  let old_len = buffer.len();
  let mut growth = READ_CHUNK;
  loop {
    match buffer.resize(old_len + growth) {
      Ok(()) => return Ok(growth),
      Err(_) if growth > 1 => growth /= 2,
      Err(e) => return Err(e),
    }
  }
}

#[cfg(test)]
mod tests {
  use super::*;
  use std::io::Cursor;

  #[test]
  fn test_peek_exact_peek_exact_read_exact() {
    let mut peekable = Cursor::new([1, 2, 3, 4, 5, 6, 7, 8, 9]).peekable();
    let mut buf1 = [0; 2];
    peekable.peek_exact(&mut buf1).unwrap();
    assert_eq!(buf1, [1, 2]);

    let mut buf2 = [0; 4];
    peekable.peek_exact(&mut buf2).unwrap();
    assert_eq!(buf2, [1, 2, 3, 4]);

    let mut buf3 = [0; 4];
    peekable.read_exact(&mut buf3).unwrap();
    assert_eq!(buf3, [1, 2, 3, 4]);
  }

  #[test]
  fn test_peek_exact_peek_exact_read_exact_2() {
    let mut peekable = Cursor::new([1, 2, 3, 4, 5, 6, 7, 8, 9]).peekable_with_buffer::<Vec<u8>>();
    let mut buf1 = [0; 2];
    peekable.peek_exact(&mut buf1).unwrap();
    assert_eq!(buf1, [1, 2]);

    let mut buf2 = [0; 4];
    peekable.peek_exact(&mut buf2).unwrap();
    assert_eq!(buf2, [1, 2, 3, 4]);

    let mut buf3 = [0; 4];
    peekable.read_exact(&mut buf3).unwrap();
    assert_eq!(buf3, [1, 2, 3, 4]);
  }

  #[test]
  fn test_peek_exact_peek_exact_read_exact_3() {
    let mut peekable =
      Cursor::new([1, 2, 3, 4, 5, 6, 7, 8, 9]).peekable_with_capacity_and_buffer::<Vec<u8>>(24);
    let mut buf1 = [0; 2];
    peekable.peek_exact(&mut buf1).unwrap();
    assert_eq!(buf1, [1, 2]);

    let mut buf2 = [0; 4];
    peekable.peek_exact(&mut buf2).unwrap();
    assert_eq!(buf2, [1, 2, 3, 4]);

    let mut buf3 = [0; 4];
    peekable.read_exact(&mut buf3).unwrap();
    assert_eq!(buf3, [1, 2, 3, 4]);
  }
}