//! Blocking IO traits use core::fmt; /// Error returned by [`Read::read_exact`] #[derive(Debug, Copy, Clone, Eq, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum ReadExactError { /// An EOF error was encountered before reading the exact amount of requested bytes. UnexpectedEof, /// Error returned by the inner Read. Other(E), } impl fmt::Display for ReadExactError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{:?}", self) } } #[cfg(feature = "std")] impl std::error::Error for ReadExactError {} /// Error returned by [`Write::write_fmt`] #[derive(Debug, Copy, Clone, Eq, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum WriteFmtError { /// An error was encountered while formatting. FmtError, /// Error returned by the inner Write. Other(E), } impl fmt::Display for WriteFmtError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{:?}", self) } } #[cfg(feature = "std")] impl std::error::Error for WriteFmtError {} /// Blocking reader. /// /// Semantics are the same as [`std::io::Read`], check its documentation for details. pub trait Read: crate::Io { /// Pull some bytes from this source into the specified buffer, returning how many bytes were read. fn read(&mut self, buf: &mut [u8]) -> Result; /// Read the exact number of bytes required to fill `buf`. fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<(), ReadExactError> { while !buf.is_empty() { match self.read(buf) { Ok(0) => break, Ok(n) => buf = &mut buf[n..], Err(e) => return Err(ReadExactError::Other(e)), } } if !buf.is_empty() { Err(ReadExactError::UnexpectedEof) } else { Ok(()) } } } /// Blocking buffered reader. /// /// Semantics are the same as [`std::io::BufRead`], check its documentation for details. pub trait BufRead: crate::Io { /// Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty. fn fill_buf(&mut self) -> Result<&[u8], Self::Error>; /// Tell this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `fill_buf`. fn consume(&mut self, amt: usize); } /// Blocking writer. /// /// Semantics are the same as [`std::io::Write`], check its documentation for details. pub trait Write: crate::Io { /// Write a buffer into this writer, returning how many bytes were written. fn write(&mut self, buf: &[u8]) -> Result; /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination. fn flush(&mut self) -> Result<(), Self::Error>; /// Write an entire buffer into this writer. fn write_all(&mut self, mut buf: &[u8]) -> Result<(), Self::Error> { while !buf.is_empty() { match self.write(buf) { Ok(0) => panic!("zero-length write."), Ok(n) => buf = &buf[n..], Err(e) => return Err(e), } } Ok(()) } /// Write a formatted string into this writer, returning any error encountered. fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<(), WriteFmtError> { // Create a shim which translates a Write to a fmt::Write and saves // off I/O errors. instead of discarding them struct Adapter<'a, T: Write + ?Sized + 'a> { inner: &'a mut T, error: Result<(), T::Error>, } impl fmt::Write for Adapter<'_, T> { fn write_str(&mut self, s: &str) -> fmt::Result { match self.inner.write_all(s.as_bytes()) { Ok(()) => Ok(()), Err(e) => { self.error = Err(e); Err(fmt::Error) } } } } let mut output = Adapter { inner: self, error: Ok(()), }; match fmt::write(&mut output, fmt) { Ok(()) => Ok(()), Err(..) => match output.error { // check if the error came from the underlying `Write` or not Err(e) => Err(WriteFmtError::Other(e)), Ok(()) => Err(WriteFmtError::FmtError), }, } } } /// Blocking seek within streams. /// /// Semantics are the same as [`std::io::Seek`], check its documentation for details. pub trait Seek: crate::Io { /// Seek to an offset, in bytes, in a stream. fn seek(&mut self, pos: crate::SeekFrom) -> Result; /// Rewind to the beginning of a stream. fn rewind(&mut self) -> Result<(), Self::Error> { self.seek(crate::SeekFrom::Start(0))?; Ok(()) } /// Returns the current seek position from the start of the stream. fn stream_position(&mut self) -> Result { self.seek(crate::SeekFrom::Current(0)) } } impl Read for &mut T { #[inline] fn read(&mut self, buf: &mut [u8]) -> Result { T::read(self, buf) } } impl BufRead for &mut T { fn fill_buf(&mut self) -> Result<&[u8], Self::Error> { T::fill_buf(self) } fn consume(&mut self, amt: usize) { T::consume(self, amt) } } impl Write for &mut T { #[inline] fn write(&mut self, buf: &[u8]) -> Result { T::write(self, buf) } #[inline] fn flush(&mut self) -> Result<(), Self::Error> { T::flush(self) } } impl Seek for &mut T { #[inline] fn seek(&mut self, pos: crate::SeekFrom) -> Result { T::seek(self, pos) } } /// Read is implemented for `&[u8]` by copying from the slice. /// /// Note that reading updates the slice to point to the yet unread part. /// The slice will be empty when EOF is reached. impl Read for &[u8] { #[inline] fn read(&mut self, buf: &mut [u8]) -> Result { let amt = core::cmp::min(buf.len(), self.len()); let (a, b) = self.split_at(amt); // First check if the amount of bytes we want to read is small: // `copy_from_slice` will generally expand to a call to `memcpy`, and // for a single byte the overhead is significant. if amt == 1 { buf[0] = a[0]; } else { buf[..amt].copy_from_slice(a); } *self = b; Ok(amt) } } impl BufRead for &[u8] { #[inline] fn fill_buf(&mut self) -> Result<&[u8], Self::Error> { Ok(*self) } #[inline] fn consume(&mut self, amt: usize) { *self = &self[amt..]; } } /// Write is implemented for `&mut [u8]` by copying into the slice, overwriting /// its data. /// /// Note that writing updates the slice to point to the yet unwritten part. /// The slice will be empty when it has been completely overwritten. /// /// If the number of bytes to be written exceeds the size of the slice, write operations will /// return short writes: ultimately, `Ok(0)`; in this situation, `write_all` returns an error of /// kind `ErrorKind::WriteZero`. impl Write for &mut [u8] { #[inline] fn write(&mut self, buf: &[u8]) -> Result { let amt = core::cmp::min(buf.len(), self.len()); let (a, b) = core::mem::replace(self, &mut []).split_at_mut(amt); a.copy_from_slice(&buf[..amt]); *self = b; Ok(amt) } #[inline] fn flush(&mut self) -> Result<(), Self::Error> { Ok(()) } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] impl Read for alloc::boxed::Box { #[inline] fn read(&mut self, buf: &mut [u8]) -> Result { T::read(self, buf) } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] impl BufRead for alloc::boxed::Box { fn fill_buf(&mut self) -> Result<&[u8], Self::Error> { T::fill_buf(self) } fn consume(&mut self, amt: usize) { T::consume(self, amt) } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] impl Write for alloc::boxed::Box { #[inline] fn write(&mut self, buf: &[u8]) -> Result { T::write(self, buf) } #[inline] fn flush(&mut self) -> Result<(), Self::Error> { T::flush(self) } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] impl Seek for alloc::boxed::Box { #[inline] fn seek(&mut self, pos: crate::SeekFrom) -> Result { T::seek(self, pos) } } #[cfg(feature = "alloc")] #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] impl Write for alloc::vec::Vec { #[inline] fn write(&mut self, buf: &[u8]) -> Result { self.extend_from_slice(buf); Ok(buf.len()) } #[inline] fn flush(&mut self) -> Result<(), Self::Error> { Ok(()) } }