bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #75674 - poliorcetics:intra-links-std-io, r=jyn514

Browse source 
Move to intra doc links for std::io

Helps with #75080.

@rustbot modify labels: T-doc, A-intra-doc-links, T-rustdoc

r? @jyn514

I had no problems with those files so I added some small links here and there.
This commit is contained in:
Tyler Mandry 2020-08-19 11:12:23 -07:00 • committed by GitHub
commit 0fdc8c06dd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 135 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

50
library/std/src/io/buffered.rs
View file

@ -21,17 +21,16 @@ use crate::memchr;
/// *repeated* read calls to the same file or network socket. It does not /// *repeated* read calls to the same file or network socket. It does not
/// help when reading very large amounts at once, or reading just one or a few /// help when reading very large amounts at once, or reading just one or a few
/// times. It also provides no advantage when reading from a source that is /// times. It also provides no advantage when reading from a source that is
/// already in memory, like a `Vec<u8>`. /// already in memory, like a [`Vec`]`<u8>`.
/// ///
/// When the `BufReader<R>` is dropped, the contents of its buffer will be /// When the `BufReader<R>` is dropped, the contents of its buffer will be
/// discarded. Creating multiple instances of a `BufReader<R>` on the same /// discarded. Creating multiple instances of a `BufReader<R>` on the same
/// stream can cause data loss. Reading from the underlying reader after /// stream can cause data loss. Reading from the underlying reader after
/// unwrapping the `BufReader<R>` with `BufReader::into_inner` can also cause /// unwrapping the `BufReader<R>` with [`BufReader::into_inner`] can also cause
/// data loss. /// data loss.
/// ///
/// [`Read`]: ../../std/io/trait.Read.html /// [`TcpStream::read`]: Read::read
/// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read /// [`TcpStream`]: crate::net::TcpStream
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// ///
/// # Examples /// # Examples
/// ///
@ -155,7 +154,9 @@ impl<R> BufReader<R> {
/// Returns a reference to the internally buffered data. /// Returns a reference to the internally buffered data.
/// ///
/// Unlike `fill_buf`, this will not attempt to fill the buffer if it is empty. /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty.
///
/// [`fill_buf`]: BufRead::fill_buf
/// ///
/// # Examples /// # Examples
/// ///
@ -338,27 +339,26 @@ where
impl<R: Seek> Seek for BufReader<R> { impl<R: Seek> Seek for BufReader<R> {
/// Seek to an offset, in bytes, in the underlying reader. /// Seek to an offset, in bytes, in the underlying reader.
/// ///
/// The position used for seeking with `SeekFrom::Current(_)` is the /// The position used for seeking with [`SeekFrom::Current`]`(_)` is the
/// position the underlying reader would be at if the `BufReader<R>` had no /// position the underlying reader would be at if the `BufReader<R>` had no
/// internal buffer. /// internal buffer.
/// ///
/// Seeking always discards the internal buffer, even if the seek position /// Seeking always discards the internal buffer, even if the seek position
/// would otherwise fall within it. This guarantees that calling /// would otherwise fall within it. This guarantees that calling
/// `.into_inner()` immediately after a seek yields the underlying reader /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader
/// at the same position. /// at the same position.
/// ///
/// To seek without discarding the internal buffer, use [`BufReader::seek_relative`]. /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
/// ///
/// See [`std::io::Seek`] for more details. /// See [`std::io::Seek`] for more details.
/// ///
/// Note: In the edge case where you're seeking with `SeekFrom::Current(n)` /// Note: In the edge case where you're seeking with [`SeekFrom::Current`]`(n)`
/// where `n` minus the internal buffer length overflows an `i64`, two /// where `n` minus the internal buffer length overflows an `i64`, two
/// seeks will be performed instead of one. If the second seek returns /// seeks will be performed instead of one. If the second seek returns
/// `Err`, the underlying reader will be left at the same position it would /// [`Err`], the underlying reader will be left at the same position it would
/// have if you called `seek` with `SeekFrom::Current(0)`. /// have if you called `seek` with [`SeekFrom::Current`]`(0)`.
/// ///
/// [`BufReader::seek_relative`]: struct.BufReader.html#method.seek_relative /// [`std::io::Seek`]: Seek
/// [`std::io::Seek`]: trait.Seek.html
fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> { fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
let result: u64; let result: u64;
if let SeekFrom::Current(n) = pos { if let SeekFrom::Current(n) = pos {
@ -397,7 +397,7 @@ impl<R: Seek> Seek for BufReader<R> {
/// *repeated* write calls to the same file or network socket. It does not /// *repeated* write calls to the same file or network socket. It does not
/// help when writing very large amounts at once, or writing just one or a few /// help when writing very large amounts at once, or writing just one or a few
/// times. It also provides no advantage when writing to a destination that is /// times. It also provides no advantage when writing to a destination that is
/// in memory, like a `Vec<u8>`. /// in memory, like a [`Vec`]<u8>`.
/// ///
/// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though /// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though
/// dropping will attempt to flush the contents of the buffer, any errors /// dropping will attempt to flush the contents of the buffer, any errors
@ -441,10 +441,9 @@ impl<R: Seek> Seek for BufReader<R> {
/// together by the buffer and will all be written out in one system call when /// together by the buffer and will all be written out in one system call when
/// the `stream` is flushed. /// the `stream` is flushed.
/// ///
/// [`Write`]: ../../std/io/trait.Write.html /// [`TcpStream::write`]: Write::write
/// [`TcpStream::write`]: ../../std/net/struct.TcpStream.html#method.write /// [`TcpStream`]: crate::net::TcpStream
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html /// [`flush`]: Write::flush
/// [`flush`]: #method.flush
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct BufWriter<W: Write> { pub struct BufWriter<W: Write> {
inner: Option<W>, inner: Option<W>,
@ -455,7 +454,7 @@ pub struct BufWriter<W: Write> {
panicked: bool, panicked: bool,
} }
/// An error returned by `into_inner` which combines an error that /// An error returned by [`BufWriter::into_inner`] which combines an error that
/// happened while writing out the buffer, and the buffered writer object /// happened while writing out the buffer, and the buffered writer object
/// which may be used to recover from the condition. /// which may be used to recover from the condition.
/// ///
@ -629,7 +628,7 @@ impl<W: Write> BufWriter<W> {
/// ///
/// # Errors /// # Errors
/// ///
/// An `Err` will be returned if an error occurs while flushing the buffer. /// An [`Err`] will be returned if an error occurs while flushing the buffer.
/// ///
/// # Examples /// # Examples
/// ///
@ -725,7 +724,8 @@ impl<W: Write> Drop for BufWriter<W> {
} }
impl<W> IntoInnerError<W> { impl<W> IntoInnerError<W> {
/// Returns the error which caused the call to `into_inner()` to fail. /// Returns the error which caused the call to [`BufWriter::into_inner()`]
/// to fail.
/// ///
/// This error was returned when attempting to write the internal buffer. /// This error was returned when attempting to write the internal buffer.
/// ///
@ -819,17 +819,15 @@ impl<W> fmt::Display for IntoInnerError<W> {
/// Wraps a writer and buffers output to it, flushing whenever a newline /// Wraps a writer and buffers output to it, flushing whenever a newline
/// (`0x0a`, `'\n'`) is detected. /// (`0x0a`, `'\n'`) is detected.
/// ///
/// The [`BufWriter`][bufwriter] struct wraps a writer and buffers its output. /// The [`BufWriter`] struct wraps a writer and buffers its output.
/// But it only does this batched write when it goes out of scope, or when the /// But it only does this batched write when it goes out of scope, or when the
/// internal buffer is full. Sometimes, you'd prefer to write each line as it's /// internal buffer is full. Sometimes, you'd prefer to write each line as it's
/// completed, rather than the entire buffer at once. Enter `LineWriter`. It /// completed, rather than the entire buffer at once. Enter `LineWriter`. It
/// does exactly that. /// does exactly that.
/// ///
/// Like [`BufWriter`][bufwriter], a `LineWriter`’s buffer will also be flushed when the /// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the
/// `LineWriter` goes out of scope or when its internal buffer is full. /// `LineWriter` goes out of scope or when its internal buffer is full.
/// ///
/// [bufwriter]: struct.BufWriter.html
///
/// If there's still a partial line in the buffer when the `LineWriter` is /// If there's still a partial line in the buffer when the `LineWriter` is
/// dropped, it will flush those contents. /// dropped, it will flush those contents.
/// ///
@ -979,7 +977,7 @@ impl<W: Write> LineWriter<W> {
/// ///
/// # Errors /// # Errors
/// ///
/// An `Err` will be returned if an error occurs while flushing the buffer. /// An [`Err`] will be returned if an error occurs while flushing the buffer.
/// ///
/// # Examples /// # Examples
/// ///

14
library/std/src/io/cursor.rs
View file

@ -9,7 +9,7 @@ use core::convert::TryInto;
/// [`Seek`] implementation. /// [`Seek`] implementation.
/// ///
/// `Cursor`s are used with in-memory buffers, anything implementing /// `Cursor`s are used with in-memory buffers, anything implementing
/// `AsRef<[u8]>`, to allow them to implement [`Read`] and/or [`Write`], /// [`AsRef`]`<[u8]>`, to allow them to implement [`Read`] and/or [`Write`],
/// allowing these buffers to be used anywhere you might use a reader or writer /// allowing these buffers to be used anywhere you might use a reader or writer
/// that does actual I/O. /// that does actual I/O.
/// ///
@ -23,12 +23,8 @@ use core::convert::TryInto;
/// code, but use an in-memory buffer in our tests. We can do this with /// code, but use an in-memory buffer in our tests. We can do this with
/// `Cursor`: /// `Cursor`:
/// ///
/// [`Seek`]: trait.Seek.html /// [bytes]: crate::slice
/// [`Read`]: ../../std/io/trait.Read.html /// [`File`]: crate::fs::File
/// [`Write`]: ../../std/io/trait.Write.html
/// [`Vec`]: ../../std/vec/struct.Vec.html
/// [bytes]: ../../std/primitive.slice.html
/// [`File`]: ../fs/struct.File.html
/// ///
/// ```no_run /// ```no_run
/// use std::io::prelude::*; /// use std::io::prelude::*;
@ -81,8 +77,8 @@ pub struct Cursor<T> {
impl<T> Cursor<T> { impl<T> Cursor<T> {
/// Creates a new cursor wrapping the provided underlying in-memory buffer. /// Creates a new cursor wrapping the provided underlying in-memory buffer.
/// ///
/// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`) /// Cursor initial position is `0` even if underlying buffer (e.g., [`Vec`])
/// is not empty. So writing to cursor starts with overwriting `Vec` /// is not empty. So writing to cursor starts with overwriting [`Vec`]
/// content, not with appending to it. /// content, not with appending to it.
/// ///
/// # Examples /// # Examples

65
library/std/src/io/error.rs
View file

@ -4,8 +4,7 @@ use crate::fmt;
use crate::result; use crate::result;
use crate::sys; use crate::sys;
/// A specialized [`Result`](../result/enum.Result.html) type for I/O /// A specialized [`Result`] type for I/O operations.
/// operations.
/// ///
/// This type is broadly used across [`std::io`] for any operation which may /// This type is broadly used across [`std::io`] for any operation which may
/// produce an error. /// produce an error.
@ -16,12 +15,13 @@ use crate::sys;
/// While usual Rust style is to import types directly, aliases of [`Result`] /// While usual Rust style is to import types directly, aliases of [`Result`]
/// often are not, to make it easier to distinguish between them. [`Result`] is /// often are not, to make it easier to distinguish between them. [`Result`] is
/// generally assumed to be [`std::result::Result`][`Result`], and so users of this alias /// generally assumed to be [`std::result::Result`][`Result`], and so users of this alias
/// will generally use `io::Result` instead of shadowing the prelude's import /// will generally use `io::Result` instead of shadowing the [prelude]'s import
/// of [`std::result::Result`][`Result`]. /// of [`std::result::Result`][`Result`].
/// ///
/// [`std::io`]: ../io/index.html /// [`std::io`]: crate::io
/// [`io::Error`]: ../io/struct.Error.html /// [`io::Error`]: Error
/// [`Result`]: ../result/enum.Result.html /// [`Result`]: crate::result::Result
/// [prelude]: crate::prelude
/// ///
/// # Examples /// # Examples
/// ///
@ -48,10 +48,9 @@ pub type Result<T> = result::Result<T, Error>;
/// `Error` can be created with crafted error messages and a particular value of /// `Error` can be created with crafted error messages and a particular value of
/// [`ErrorKind`]. /// [`ErrorKind`].
/// ///
/// [`Read`]: ../io/trait.Read.html /// [`Read`]: crate::io::Read
/// [`Write`]: ../io/trait.Write.html /// [`Write`]: crate::io::Write
/// [`Seek`]: ../io/trait.Seek.html /// [`Seek`]: crate::io::Seek
/// [`ErrorKind`]: enum.ErrorKind.html
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Error { pub struct Error {
repr: Repr, repr: Repr,
@ -83,7 +82,7 @@ struct Custom {
/// ///
/// It is used with the [`io::Error`] type. /// It is used with the [`io::Error`] type.
/// ///
/// [`io::Error`]: struct.Error.html /// [`io::Error`]: Error
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)] #[allow(deprecated)]
@ -137,7 +136,7 @@ pub enum ErrorKind {
/// For example, a function that reads a file into a string will error with /// For example, a function that reads a file into a string will error with
/// `InvalidData` if the file's contents are not valid UTF-8. /// `InvalidData` if the file's contents are not valid UTF-8.
/// ///
/// [`InvalidInput`]: #variant.InvalidInput /// [`InvalidInput`]: ErrorKind::InvalidInput
#[stable(feature = "io_invalid_data", since = "1.2.0")] #[stable(feature = "io_invalid_data", since = "1.2.0")]
InvalidData, InvalidData,
/// The I/O operation's timeout expired, causing it to be canceled. /// The I/O operation's timeout expired, causing it to be canceled.
@ -150,8 +149,8 @@ pub enum ErrorKind {
/// particular number of bytes but only a smaller number of bytes could be /// particular number of bytes but only a smaller number of bytes could be
/// written. /// written.
/// ///
/// [`write`]: ../../std/io/trait.Write.html#tymethod.write /// [`write`]: crate::io::Write::write
/// [`Ok(0)`]: ../../std/io/type.Result.html /// [`Ok(0)`]: Ok
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
WriteZero, WriteZero,
/// This operation was interrupted. /// This operation was interrupted.
@ -220,9 +219,6 @@ impl From<ErrorKind> for Error {
/// let error = Error::from(not_found); /// let error = Error::from(not_found);
/// assert_eq!("entity not found", format!("{}", error)); /// assert_eq!("entity not found", format!("{}", error));
/// ``` /// ```
///
/// [`ErrorKind`]: ../../std/io/enum.ErrorKind.html
/// [`Error`]: ../../std/io/struct.Error.html
#[inline] #[inline]
fn from(kind: ErrorKind) -> Error { fn from(kind: ErrorKind) -> Error {
Error { repr: Repr::Simple(kind) } Error { repr: Repr::Simple(kind) }
@ -235,7 +231,7 @@ impl Error {
/// ///
/// This function is used to generically create I/O errors which do not /// This function is used to generically create I/O errors which do not
/// originate from the OS itself. The `error` argument is an arbitrary /// originate from the OS itself. The `error` argument is an arbitrary
/// payload which will be contained in this `Error`. /// payload which will be contained in this [`Error`].
/// ///
/// # Examples /// # Examples
/// ///
@ -264,7 +260,7 @@ impl Error {
/// ///
/// This function reads the value of `errno` for the target platform (e.g. /// This function reads the value of `errno` for the target platform (e.g.
/// `GetLastError` on Windows) and will return a corresponding instance of /// `GetLastError` on Windows) and will return a corresponding instance of
/// `Error` for the error code. /// [`Error`] for the error code.
/// ///
/// # Examples /// # Examples
/// ///
@ -278,7 +274,7 @@ impl Error {
Error::from_raw_os_error(sys::os::errno() as i32) Error::from_raw_os_error(sys::os::errno() as i32)
} }
/// Creates a new instance of an `Error` from a particular OS error code. /// Creates a new instance of an [`Error`] from a particular OS error code.
/// ///
/// # Examples /// # Examples
/// ///
@ -310,9 +306,12 @@ impl Error {
/// Returns the OS error that this error represents (if any). /// Returns the OS error that this error represents (if any).
/// ///
/// If this `Error` was constructed via `last_os_error` or /// If this [`Error`] was constructed via [`last_os_error`] or
/// `from_raw_os_error`, then this function will return `Some`, otherwise /// [`from_raw_os_error`], then this function will return [`Some`], otherwise
/// it will return `None`. /// it will return [`None`].
///
/// [`last_os_error`]: Error::last_os_error
/// [`from_raw_os_error`]: Error::from_raw_os_error
/// ///
/// # Examples /// # Examples
/// ///
@ -345,8 +344,10 @@ impl Error {
/// Returns a reference to the inner error wrapped by this error (if any). /// Returns a reference to the inner error wrapped by this error (if any).
/// ///
/// If this `Error` was constructed via `new` then this function will /// If this [`Error`] was constructed via [`new`] then this function will
/// return `Some`, otherwise it will return `None`. /// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
/// ///
/// # Examples /// # Examples
/// ///
@ -380,8 +381,10 @@ impl Error {
/// Returns a mutable reference to the inner error wrapped by this error /// Returns a mutable reference to the inner error wrapped by this error
/// (if any). /// (if any).
/// ///
/// If this `Error` was constructed via `new` then this function will /// If this [`Error`] was constructed via [`new`] then this function will
/// return `Some`, otherwise it will return `None`. /// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
/// ///
/// # Examples /// # Examples
/// ///
@ -448,8 +451,10 @@ impl Error {
/// Consumes the `Error`, returning its inner error (if any). /// Consumes the `Error`, returning its inner error (if any).
/// ///
/// If this `Error` was constructed via `new` then this function will /// If this [`Error`] was constructed via [`new`] then this function will
/// return `Some`, otherwise it will return `None`. /// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
/// ///
/// # Examples /// # Examples
/// ///
@ -480,7 +485,7 @@ impl Error {
} }
} }
/// Returns the corresponding `ErrorKind` for this error. /// Returns the corresponding [`ErrorKind`] for this error.
/// ///
/// # Examples /// # Examples
/// ///

99
library/std/src/io/mod.rs
View file

@ -240,9 +240,9 @@
//! //!
//! [`File`]: crate::fs::File //! [`File`]: crate::fs::File
//! [`TcpStream`]: crate::net::TcpStream //! [`TcpStream`]: crate::net::TcpStream
//! [`Vec<T>`]: crate::vec::Vec //! [`Vec<T>`]: Vec
//! [`io::stdout`]: stdout //! [`io::stdout`]: stdout
//! [`io::Result`]: crate::io::Result //! [`io::Result`]: self::Result
//! [`?` operator]: ../../book/appendix-02-operators.html //! [`?` operator]: ../../book/appendix-02-operators.html
//! [`Result`]: crate::result::Result //! [`Result`]: crate::result::Result
//! [`.unwrap()`]: crate::result::Result::unwrap //! [`.unwrap()`]: crate::result::Result::unwrap
@ -671,15 +671,15 @@ pub trait Read {
/// If the data in this stream is *not* valid UTF-8 then an error is /// If the data in this stream is *not* valid UTF-8 then an error is
/// returned and `buf` is unchanged. /// returned and `buf` is unchanged.
/// ///
/// See [`read_to_end`][readtoend] for other error semantics. /// See [`read_to_end`] for other error semantics.
/// ///
/// [readtoend]: Self::read_to_end /// [`read_to_end`]: Read::read_to_end
/// ///
/// # Examples /// # Examples
/// ///
/// [`File`][file]s implement `Read`: /// [`File`]s implement `Read`:
/// ///
/// [file]: crate::fs::File /// [`File`]: crate::fs::File
/// ///
/// ```no_run /// ```no_run
/// use std::io; /// use std::io;
@ -790,9 +790,9 @@ pub trait Read {
/// ///
/// # Examples /// # Examples
/// ///
/// [`File`][file]s implement `Read`: /// [`File`]s implement `Read`:
/// ///
/// [file]: crate::fs::File /// [`File`]: crate::fs::File
/// ///
/// ```no_run /// ```no_run
/// use std::io; /// use std::io;
@ -834,10 +834,9 @@ pub trait Read {
/// ///
/// # Examples /// # Examples
/// ///
/// [`File`][file]s implement `Read`: /// [`File`]s implement `Read`:
/// ///
/// [file]: crate::fs::File /// [`File`]: crate::fs::File
/// [`Iterator`]: crate::iter::Iterator
/// [`Result`]: crate::result::Result /// [`Result`]: crate::result::Result
/// [`io::Error`]: self::Error /// [`io::Error`]: self::Error
/// ///
@ -871,9 +870,9 @@ pub trait Read {
/// ///
/// # Examples /// # Examples
/// ///
/// [`File`][file]s implement `Read`: /// [`File`]s implement `Read`:
/// ///
/// [file]: crate::fs::File /// [`File`]: crate::fs::File
/// ///
/// ```no_run /// ```no_run
/// use std::io; /// use std::io;
@ -1210,8 +1209,8 @@ impl Initializer {
/// throughout [`std::io`] take and provide types which implement the `Write` /// throughout [`std::io`] take and provide types which implement the `Write`
/// trait. /// trait.
/// ///
/// [`write`]: Self::write /// [`write`]: Write::write
/// [`flush`]: Self::flush /// [`flush`]: Write::flush
/// [`std::io`]: self /// [`std::io`]: self
/// ///
/// # Examples /// # Examples
@ -1237,7 +1236,7 @@ impl Initializer {
/// The trait also provides convenience methods like [`write_all`], which calls /// The trait also provides convenience methods like [`write_all`], which calls
/// `write` in a loop until its entire input has been written. /// `write` in a loop until its entire input has been written.
/// ///
/// [`write_all`]: Self::write_all /// [`write_all`]: Write::write_all
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[doc(spotlight)] #[doc(spotlight)]
pub trait Write { pub trait Write {
@ -1283,30 +1282,36 @@ pub trait Write {
/// Ok(()) /// Ok(())
/// } /// }
/// ``` /// ```
///
/// [`Ok(n)`]: Ok
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
fn write(&mut self, buf: &[u8]) -> Result<usize>; fn write(&mut self, buf: &[u8]) -> Result<usize>;
/// Like `write`, except that it writes from a slice of buffers. /// Like [`write`], except that it writes from a slice of buffers.
/// ///
/// Data is copied from each buffer in order, with the final buffer /// Data is copied from each buffer in order, with the final buffer
/// read from possibly being only partially consumed. This method must /// read from possibly being only partially consumed. This method must
/// behave as a call to `write` with the buffers concatenated would. /// behave as a call to [`write`] with the buffers concatenated would.
/// ///
/// The default implementation calls `write` with either the first nonempty /// The default implementation calls [`write`] with either the first nonempty
/// buffer provided, or an empty one if none exists. /// buffer provided, or an empty one if none exists.
///
/// [`write`]: Write::write
#[stable(feature = "iovec", since = "1.36.0")] #[stable(feature = "iovec", since = "1.36.0")]
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize> { fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize> {
default_write_vectored(|b| self.write(b), bufs) default_write_vectored(|b| self.write(b), bufs)
} }
/// Determines if this `Write`er has an efficient `write_vectored` /// Determines if this `Write`er has an efficient [`write_vectored`]
/// implementation. /// implementation.
/// ///
/// If a `Write`er does not override the default `write_vectored` /// If a `Write`er does not override the default [`write_vectored`]
/// implementation, code using it may want to avoid the method all together /// implementation, code using it may want to avoid the method all together
/// and coalesce writes into a single buffer for higher performance. /// and coalesce writes into a single buffer for higher performance.
/// ///
/// The default implementation returns `false`. /// The default implementation returns `false`.
///
/// [`write_vectored`]: Write::write_vectored
#[unstable(feature = "can_vector", issue = "69941")] #[unstable(feature = "can_vector", issue = "69941")]
fn is_write_vectored(&self) -> bool { fn is_write_vectored(&self) -> bool {
false false
@ -1354,7 +1359,7 @@ pub trait Write {
/// This function will return the first error of /// This function will return the first error of
/// non-[`ErrorKind::Interrupted`] kind that [`write`] returns. /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns.
/// ///
/// [`write`]: Self::write /// [`write`]: Write::write
/// ///
/// # Examples /// # Examples
/// ///
@ -1395,22 +1400,21 @@ pub trait Write {
/// ///
/// If the buffer contains no data, this will never call [`write_vectored`]. /// If the buffer contains no data, this will never call [`write_vectored`].
/// ///
/// [`write_vectored`]: Self::write_vectored
///
/// # Notes /// # Notes
/// ///
/// /// Unlike [`write_vectored`], this takes a *mutable* reference to
/// Unlike `io::Write::write_vectored`, this takes a *mutable* reference to /// a slice of [`IoSlice`]s, not an immutable one. That's because we need to
/// a slice of `IoSlice`s, not an immutable one. That's because we need to
/// modify the slice to keep track of the bytes already written. /// modify the slice to keep track of the bytes already written.
/// ///
/// Once this function returns, the contents of `bufs` are unspecified, as /// Once this function returns, the contents of `bufs` are unspecified, as
/// this depends on how many calls to `write_vectored` were necessary. It is /// this depends on how many calls to [`write_vectored`] were necessary. It is
/// best to understand this function as taking ownership of `bufs` and to /// best to understand this function as taking ownership of `bufs` and to
/// not use `bufs` afterwards. The underlying buffers, to which the /// not use `bufs` afterwards. The underlying buffers, to which the
/// `IoSlice`s point (but not the `IoSlice`s themselves), are unchanged and /// [`IoSlice`]s point (but not the [`IoSlice`]s themselves), are unchanged and
/// can be reused. /// can be reused.
/// ///
/// [`write_vectored`]: Write::write_vectored
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -1458,12 +1462,12 @@ pub trait Write {
/// explicitly be called. The [`write!()`] macro should be favored to /// explicitly be called. The [`write!()`] macro should be favored to
/// invoke this method instead. /// invoke this method instead.
/// ///
/// This function internally uses the [`write_all`][writeall] method on /// This function internally uses the [`write_all`] method on
/// this trait and hence will continuously write data so long as no errors /// 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 /// are received. This also means that partial writes are not indicated in
/// this signature. /// this signature.
/// ///
/// [writeall]: Self::write_all /// [`write_all`]: Write::write_all
/// ///
/// # Errors /// # Errors
/// ///
@ -1558,9 +1562,9 @@ pub trait Write {
/// ///
/// # Examples /// # Examples
/// ///
/// [`File`][file]s implement `Seek`: /// [`File`]s implement `Seek`:
/// ///
/// [file]: crate::fs::File /// [`File`]: crate::fs::File
/// ///
/// ```no_run /// ```no_run
/// use std::io; /// use std::io;
@ -1610,7 +1614,6 @@ pub trait Seek {
/// data is appended to a file). So calling this method multiple times does /// data is appended to a file). So calling this method multiple times does
/// not necessarily return the same length each time. /// not necessarily return the same length each time.
/// ///
///
/// # Example /// # Example
/// ///
/// ```no_run /// ```no_run
@ -1646,7 +1649,6 @@ pub trait Seek {
/// ///
/// This is equivalent to `self.seek(SeekFrom::Current(0))`. /// This is equivalent to `self.seek(SeekFrom::Current(0))`.
/// ///
///
/// # Example /// # Example
/// ///
/// ```no_run /// ```no_run
@ -1756,8 +1758,8 @@ fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>) -> R
/// [`BufReader`] to the rescue! /// [`BufReader`] to the rescue!
/// ///
/// [`File`]: crate::fs::File /// [`File`]: crate::fs::File
/// [`read_line`]: Self::read_line /// [`read_line`]: BufRead::read_line
/// [`lines`]: Self::lines /// [`lines`]: BufRead::lines
/// ///
/// ```no_run /// ```no_run
/// use std::io::{self, BufReader}; /// use std::io::{self, BufReader};
@ -1775,7 +1777,6 @@ fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>) -> R
/// Ok(()) /// Ok(())
/// } /// }
/// ``` /// ```
///
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait BufRead: Read { pub trait BufRead: Read {
/// Returns the contents of the internal buffer, filling it with more data /// Returns the contents of the internal buffer, filling it with more data
@ -1788,7 +1789,7 @@ pub trait BufRead: Read {
/// be called with the number of bytes that are consumed from this buffer to /// be called with the number of bytes that are consumed from this buffer to
/// ensure that the bytes are never returned twice. /// ensure that the bytes are never returned twice.
/// ///
/// [`consume`]: Self::consume /// [`consume`]: BufRead::consume
/// ///
/// An empty buffer returned indicates that the stream has reached EOF. /// An empty buffer returned indicates that the stream has reached EOF.
/// ///
@ -1838,7 +1839,7 @@ pub trait BufRead: Read {
/// Since `consume()` is meant to be used with [`fill_buf`], /// Since `consume()` is meant to be used with [`fill_buf`],
/// that method's example includes an example of `consume()`. /// that method's example includes an example of `consume()`.
/// ///
/// [`fill_buf`]: Self::fill_buf /// [`fill_buf`]: BufRead::fill_buf
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
fn consume(&mut self, amt: usize); fn consume(&mut self, amt: usize);
@ -1862,7 +1863,7 @@ pub trait BufRead: Read {
/// If an I/O error is encountered then all bytes read so far will be /// If an I/O error is encountered then all bytes read so far will be
/// present in `buf` and its length will have been adjusted appropriately. /// present in `buf` and its length will have been adjusted appropriately.
/// ///
/// [`fill_buf`]: Self::fill_buf /// [`fill_buf`]: BufRead::fill_buf
/// ///
/// # Examples /// # Examples
/// ///
@ -1901,22 +1902,24 @@ pub trait BufRead: Read {
read_until(self, byte, buf) read_until(self, byte, buf)
} }
/// Read all bytes until a newline (the 0xA byte) is reached, and append /// Read all bytes until a newline (the `0xA` byte) is reached, and append
/// them to the provided buffer. /// them to the provided buffer.
/// ///
/// This function will read bytes from the underlying stream until the /// This function will read bytes from the underlying stream until the
/// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes /// newline delimiter (the `0xA` byte) or EOF is found. Once found, all bytes
/// up to, and including, the delimiter (if found) will be appended to /// up to, and including, the delimiter (if found) will be appended to
/// `buf`. /// `buf`.
/// ///
/// If successful, this function will return the total number of bytes read. /// If successful, this function will return the total number of bytes read.
/// ///
/// If this function returns `Ok(0)`, the stream has reached EOF. /// If this function returns [`Ok(0)`], the stream has reached EOF.
/// ///
/// This function is blocking and should be used carefully: it is possible for /// This function is blocking and should be used carefully: it is possible for
/// an attacker to continuously send bytes without ever sending a newline /// an attacker to continuously send bytes without ever sending a newline
/// or EOF. /// or EOF.
/// ///
/// [`Ok(0)`]: Ok
///
/// # Errors /// # Errors
/// ///
/// This function has the same error semantics as [`read_until`] and will /// This function has the same error semantics as [`read_until`] and will
@ -1924,7 +1927,7 @@ pub trait BufRead: Read {
/// error is encountered then `buf` may contain some bytes already read in /// error is encountered then `buf` may contain some bytes already read in
/// the event that all data read so far was valid UTF-8. /// the event that all data read so far was valid UTF-8.
/// ///
/// [`read_until`]: Self::read_until /// [`read_until`]: BufRead::read_until
/// ///
/// # Examples /// # Examples
/// ///
@ -1976,8 +1979,8 @@ pub trait BufRead: Read {
/// also yielded an error. /// also yielded an error.
/// ///
/// [`io::Result`]: self::Result /// [`io::Result`]: self::Result
/// [`Vec<u8>`]: crate::vec::Vec /// [`Vec<u8>`]: Vec
/// [`read_until`]: Self::read_until /// [`read_until`]: BufRead::read_until
/// ///
/// # Examples /// # Examples
/// ///
@ -2008,7 +2011,7 @@ pub trait BufRead: Read {
/// ///
/// The iterator returned from this function will yield instances of /// The iterator returned from this function will yield instances of
/// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline /// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline
/// byte (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end. /// byte (the `0xA` byte) or `CRLF` (`0xD`, `0xA` bytes) at the end.
/// ///
/// [`io::Result`]: self::Result /// [`io::Result`]: self::Result
/// ///

29
library/std/src/io/stdio.rs
View file

@ -252,8 +252,7 @@ fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> {
/// ///
/// Created by the [`io::stdin`] method. /// Created by the [`io::stdin`] method.
/// ///
/// [`io::stdin`]: fn.stdin.html /// [`io::stdin`]: stdin
/// [`BufRead`]: trait.BufRead.html
/// ///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// ///
@ -283,10 +282,6 @@ pub struct Stdin {
/// This handle implements both the [`Read`] and [`BufRead`] traits, and /// This handle implements both the [`Read`] and [`BufRead`] traits, and
/// is constructed via the [`Stdin::lock`] method. /// is constructed via the [`Stdin::lock`] method.
/// ///
/// [`Read`]: trait.Read.html
/// [`BufRead`]: trait.BufRead.html
/// [`Stdin::lock`]: struct.Stdin.html#method.lock
///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// ///
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
@ -319,8 +314,6 @@ pub struct StdinLock<'a> {
/// is synchronized via a mutex. If you need more explicit control over /// is synchronized via a mutex. If you need more explicit control over
/// locking, see the [`Stdin::lock`] method. /// locking, see the [`Stdin::lock`] method.
/// ///
/// [`Stdin::lock`]: struct.Stdin.html#method.lock
///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
@ -380,9 +373,6 @@ impl Stdin {
/// returned guard also implements the [`Read`] and [`BufRead`] traits for /// returned guard also implements the [`Read`] and [`BufRead`] traits for
/// accessing the underlying data. /// accessing the underlying data.
/// ///
/// [`Read`]: trait.Read.html
/// [`BufRead`]: trait.BufRead.html
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -407,8 +397,6 @@ impl Stdin {
/// For detailed semantics of this method, see the documentation on /// For detailed semantics of this method, see the documentation on
/// [`BufRead::read_line`]. /// [`BufRead::read_line`].
/// ///
/// [`BufRead::read_line`]: trait.BufRead.html#method.read_line
///
/// # Examples /// # Examples
/// ///
/// ```no_run /// ```no_run
@ -542,8 +530,8 @@ impl fmt::Debug for StdinLock<'_> {
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
/// an error. /// an error.
/// ///
/// [`lock`]: #method.lock /// [`lock`]: Stdout::lock
/// [`io::stdout`]: fn.stdout.html /// [`io::stdout`]: stdout
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Stdout { pub struct Stdout {
// FIXME: this should be LineWriter or BufWriter depending on the state of // FIXME: this should be LineWriter or BufWriter depending on the state of
@ -561,9 +549,6 @@ pub struct Stdout {
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
/// an error. /// an error.
///
/// [`Write`]: trait.Write.html
/// [`Stdout::lock`]: struct.Stdout.html#method.lock
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct StdoutLock<'a> { pub struct StdoutLock<'a> {
inner: ReentrantMutexGuard<'a, RefCell<LineWriter<Maybe<StdoutRaw>>>>, inner: ReentrantMutexGuard<'a, RefCell<LineWriter<Maybe<StdoutRaw>>>>,
@ -575,8 +560,6 @@ pub struct StdoutLock<'a> {
/// is synchronized via a mutex. If you need more explicit control over /// is synchronized via a mutex. If you need more explicit control over
/// locking, see the [`Stdout::lock`] method. /// locking, see the [`Stdout::lock`] method.
/// ///
/// [`Stdout::lock`]: struct.Stdout.html#method.lock
///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
@ -724,7 +707,7 @@ impl fmt::Debug for StdoutLock<'_> {
/// ///
/// For more information, see the [`io::stderr`] method. /// For more information, see the [`io::stderr`] method.
/// ///
/// [`io::stderr`]: fn.stderr.html /// [`io::stderr`]: stderr
/// ///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
@ -740,8 +723,6 @@ pub struct Stderr {
/// This handle implements the `Write` trait and is constructed via /// This handle implements the `Write` trait and is constructed via
/// the [`Stderr::lock`] method. /// the [`Stderr::lock`] method.
/// ///
/// [`Stderr::lock`]: struct.Stderr.html#method.lock
///
/// ### Note: Windows Portability Consideration /// ### Note: Windows Portability Consideration
/// When operating in a console, the Windows implementation of this stream does not support /// When operating in a console, the Windows implementation of this stream does not support
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
@ -819,7 +800,7 @@ impl Stderr {
/// guard. /// guard.
/// ///
/// The lock is released when the returned lock goes out of scope. The /// The lock is released when the returned lock goes out of scope. The
/// returned guard also implements the `Write` trait for writing data. /// returned guard also implements the [`Write`] trait for writing data.
/// ///
/// # Examples /// # Examples
/// ///

33
library/std/src/io/util.rs
View file

@ -16,14 +16,17 @@ use crate::mem::MaybeUninit;
/// If you’re wanting to copy the contents of one file to another and you’re /// If you’re wanting to copy the contents of one file to another and you’re
/// working with filesystem paths, see the [`fs::copy`] function. /// working with filesystem paths, see the [`fs::copy`] function.
/// ///
/// [`fs::copy`]: ../fs/fn.copy.html /// [`fs::copy`]: crate::fs::copy
/// ///
/// # Errors /// # Errors
/// ///
/// This function will return an error immediately if any call to `read` or /// This function will return an error immediately if any call to [`read`] or
/// `write` returns an error. All instances of `ErrorKind::Interrupted` are /// [`write`] returns an error. All instances of [`ErrorKind::Interrupted`] are
/// handled by this function and the underlying operation is retried. /// handled by this function and the underlying operation is retried.
/// ///
/// [`read`]: Read::read
/// [`write`]: Write::write
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -70,10 +73,8 @@ where
/// A reader which is always at EOF. /// A reader which is always at EOF.
/// ///
/// This struct is generally created by calling [`empty`]. Please see /// This struct is generally created by calling [`empty()`]. Please see
/// the documentation of [`empty()`][`empty`] for more details. /// the documentation of [`empty()`] for more details.
///
/// [`empty`]: fn.empty.html
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Empty { pub struct Empty {
_priv: (), _priv: (),
@ -83,8 +84,6 @@ pub struct Empty {
/// ///
/// All reads from the returned reader will return [`Ok`]`(0)`. /// All reads from the returned reader will return [`Ok`]`(0)`.
/// ///
/// [`Ok`]: ../result/enum.Result.html#variant.Ok
///
/// # Examples /// # Examples
/// ///
/// A slightly sad example of not reading anything into a buffer: /// A slightly sad example of not reading anything into a buffer:
@ -132,10 +131,8 @@ impl fmt::Debug for Empty {
/// A reader which yields one byte over and over and over and over and over and... /// A reader which yields one byte over and over and over and over and over and...
/// ///
/// This struct is generally created by calling [`repeat`][repeat]. Please /// This struct is generally created by calling [`repeat()`]. Please
/// see the documentation of `repeat()` for more details. /// see the documentation of [`repeat()`] for more details.
///
/// [repeat]: fn.repeat.html
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Repeat { pub struct Repeat {
byte: u8, byte: u8,
@ -199,10 +196,8 @@ impl fmt::Debug for Repeat {
/// A writer which will move data into the void. /// A writer which will move data into the void.
/// ///
/// This struct is generally created by calling [`sink`][sink]. Please /// This struct is generally created by calling [`sink`]. Please
/// see the documentation of `sink()` for more details. /// see the documentation of [`sink()`] for more details.
///
/// [sink]: fn.sink.html
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Sink { pub struct Sink {
_priv: (), _priv: (),
@ -210,9 +205,11 @@ pub struct Sink {
/// Creates an instance of a writer which will successfully consume all data. /// Creates an instance of a writer which will successfully consume all data.
/// ///
/// All calls to `write` on the returned instance will return `Ok(buf.len())` /// All calls to [`write`] on the returned instance will return `Ok(buf.len())`
/// and the contents of the buffer will not be inspected. /// and the contents of the buffer will not be inspected.
/// ///
/// [`write`]: Write::write
///
/// # Examples /// # Examples
/// ///
/// ```rust /// ```rust