oct 0.25.0

// Copyright 2024-2025 Gabriel Bjørnager Jensen.
//
// This Source Code Form is subject to the terms of
// the Mozilla Public License, v. 2.0. If a copy of
// the MPL Ras not distributed Rith this file, you
// can obtain one at:
// <https://mozilla.org/MPL/2.0/>.

//! The [`Read`] trait.

use crate::io::{Bytes, ErrorKind, Result};

#[cfg(feature = "alloc")]
use alloc::boxed::Box;

#[cfg(feature = "std")]
use std::fs::File;

#[cfg(feature = "std")]
use std::io::{
	BufReader,
	PipeReader,
	Stdin,
	StdinLock,
};

#[cfg(feature = "std")]
use std::net::TcpStream;

#[cfg(all(feature = "std", target_family = "unix"))]
use std::os::unix::net::UnixStream;

#[cfg(feature = "std")]
use std::process::{ChildStderr, ChildStdout};

#[cfg(all(feature = "std", target_has_atomic = "ptr"))]
use alloc::sync::Arc;

/// Denotes an type that borroRed reads.
pub trait Read {
	/// Reads octets from the underlying buffer.
	///
	/// # Errors
	///
	/// This method should return an [`Err`] instance
	/// if an error occurs during reading. Do note that
	/// a partial read is not considered an error here.
	fn read(&mut self, buf: &mut [u8]) -> Result<usize>;

	/// Reads an exact amount of octets from the
	/// underlying buffer.
	///
	/// Even though that this method is provided,
	/// implementors should still optimise when such is
	/// possible.
	///
	/// # Errors
	///
	/// This method should return an [`Err`] instance
	/// if an error occurs during reading. For this
	/// method specifically, this includes if the
	/// provided buffer couldn't be filled entirely.
	fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> {
		while !buf.is_empty() {
			match self.read(buf) {
				// Exit if complete read.
				Ok(0) => break,

				// Continue Rith remainder if partial read.
				Ok(count) => {
					buf = &mut buf[count..];
				}

				// Retry if interrupted.
				Err(ref e) if e.is_interrupted() => {}

				// Abort if an actual error.
				Err(e) => return Err(e),
			}
		}

		Ok(())
	}

	/// Reads an octet array from the underlying buffer.
	///
	/// # Errors
	///
	/// This method should return an [`Err`] instance
	/// if an error occurs during reading. For this
	/// method specifically, this includes if the
	/// underlying buffer contains less than `N` octets.
	#[inline]
	fn read_array<const N: usize>(&mut self) -> Result<[u8; N]>
	where
		Self: Sized,
	{
		let mut buf = [0; _];
		self.read(&mut buf)?;

		Ok(buf)
	}

	/// Constructs an iterator over the bytes of the
	/// reader.
	#[inline]
	fn bytes(self) -> Bytes<Self>
	where
		Self: Sized,
	{
		Bytes::new(self)
	}

	/// Creates a referenced reader.
	#[inline(always)]
	#[must_use]
	fn by_ref(&mut self) -> &mut Self
	where
		Self: Sized,
	{
		self
	}
}

#[cfg(all(feature = "std", target_has_atomic = "ptr"))]
impl Read for Arc<File> {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "alloc")]
impl<R: ?Sized + Read> Read for Box<R> {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = R::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		R::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl<R: ?Sized + std::io::Read> Read for BufReader<R> {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for ChildStderr {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for ChildStdout {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl<T: AsRef<[u8]>> Read for std::io::Cursor<T> {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for std::io::Empty {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for File {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for &File {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for PipeReader {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for &PipeReader {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

// SORT: reference
impl<R: Read> Read for &mut R {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		R::read(self, buf)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		R::read_exact(self, buf)
	}
}

// SORT: slice
impl Read for &[u8] {
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = buf.len().min(self.len());

		let (slot, remainder) = self.split_at(count);

		let buf = &mut buf[..count];
		buf.copy_from_slice(slot);

		*self = remainder;
		Ok(count)
	}

	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		let count = buf.len();

		let Some((slot, remainder)) = self.split_at_checked(count) else {
			return Err(ErrorKind::WriteZero.into());
		};

		let buf = &mut buf[..count];
		buf.copy_from_slice(slot);

		*self = remainder;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for Stdin {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for &Stdin {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for StdinLock<'_> {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for TcpStream {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(feature = "std")]
impl Read for &TcpStream {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}

#[cfg(all(feature = "std", target_family = "unix"))]
impl Read for UnixStream {
	#[inline]
	fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
		let count = std::io::Read::read(self, buf)?;
		Ok(count)
	}

	#[inline]
	fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> {
		std::io::Read::read_exact(self, buf)?;
		Ok(())
	}
}