use super::error::{Error, ErrorKind, Result}; use core::{cmp, fmt, slice}; #[cfg(feature = "alloc")] pub use alloc::vec::Vec; #[cfg(feature = "alloc")] struct Guard<'a> { buf: &'a mut Vec, len: usize, } #[cfg(feature = "alloc")] impl Drop for Guard<'_> { fn drop(&mut self) { unsafe { self.buf.set_len(self.len); } } } // This uses an adaptive system to extend the vector when it fills. We want to // avoid paying to allocate and zero a huge chunk of memory if the reader only // has 4 bytes while still making large reads if the reader does have a ton // of data to return. Simply tacking on an extra DEFAULT_BUF_SIZE space every // time is 4,500 times (!) slower than a default reservation size of 32 if the // reader has a very small amount of data to return. // // Because we're extending the buffer with uninitialized data for trusted // readers, we need to make sure to truncate that if any of this panics. #[cfg(feature = "alloc")] fn read_to_end(r: &mut R, buf: &mut Vec) -> Result { read_to_end_with_reservation(r, buf, |_| 32) } #[cfg(feature = "alloc")] fn read_to_end_with_reservation( r: &mut R, buf: &mut Vec, mut reservation_size: F, ) -> Result where R: Read + ?Sized, F: FnMut(&R) -> usize, { let start_len = buf.len(); let mut g = Guard { len: buf.len(), buf, }; loop { if g.len == g.buf.len() { unsafe { // FIXME(danielhenrymantilla): #42788 // // - This creates a (mut) reference to a slice of // _uninitialized_ integers, which is **undefined behavior** // // - Only the standard library gets to soundly "ignore" this, // based on its privileged knowledge of unstable rustc // internals; g.buf.reserve(reservation_size(r)); let capacity = g.buf.capacity(); g.buf.set_len(capacity); r.initializer().initialize(&mut g.buf[g.len..]); } } let buf = &mut g.buf[g.len..]; match r.read(buf) { Ok(0) => return Ok(g.len - start_len), Ok(n) => { // We can't allow bogus values from read. If it is too large, the returned vec could have its length // set past its capacity, or if it overflows the vec could be shortened which could create an invalid // string if this is called via read_to_string. assert!(n <= buf.len()); g.len += n; } Err(ref e) if e.kind() == ErrorKind::Interrupted => {} Err(e) => return Err(e), } } } /// The `Read` trait allows for reading bytes from a source. /// /// Implementors of the `Read` trait are called 'readers'. /// /// Readers are defined by one required method, [`read()`]. Each call to [`read()`] /// will attempt to pull bytes from this source into a provided buffer. A /// number of other methods are implemented in terms of [`read()`], giving /// implementors a number of ways to read bytes while only needing to implement /// a single method. /// /// Readers are intended to be composable with one another. Many implementors /// throughout [`std::io`] take and provide types which implement the `Read` /// trait. /// /// Please note that each call to [`read()`] may involve a system call, and /// therefore, using something that implements [`BufRead`], such as /// [`BufReader`], will be more efficient. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = [0; 10]; /// /// // read up to 10 bytes /// f.read(&mut buffer)?; /// /// let mut buffer = Vec::new(); /// // read the whole file /// f.read_to_end(&mut buffer)?; /// /// // read into a String, so that you don't need to do the conversion. /// let mut buffer = String::new(); /// f.read_to_string(&mut buffer)?; /// /// // and more! See the other methods for more details. /// Ok(()) /// } /// ``` /// /// Read from [`&str`] because [`&[u8]`][slice] implements `Read`: /// /// ```no_run /// # use std::io; /// use std::io::prelude::*; /// /// fn main() -> io::Result<()> { /// let mut b = "This string will be read".as_bytes(); /// let mut buffer = [0; 10]; /// /// // read up to 10 bytes /// b.read(&mut buffer)?; /// /// // etc... it works exactly as a File does! /// Ok(()) /// } /// ``` /// /// [`read()`]: Read::read /// [`&str`]: prim@str /// [`std::io`]: self /// [`File`]: crate::fs::File /// [slice]: ../../std/primitive.slice.html pub trait Read { /// Pull some bytes from this source into the specified buffer, returning /// how many bytes were read. /// /// This function does not provide any guarantees about whether it blocks /// waiting for data, but if an object needs to block for a read and cannot, /// it will typically signal this via an [`Err`] return value. /// /// If the return value of this method is [`Ok(n)`], then it must be /// guaranteed 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 reader has reached its "end of file" and will likely no longer /// be able to produce bytes. Note that this does not mean that the /// reader will *always* no longer be able to produce bytes. /// 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 reader 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 read() was interrupted by a signal. /// /// No guarantees are provided about the contents of `buf` when this /// function is called, 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 reading its contents. /// /// Correspondingly, however, *callers* of this method may 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 read /// from it. It is your responsibility to make sure that `buf` is initialized /// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one /// obtains via [`MaybeUninit`]) is not safe, and can lead to undefined behavior. /// /// [`MaybeUninit`]: 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 read. /// /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the read /// operation should be retried if there is nothing else to do. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`Ok(n)`]: Ok /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = [0; 10]; /// /// // read up to 10 bytes /// let n = f.read(&mut buffer[..])?; /// /// println!("The bytes: {:?}", &buffer[..n]); /// Ok(()) /// } /// ``` fn read(&mut self, buf: &mut [u8]) -> Result; /// Read all bytes until EOF in this source, placing them into `buf`. /// /// All bytes read from this source will be appended to the specified buffer /// `buf`. This function will continuously call [`read()`] to append more data to /// `buf` until [`read()`] returns either [`Ok(0)`] or an error of /// non-[`ErrorKind::Interrupted`] kind. /// /// If successful, this function will return the total number of bytes read. /// /// # 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 read error is encountered then this function immediately /// returns. Any bytes which have already been read will be appended to /// `buf`. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`read()`]: Read::read /// [`Ok(0)`]: Ok /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = Vec::new(); /// /// // read the whole file /// f.read_to_end(&mut buffer)?; /// Ok(()) /// } /// ``` /// /// (See also the [`std::fs::read`] convenience function for reading from a /// file.) /// /// [`std::fs::read`]: crate::fs::read #[cfg(feature = "alloc")] fn read_to_end(&mut self, buf: &mut Vec) -> Result { read_to_end(self, buf) } /// Determines if this `Read`er can work with buffers of uninitialized /// memory. /// /// The default implementation returns an initializer which will zero /// buffers. /// /// If a `Read`er guarantees that it can work properly with uninitialized /// memory, it should call [`Initializer::nop()`]. See the documentation for /// [`Initializer`] for details. /// /// The behavior of this method must be independent of the state of the /// `Read`er - the method only takes `&self` so that it can be used through /// trait objects. /// /// # Safety /// /// This method is unsafe because a `Read`er could otherwise return a /// non-zeroing `Initializer` from another `Read` type without an `unsafe` /// block. #[inline] unsafe fn initializer(&self) -> Initializer { Initializer::zeroing() } /// Read the exact number of bytes required to fill `buf`. /// /// This function reads 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, 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 reading its contents. The /// documentation on [`read`] has a more detailed explanation on this /// subject. /// /// # Errors /// /// If this function encounters an error of the kind /// [`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`]. /// The contents of `buf` are unspecified in this case. /// /// If any other read 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 read, but it will never read more than would be necessary to /// completely fill the buffer. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`read`]: Read::read /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = [0; 10]; /// /// // read exactly 10 bytes /// f.read_exact(&mut buffer)?; /// Ok(()) /// } /// ``` fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> { while !buf.is_empty() { match self.read(buf) { Ok(0) => break, Ok(n) => { let tmp = buf; buf = &mut tmp[n..]; } Err(ref e) if e.kind() == ErrorKind::Interrupted => {} Err(e) => return Err(e), } } if !buf.is_empty() { Err(Error::new( ErrorKind::UnexpectedEof, "failed to fill whole buffer", )) } else { Ok(()) } } /// Creates a "by reference" adaptor for this instance of `Read`. /// /// The returned adaptor also implements `Read` and will simply borrow this /// current reader. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::Read; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = Vec::new(); /// let mut other_buffer = Vec::new(); /// /// { /// let reference = f.by_ref(); /// /// // read at most 5 bytes /// reference.take(5).read_to_end(&mut buffer)?; /// /// } // drop our &mut reference so we can use f again /// /// // original file still usable, read the rest /// f.read_to_end(&mut other_buffer)?; /// Ok(()) /// } /// ``` fn by_ref(&mut self) -> &mut Self where Self: Sized, { self } /// Transforms this `Read` instance to an [`Iterator`] over its bytes. /// /// The returned type implements [`Iterator`] where the `Item` is /// [`Result`]`<`[`u8`]`, `[`io::Error`]`>`. /// The yielded item is [`Ok`] if a byte was successfully read and [`Err`] /// otherwise. EOF is mapped to returning [`None`] from this iterator. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`File`]: crate::fs::File /// [`Result`]: crate::result::Result /// [`io::Error`]: self::Error /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// /// for byte in f.bytes() { /// println!("{}", byte.unwrap()); /// } /// Ok(()) /// } /// ``` fn bytes(self) -> Bytes where Self: Sized, { Bytes { inner: self } } /// Creates an adaptor which will chain this stream with another. /// /// The returned `Read` instance will first read all bytes from this object /// until EOF is encountered. Afterwards the output is equivalent to the /// output of `next`. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f1 = File::open("foo.txt")?; /// let mut f2 = File::open("bar.txt")?; /// /// let mut handle = f1.chain(f2); /// let mut buffer = String::new(); /// /// // read the value into a String. We could use any Read method here, /// // this is just one example. /// handle.read_to_string(&mut buffer)?; /// Ok(()) /// } /// ``` fn chain(self, next: R) -> Chain where Self: Sized, { Chain { first: self, second: next, done_first: false, } } /// Creates an adaptor which will read at most `limit` bytes from it. /// /// This function returns a new instance of `Read` which will read at most /// `limit` bytes, after which it will always return EOF ([`Ok(0)`]). Any /// read errors will not count towards the number of bytes read and future /// calls to [`read()`] may succeed. /// /// # Examples /// /// [`File`]s implement `Read`: /// /// [`File`]: crate::fs::File /// [`Ok(0)`]: Ok /// [`read()`]: Read::read /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// let mut buffer = [0; 5]; /// /// // read at most five bytes /// let mut handle = f.take(5); /// /// handle.read(&mut buffer)?; /// Ok(()) /// } /// ``` fn take(self, limit: u64) -> Take where Self: Sized, { Take { inner: self, limit } } } /// A type used to conditionally initialize buffers passed to `Read` methods. #[derive(Debug)] pub struct Initializer(bool); impl Initializer { /// Returns a new `Initializer` which will zero out buffers. #[inline] pub fn zeroing() -> Initializer { Initializer(true) } /// Returns a new `Initializer` which will not zero out buffers. /// /// # Safety /// /// This may only be called by `Read`ers which guarantee that they will not /// read from buffers passed to `Read` methods, and that the return value of /// the method accurately reflects the number of bytes that have been /// written to the head of the buffer. #[inline] pub unsafe fn nop() -> Initializer { Initializer(false) } /// Indicates if a buffer should be initialized. #[inline] pub fn should_initialize(&self) -> bool { self.0 } /// Initializes a buffer if necessary. #[inline] pub fn initialize(&self, buf: &mut [u8]) { if self.should_initialize() { unsafe { core::ptr::write_bytes(buf.as_mut_ptr(), 0, buf.len()) } } } } /// A trait for objects which are byte-oriented sinks. /// /// Implementors of the `Write` trait are sometimes called 'writers'. /// /// Writers are defined by two required methods, [`write`] and [`flush`]: /// /// * The [`write`] method will attempt to write some data into the object, /// returning how many bytes were successfully written. /// /// * The [`flush`] method is useful for adaptors and explicit buffers /// themselves for ensuring that all buffered data has been pushed out to the /// 'true sink'. /// /// Writers are intended to be composable with one another. Many implementors /// throughout [`std::io`] take and provide types which implement the `Write` /// trait. /// /// [`write`]: Write::write /// [`flush`]: Write::flush /// [`std::io`]: self /// /// # Examples /// /// ```no_run /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let data = b"some bytes"; /// /// let mut pos = 0; /// let mut buffer = File::create("foo.txt")?; /// /// while pos < data.len() { /// let bytes_written = buffer.write(&data[pos..])?; /// pos += bytes_written; /// } /// Ok(()) /// } /// ``` /// /// The trait also provides convenience methods like [`write_all`], which calls /// `write` in a loop until its entire input has been written. /// /// [`write_all`]: Write::write_all pub trait Write { /// Write a buffer into this writer, returning how many bytes were written. /// /// This function will attempt to write the entire contents of `buf`, but /// the entire write may not succeed, or the write may also generate an /// error. A call to `write` represents *at most one* attempt to write to /// any wrapped object. /// /// Calls to `write` are not guaranteed to block waiting for data to be /// written, and a write which would otherwise block can be indicated through /// an [`Err`] variant. /// /// If the return value is [`Ok(n)`] then it must be guaranteed that /// `n <= buf.len()`. A return value of `0` typically means that the /// underlying object is no longer able to accept bytes and will likely not /// be able to in the future as well, or that the buffer provided is empty. /// /// # Errors /// /// Each call to `write` may generate an I/O error indicating that the /// operation could not be completed. If an error is returned then no bytes /// in the buffer were written to this writer. /// /// It is **not** considered an error if the entire buffer could not be /// written to this writer. /// /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the /// write operation should be retried if there is nothing else to do. /// /// # Examples /// /// ```no_run /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let mut buffer = File::create("foo.txt")?; /// /// // Writes some prefix of the byte string, not necessarily all of it. /// buffer.write(b"some bytes")?; /// Ok(()) /// } /// ``` /// /// [`Ok(n)`]: Ok fn write(&mut self, buf: &[u8]) -> Result; /// Flush this output stream, ensuring that all intermediately buffered /// contents reach their destination. /// /// # Errors /// /// It is considered an error if not all bytes could be written due to /// I/O errors or EOF being reached. /// /// # Examples /// /// ```no_run /// use std::io::prelude::*; /// use std::io::BufWriter; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let mut buffer = BufWriter::new(File::create("foo.txt")?); /// /// buffer.write_all(b"some bytes")?; /// buffer.flush()?; /// Ok(()) /// } /// ``` fn flush(&mut self) -> Result<()>; /// Attempts to write an entire buffer into this writer. /// /// This method will continuously call [`write`] until there is no more data /// to be written or an error of non-[`ErrorKind::Interrupted`] kind is /// returned. This method will not return until the entire buffer has been /// successfully written or such an error occurs. The first error that is /// not of [`ErrorKind::Interrupted`] kind generated from this method will be /// returned. /// /// If the buffer contains no data, this will never call [`write`]. /// /// # Errors /// /// This function will return the first error of /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns. /// /// [`write`]: Write::write /// /// # Examples /// /// ```no_run /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let mut buffer = File::create("foo.txt")?; /// /// buffer.write_all(b"some bytes")?; /// Ok(()) /// } /// ``` fn write_all(&mut self, mut buf: &[u8]) -> Result<()> { while !buf.is_empty() { match self.write(buf) { Ok(0) => { return Err(Error::new( ErrorKind::WriteZero, "failed to write whole buffer", )); } Ok(n) => buf = &buf[n..], Err(ref e) if e.kind() == ErrorKind::Interrupted => {} Err(e) => return Err(e), } } Ok(()) } /// Writes a formatted string into this writer, returning any error /// encountered. /// /// This method is primarily used to interface with the /// [`format_args!()`] macro, but it is rare that this should /// explicitly be called. The [`write!()`] macro should be favored to /// invoke this method instead. /// /// This function internally uses the [`write_all`] method on /// this trait and hence will continuously write data so long as no errors /// are received. This also means that partial writes are not indicated in /// this signature. /// /// [`write_all`]: Write::write_all /// /// # Errors /// /// This function will return any I/O error reported while formatting. /// /// # Examples /// /// ```no_run /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let mut buffer = File::create("foo.txt")?; /// /// // this call /// write!(buffer, "{:.*}", 2, 1.234567)?; /// // turns into this: /// buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?; /// Ok(()) /// } /// ``` fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> { // Create a shim which translates a Write to a fmt::Write and saves // off I/O errors. instead of discarding them struct Adaptor<'a, T: ?Sized + 'a> { inner: &'a mut T, error: Result<()>, } impl fmt::Write for Adaptor<'_, 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 = Adaptor { inner: self, error: Ok(()), }; match fmt::write(&mut output, fmt) { Ok(()) => Ok(()), Err(..) => { // check if the error came from the underlying `Write` or not if output.error.is_err() { output.error } else { Err(Error::new(ErrorKind::Other, "formatter error")) } } } } /// Creates a "by reference" adaptor for this instance of `Write`. /// /// The returned adaptor also implements `Write` and will simply borrow this /// current writer. /// /// # Examples /// /// ```no_run /// use std::io::Write; /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { /// let mut buffer = File::create("foo.txt")?; /// /// let reference = buffer.by_ref(); /// /// // we can use reference just like our original buffer /// reference.write_all(b"some bytes")?; /// Ok(()) /// } /// ``` fn by_ref(&mut self) -> &mut Self where Self: Sized, { self } } /// The `Seek` trait provides a cursor which can be moved within a stream of /// bytes. /// /// The stream typically has a fixed size, allowing seeking relative to either /// end or the current offset. /// /// # Examples /// /// [`File`]s implement `Seek`: /// /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// use std::io::SeekFrom; /// /// fn main() -> io::Result<()> { /// let mut f = File::open("foo.txt")?; /// /// // move the cursor 42 bytes from the start of the file /// f.seek(SeekFrom::Start(42))?; /// Ok(()) /// } /// ``` pub trait Seek { /// Seek to an offset, in bytes, in a stream. /// /// A seek beyond the end of a stream is allowed, but behavior is defined /// by the implementation. /// /// If the seek operation completed successfully, /// this method returns the new position from the start of the stream. /// That position can be used later with [`SeekFrom::Start`]. /// /// # Errors /// /// Seeking to a negative offset is considered an error. fn seek(&mut self, pos: SeekFrom) -> Result; } /// Enumeration of possible methods to seek within an I/O object. /// /// It is used by the [`Seek`] trait. #[derive(Copy, PartialEq, Eq, Clone, Debug)] pub enum SeekFrom { /// Sets the offset to the provided number of bytes. Start(u64), /// Sets the offset to the size of this object plus the specified number of /// bytes. /// /// It is possible to seek beyond the end of an object, but it's an error to /// seek before byte 0. End(i64), /// Sets the offset to the current position plus the specified number of /// bytes. /// /// It is possible to seek beyond the end of an object, but it's an error to /// seek before byte 0. Current(i64), } /// An iterator over `u8` values of a reader. /// /// This struct is generally created by calling [`bytes`] on a reader. /// Please see the documentation of [`bytes`] for more details. /// /// [`bytes`]: Read::bytes #[derive(Debug)] pub struct Bytes { inner: R, } impl Iterator for Bytes { type Item = Result; fn next(&mut self) -> Option> { let mut byte = 0; loop { return match self.inner.read(slice::from_mut(&mut byte)) { Ok(0) => None, Ok(..) => Some(Ok(byte)), Err(ref e) if e.kind() == ErrorKind::Interrupted => continue, Err(e) => Some(Err(e)), }; } } } /// A `BufRead` is a type of `Read`er which has an internal buffer, allowing it /// to perform extra ways of reading. /// /// For example, reading line-by-line is inefficient without using a buffer, so /// if you want to read by line, you'll need `BufRead`, which includes a /// [`read_line`] method as well as a [`lines`] iterator. /// /// # Examples /// /// A locked standard input implements `BufRead`: /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// /// let stdin = io::stdin(); /// for line in stdin.lock().lines() { /// println!("{}", line.unwrap()); /// } /// ``` /// /// If you have something that implements [`Read`], you can use the [`BufReader` /// type][`BufReader`] to turn it into a `BufRead`. /// /// For example, [`File`] implements [`Read`], but not `BufRead`. /// [`BufReader`] to the rescue! /// /// [`File`]: crate::fs::File /// [`read_line`]: BufRead::read_line /// [`lines`]: BufRead::lines /// /// ```no_run /// use std::io::{self, BufReader}; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let f = File::open("foo.txt")?; /// let f = BufReader::new(f); /// /// for line in f.lines() { /// println!("{}", line.unwrap()); /// } /// /// Ok(()) /// } /// ``` pub trait BufRead: Read { /// Returns the contents of the internal buffer, filling it with more data /// from the inner reader if it is empty. /// /// This function is a lower-level call. It needs to be paired with the /// [`consume`] method to function properly. When calling this /// method, none of the contents will be "read" in the sense that later /// calling `read` may return the same contents. As such, [`consume`] must /// be called with the number of bytes that are consumed from this buffer to /// ensure that the bytes are never returned twice. /// /// [`consume`]: BufRead::consume /// /// An empty buffer returned indicates that the stream has reached EOF. /// /// # Errors /// /// This function will return an I/O error if the underlying reader was /// read, but returned an error. /// /// # Examples /// /// A locked standard input implements `BufRead`: /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// /// let stdin = io::stdin(); /// let mut stdin = stdin.lock(); /// /// let buffer = stdin.fill_buf().unwrap(); /// /// // work with buffer /// println!("{:?}", buffer); /// /// // ensure the bytes we worked with aren't returned again later /// let length = buffer.len(); /// stdin.consume(length); /// ``` fn fill_buf(&mut self) -> Result<&[u8]>; /// Tells this buffer that `amt` bytes have been consumed from the buffer, /// so they should no longer be returned in calls to `read`. /// /// This function is a lower-level call. It needs to be paired with the /// [`fill_buf`] method to function properly. This function does /// not perform any I/O, it simply informs this object that some amount of /// its buffer, returned from [`fill_buf`], has been consumed and should /// no longer be returned. As such, this function may do odd things if /// [`fill_buf`] isn't called before calling it. /// /// The `amt` must be `<=` the number of bytes in the buffer returned by /// [`fill_buf`]. /// /// # Examples /// /// Since `consume()` is meant to be used with [`fill_buf`], /// that method's example includes an example of `consume()`. /// /// [`fill_buf`]: BufRead::fill_buf fn consume(&mut self, amt: usize); } /// Adaptor to chain together two readers. /// /// This struct is generally created by calling [`chain`] on a reader. /// Please see the documentation of [`chain`] for more details. /// /// [`chain`]: Read::chain pub struct Chain { first: T, second: U, done_first: bool, } impl Chain { /// Consumes the `Chain`, returning the wrapped readers. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut foo_file = File::open("foo.txt")?; /// let mut bar_file = File::open("bar.txt")?; /// /// let chain = foo_file.chain(bar_file); /// let (foo_file, bar_file) = chain.into_inner(); /// Ok(()) /// } /// ``` pub fn into_inner(self) -> (T, U) { (self.first, self.second) } /// Gets references to the underlying readers in this `Chain`. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut foo_file = File::open("foo.txt")?; /// let mut bar_file = File::open("bar.txt")?; /// /// let chain = foo_file.chain(bar_file); /// let (foo_file, bar_file) = chain.get_ref(); /// Ok(()) /// } /// ``` pub fn get_ref(&self) -> (&T, &U) { (&self.first, &self.second) } /// Gets mutable references to the underlying readers in this `Chain`. /// /// Care should be taken to avoid modifying the internal I/O state of the /// underlying readers as doing so may corrupt the internal state of this /// `Chain`. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut foo_file = File::open("foo.txt")?; /// let mut bar_file = File::open("bar.txt")?; /// /// let mut chain = foo_file.chain(bar_file); /// let (foo_file, bar_file) = chain.get_mut(); /// Ok(()) /// } /// ``` pub fn get_mut(&mut self) -> (&mut T, &mut U) { (&mut self.first, &mut self.second) } } impl fmt::Debug for Chain { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Chain") .field("t", &self.first) .field("u", &self.second) .finish() } } impl Read for Chain { fn read(&mut self, buf: &mut [u8]) -> Result { if !self.done_first { match self.first.read(buf)? { 0 if !buf.is_empty() => self.done_first = true, n => return Ok(n), } } self.second.read(buf) } unsafe fn initializer(&self) -> Initializer { let initializer = self.first.initializer(); if initializer.should_initialize() { initializer } else { self.second.initializer() } } } impl BufRead for Chain { fn fill_buf(&mut self) -> Result<&[u8]> { if !self.done_first { match self.first.fill_buf()? { buf if buf.is_empty() => { self.done_first = true; } buf => return Ok(buf), } } self.second.fill_buf() } fn consume(&mut self, amt: usize) { if !self.done_first { self.first.consume(amt) } else { self.second.consume(amt) } } } /// Reader adaptor which limits the bytes read from an underlying reader. /// /// This struct is generally created by calling [`take`] on a reader. /// Please see the documentation of [`take`] for more details. /// /// [`take`]: Read::take #[derive(Debug)] pub struct Take { inner: T, limit: u64, } impl Take { /// Returns the number of bytes that can be read before this instance will /// return EOF. /// /// # Note /// /// This instance may reach `EOF` after reading fewer bytes than indicated by /// this method if the underlying [`Read`] instance reaches EOF. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let f = File::open("foo.txt")?; /// /// // read at most five bytes /// let handle = f.take(5); /// /// println!("limit: {}", handle.limit()); /// Ok(()) /// } /// ``` pub fn limit(&self) -> u64 { self.limit } /// Sets the number of bytes that can be read before this instance will /// return EOF. This is the same as constructing a new `Take` instance, so /// the amount of bytes read and the previous limit value don't matter when /// calling this method. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let f = File::open("foo.txt")?; /// /// // read at most five bytes /// let mut handle = f.take(5); /// handle.set_limit(10); /// /// assert_eq!(handle.limit(), 10); /// Ok(()) /// } /// ``` pub fn set_limit(&mut self, limit: u64) { self.limit = limit; } /// Consumes the `Take`, returning the wrapped reader. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut file = File::open("foo.txt")?; /// /// let mut buffer = [0; 5]; /// let mut handle = file.take(5); /// handle.read(&mut buffer)?; /// /// let file = handle.into_inner(); /// Ok(()) /// } /// ``` pub fn into_inner(self) -> T { self.inner } /// Gets a reference to the underlying reader. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut file = File::open("foo.txt")?; /// /// let mut buffer = [0; 5]; /// let mut handle = file.take(5); /// handle.read(&mut buffer)?; /// /// let file = handle.get_ref(); /// Ok(()) /// } /// ``` pub fn get_ref(&self) -> &T { &self.inner } /// Gets a mutable reference to the underlying reader. /// /// Care should be taken to avoid modifying the internal I/O state of the /// underlying reader as doing so may corrupt the internal limit of this /// `Take`. /// /// # Examples /// /// ```no_run /// use std::io; /// use std::io::prelude::*; /// use std::fs::File; /// /// fn main() -> io::Result<()> { /// let mut file = File::open("foo.txt")?; /// /// let mut buffer = [0; 5]; /// let mut handle = file.take(5); /// handle.read(&mut buffer)?; /// /// let file = handle.get_mut(); /// Ok(()) /// } /// ``` pub fn get_mut(&mut self) -> &mut T { &mut self.inner } } impl Read for Take { fn read(&mut self, buf: &mut [u8]) -> Result { // Don't call into inner reader at all at EOF because it may still block if self.limit == 0 { return Ok(0); } let max = cmp::min(buf.len() as u64, self.limit) as usize; let n = self.inner.read(&mut buf[..max])?; self.limit -= n as u64; Ok(n) } unsafe fn initializer(&self) -> Initializer { self.inner.initializer() } #[cfg(feature = "alloc")] fn read_to_end(&mut self, buf: &mut Vec) -> Result { // Pass in a reservation_size closure that respects the current value // of limit for each read. If we hit the read limit, this prevents the // final zero-byte read from allocating again. read_to_end_with_reservation(self, buf, |self_| cmp::min(self_.limit, 32) as usize) } } impl BufRead for Take { fn fill_buf(&mut self) -> Result<&[u8]> { // Don't call into inner reader at all at EOF because it may still block if self.limit == 0 { return Ok(&[]); } let buf = self.inner.fill_buf()?; let cap = cmp::min(buf.len() as u64, self.limit) as usize; Ok(&buf[..cap]) } fn consume(&mut self, amt: usize) { // Don't let callers reset the limit by passing an overlarge value let amt = cmp::min(amt as u64, self.limit) as usize; self.limit -= amt as u64; self.inner.consume(amt); } }