oct 0.26.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 was not distributed with this file, you
// can obtain one at:
// <https://mozilla.org/MPL/2.0/>.

//! The [`Write`] trait.

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

use core::mem::take;

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

#[cfg(feature = "alloc")]
use alloc::vec::Vec;

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

#[cfg(feature = "std")]
use std::io::{
	BufWriter,
	LineWriter,
	PipeWriter,
	Stderr,
	StderrLock,
	Stdout,
	StdoutLock,
};

#[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::ChildStdin;

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

/// Denotes a type that cen be written to.
pub trait Write {
	/// Writes octets to the underlying buffer.
	///
	/// # Errors
	///
	/// This method should return an [`Err`] instance
	/// if an error occurs during writing. Do note that
	/// a partial write is not considered an error here.
	fn write(&mut self, buf: &[u8]) -> Result<usize>;

	/// Writes octets to the underlying buffer.
	///
	/// Even though that this method is provided,
	/// implementors should still optimise when such is
	/// possible.
	///
	/// # Errors
	///
	/// If the underlying buffer couldn't contain the
	/// entirety of the provided buf, this function
	/// should return an [`Err`] instance.
	fn write_all(&mut self, mut buf: &[u8]) -> Result<()> {
		while !buf.is_empty() {
			match self.write(buf) {
				// Exit if complete read.
				Ok(0) => break,

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

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

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

		Ok(())
	}

	/// Flushes all writes to the buffer.
	///
	/// # Errors
	///
	/// If the cached writes could not be flushed to the
	/// underlying buffer, this function should return
	/// an [`Err`] instance.
	fn flush(&mut self) -> Result<()>;

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

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

#[cfg(feature = "alloc")]
impl<W: ?Sized + Write> Write for Box<W> {
	#[inline]
	fn write(&mut self, buf: &[u8]) -> Result<usize> {
		W::write(self, buf)
	}

	#[inline]
	fn flush(&mut self) -> Result<()> {
		W::flush(self)
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		W::flush(self)
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

		// NOTE: Use `take` so as to overwrite the original
		// lifetime.
		let (slot, remainder) = take(self).split_at_mut(count);

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

		*self = remainder;
		Ok(count)
	}

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

		// NOTE: Use `take` so as to overwrite the original
		// lifetime.
		let Some((slot, remainder)) = take(self).split_at_mut_checked(count) else {
			return Err(ErrorKind::WriteZero.into());
		};

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

		*self = remainder;
		Ok(())
	}

	#[inline(always)]
	fn flush(&mut self) -> Result<()> {
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

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

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

	#[inline]
	fn flush(&mut self) -> Result<()> {
		std::io::Write::flush(self)?;
		Ok(())
	}
}

#[cfg(feature = "alloc")]
impl Write for Vec<u8> {
	#[inline]
	fn write(&mut self, buf: &[u8]) -> Result<usize> {
		self.extend_from_slice(buf);
		Ok(buf.len())
	}

	#[inline(always)]
	fn flush(&mut self) -> Result<()> {
		Ok(())
	}
}