OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Move to intra doc links for std::io

Browse Source
This commit is contained in:
Alexis Bourget 2020-08-18 19:36:52 +02:00
parent 2c3dc04ea4
commit 5d49c0e55a
6 changed files with 126 additions and 146 deletions
Show Stats 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
/// 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
/// 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
/// discarded. Creating multiple instances of a `BufReader<R>` on the same
/// 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.
///
/// [`Read`]: ../../std/io/trait.Read.html
/// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// [`TcpStream::read`]: Read::read
/// [`TcpStream`]: crate::net::TcpStream
///
/// # Examples
///
@ -155,7 +154,9 @@ impl<R> BufReader<R> {
/// 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
///
@ -338,27 +339,26 @@ where
impl<R: Seek> Seek for BufReader<R> {
/// 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
/// internal buffer.
///
/// Seeking always discards the internal buffer, even if the seek position
/// 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.
///
/// To seek without discarding the internal buffer, use [`BufReader::seek_relative`].
///
/// 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
/// 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
/// have if you called `seek` with `SeekFrom::Current(0)`.
/// [`Err`], the underlying reader will be left at the same position it would
/// have if you called `seek` with [`SeekFrom::Current`]`(0)`.
///
/// [`BufReader::seek_relative`]: struct.BufReader.html#method.seek_relative
/// [`std::io::Seek`]: trait.Seek.html
/// [`std::io::Seek`]: Seek
fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
let result: u64;
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
/// 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
/// in memory, like a `Vec<u8>`.
/// in memory, like a [`Vec`]<u8>`.
///
/// It is critical to call [`flush`] before `BufWriter<W>` is dropped. Though
/// 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
/// the `stream` is flushed.
///
/// [`Write`]: ../../std/io/trait.Write.html
/// [`TcpStream::write`]: ../../std/net/struct.TcpStream.html#method.write
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// [`flush`]: #method.flush
/// [`TcpStream::write`]: Write::write
/// [`TcpStream`]: crate::net::TcpStream
/// [`flush`]: Write::flush
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BufWriter<W: Write> {
inner: Option<W>,
@ -455,7 +454,7 @@ pub struct BufWriter<W: Write> {
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
/// which may be used to recover from the condition.
///
@ -629,7 +628,7 @@ impl<W: Write> BufWriter<W> {
///
/// # 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
///
@ -725,7 +724,8 @@ impl<W: Write> Drop for BufWriter<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.
///
@ -819,17 +819,15 @@ impl<W> fmt::Display for IntoInnerError<W> {
/// Wraps a writer and buffers output to it, flushing whenever a newline
/// (`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
/// 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
/// 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.
///
/// [bufwriter]: struct.BufWriter.html
///
/// If there's still a partial line in the buffer when the `LineWriter` is
/// dropped, it will flush those contents.
///
@ -979,7 +977,7 @@ impl<W: Write> LineWriter<W> {
///
/// # 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
///

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

@ -9,7 +9,7 @@ use core::convert::TryInto;
/// [`Seek`] implementation.
///
/// `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
/// 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
/// `Cursor`:
///
/// [`Seek`]: trait.Seek.html
/// [`Read`]: ../../std/io/trait.Read.html
/// [`Write`]: ../../std/io/trait.Write.html
/// [`Vec`]: ../../std/vec/struct.Vec.html
/// [bytes]: ../../std/primitive.slice.html
/// [`File`]: ../fs/struct.File.html
/// [bytes]: crate::slice
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io::prelude::*;
@ -81,8 +77,8 @@ pub struct Cursor<T> {
impl<T> Cursor<T> {
/// Creates a new cursor wrapping the provided underlying in-memory buffer.
///
/// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`)
/// is not empty. So writing to cursor starts with overwriting `Vec`
/// Cursor initial position is `0` even if underlying buffer (e.g., [`Vec`])
/// is not empty. So writing to cursor starts with overwriting [`Vec`]
/// content, not with appending to it.
///
/// # Examples

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

@ -4,8 +4,7 @@ use crate::fmt;
use crate::result;
use crate::sys;
/// A specialized [`Result`](../result/enum.Result.html) type for I/O
/// operations.
/// A specialized [`Result`] type for I/O operations.
///
/// This type is broadly used across [`std::io`] for any operation which may
/// produce an error.
@ -16,12 +15,13 @@ use crate::sys;
/// 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
/// 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`].
///
/// [`std::io`]: ../io/index.html
/// [`io::Error`]: ../io/struct.Error.html
/// [`Result`]: ../result/enum.Result.html
/// [`std::io`]: crate::io
/// [`io::Error`]: Error
/// [`Result`]: crate::result::Result
/// [prelude]: crate::prelude
///
/// # 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
/// [`ErrorKind`].
///
/// [`Read`]: ../io/trait.Read.html
/// [`Write`]: ../io/trait.Write.html
/// [`Seek`]: ../io/trait.Seek.html
/// [`ErrorKind`]: enum.ErrorKind.html
/// [`Read`]: crate::io::Read
/// [`Write`]: crate::io::Write
/// [`Seek`]: crate::io::Seek
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Error {
repr: Repr,
@ -83,7 +82,7 @@ struct Custom {
///
/// 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)]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)]
@ -137,7 +136,7 @@ pub enum ErrorKind {
/// 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.
///
/// [`InvalidInput`]: #variant.InvalidInput
/// [`InvalidInput`]: ErrorKind::InvalidInput
#[stable(feature = "io_invalid_data", since = "1.2.0")]
InvalidData,
/// 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
/// written.
///
/// [`write`]: ../../std/io/trait.Write.html#tymethod.write
/// [`Ok(0)`]: ../../std/io/type.Result.html
/// [`write`]: crate::io::Write::write
/// [`Ok(0)`]: Ok
#[stable(feature = "rust1", since = "1.0.0")]
WriteZero,
/// This operation was interrupted.
@ -220,9 +219,6 @@ impl From<ErrorKind> for Error {
/// let error = Error::from(not_found);
/// assert_eq!("entity not found", format!("{}", error));
/// ```
///
/// [`ErrorKind`]: ../../std/io/enum.ErrorKind.html
/// [`Error`]: ../../std/io/struct.Error.html
#[inline]
fn from(kind: ErrorKind) -> Error {
Error { repr: Repr::Simple(kind) }
@ -235,7 +231,7 @@ impl Error {
///
/// This function is used to generically create I/O errors which do not
/// 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
///
@ -264,7 +260,7 @@ impl Error {
///
/// This function reads the value of `errno` for the target platform (e.g.
/// `GetLastError` on Windows) and will return a corresponding instance of
/// `Error` for the error code.
/// [`Error`] for the error code.
///
/// # Examples
///
@ -278,7 +274,7 @@ impl Error {
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
///
@ -310,9 +306,12 @@ impl Error {
/// Returns the OS error that this error represents (if any).
///
/// If this `Error` was constructed via `last_os_error` or
/// `from_raw_os_error`, then this function will return `Some`, otherwise
/// it will return `None`.
/// If this [`Error`] was constructed via [`last_os_error`] or
/// [`from_raw_os_error`], then this function will return [`Some`], otherwise
/// it will return [`None`].
///
/// [`last_os_error`]: Error::last_os_error
/// [`from_raw_os_error`]: Error::from_raw_os_error
///
/// # Examples
///
@ -345,8 +344,10 @@ impl Error {
/// Returns a reference to the inner error wrapped by this error (if any).
///
/// If this `Error` was constructed via `new` then this function will
/// return `Some`, otherwise it will return `None`.
/// If this [`Error`] was constructed via [`new`] then this function will
/// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
///
/// # Examples
///
@ -380,8 +381,10 @@ impl Error {
/// Returns a mutable reference to the inner error wrapped by this error
/// (if any).
///
/// If this `Error` was constructed via `new` then this function will
/// return `Some`, otherwise it will return `None`.
/// If this [`Error`] was constructed via [`new`] then this function will
/// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
///
/// # Examples
///
@ -448,8 +451,10 @@ impl Error {
/// Consumes the `Error`, returning its inner error (if any).
///
/// If this `Error` was constructed via `new` then this function will
/// return `Some`, otherwise it will return `None`.
/// If this [`Error`] was constructed via [`new`] then this function will
/// return [`Some`], otherwise it will return [`None`].
///
/// [`new`]: Error::new
///
/// # Examples
///
@ -480,7 +485,7 @@ impl Error {
}
}
/// Returns the corresponding `ErrorKind` for this error.
/// Returns the corresponding [`ErrorKind`] for this error.
///
/// # Examples
///

81
library/std/src/io/mod.rs
View File

@ -240,9 +240,9 @@
//!
//! [`File`]: crate::fs::File
//! [`TcpStream`]: crate::net::TcpStream
//! [`Vec<T>`]: crate::vec::Vec
//! [`Vec<T>`]: Vec
//! [`io::stdout`]: stdout
//! [`io::Result`]: crate::io::Result
//! [`io::Result`]: self::Result
//! [`?` operator]: ../../book/appendix-02-operators.html
//! [`Result`]: crate::result::Result
//! [`.unwrap()`]: crate::result::Result::unwrap
@ -479,11 +479,11 @@ where
/// }
/// ```
///
/// [`read()`]: Read::read
/// [`read()`]: Self::read
/// [`&str`]: str
/// [`std::io`]: self
/// [`File`]: crate::fs::File
/// [slice]: ../../std/primitive.slice.html
/// [slice]: crate::slice
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(spotlight)]
pub trait Read {
@ -633,7 +633,7 @@ pub trait Read {
///
/// [`File`]s implement `Read`:
///
/// [`read()`]: Read::read
/// [`read()`]: Self::read
/// [`Ok(0)`]: Ok
/// [`File`]: crate::fs::File
///
@ -671,15 +671,15 @@ pub trait Read {
/// If the data in this stream is *not* valid UTF-8 then an error is
/// 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`]: Self::read_to_end
///
/// # Examples
///
/// [`File`][file]s implement `Read`:
/// [`File`]s implement `Read`:
///
/// [file]: crate::fs::File
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io;
@ -746,7 +746,7 @@ pub trait Read {
///
/// [`File`]s implement `Read`:
///
/// [`read`]: Read::read
/// [`read`]: Self::read
/// [`File`]: crate::fs::File
///
/// ```no_run
@ -790,9 +790,9 @@ pub trait Read {
///
/// # Examples
///
/// [`File`][file]s implement `Read`:
/// [`File`]s implement `Read`:
///
/// [file]: crate::fs::File
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io;
@ -834,10 +834,9 @@ pub trait Read {
///
/// # Examples
///
/// [`File`][file]s implement `Read`:
/// [`File`]s implement `Read`:
///
/// [file]: crate::fs::File
/// [`Iterator`]: crate::iter::Iterator
/// [`File`]: crate::fs::File
/// [`Result`]: crate::result::Result
/// [`io::Error`]: self::Error
///
@ -871,9 +870,9 @@ pub trait Read {
///
/// # Examples
///
/// [`File`][file]s implement `Read`:
/// [`File`]s implement `Read`:
///
/// [file]: crate::fs::File
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io;
@ -1283,30 +1282,36 @@ pub trait Write {
/// Ok(())
/// }
/// ```
///
/// [`Ok(n)`]: Ok
#[stable(feature = "rust1", since = "1.0.0")]
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
/// 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.
///
/// [`write`]: Self::write
#[stable(feature = "iovec", since = "1.36.0")]
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize> {
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.
///
/// 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
/// and coalesce writes into a single buffer for higher performance.
///
/// The default implementation returns `false`.
///
/// [`write_vectored`]: Self::write_vectored
#[unstable(feature = "can_vector", issue = "69941")]
fn is_write_vectored(&self) -> bool {
false
@ -1399,16 +1404,15 @@ pub trait Write {
///
/// # Notes
///
///
/// 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
/// Unlike [`write_vectored`], this takes a *mutable* reference 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.
///
/// 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
/// 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.
///
/// # Examples
@ -1458,12 +1462,12 @@ pub trait Write {
/// explicitly be called. The [`write!()`] macro should be favored to
/// 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
/// are received. This also means that partial writes are not indicated in
/// this signature.
///
/// [writeall]: Self::write_all
/// [`write_all`]: Self::write_all
///
/// # Errors
///
@ -1558,9 +1562,9 @@ pub trait Write {
///
/// # Examples
///
/// [`File`][file]s implement `Seek`:
/// [`File`]s implement `Seek`:
///
/// [file]: crate::fs::File
/// [`File`]: crate::fs::File
///
/// ```no_run
/// use std::io;
@ -1610,7 +1614,6 @@ pub trait Seek {
/// data is appended to a file). So calling this method multiple times does
/// not necessarily return the same length each time.
///
///
/// # Example
///
/// ```no_run
@ -1646,7 +1649,6 @@ pub trait Seek {
///
/// This is equivalent to `self.seek(SeekFrom::Current(0))`.
///
///
/// # Example
///
/// ```no_run
@ -1775,7 +1777,6 @@ fn read_until<R: BufRead + ?Sized>(r: &mut R, delim: u8, buf: &mut Vec<u8>) -> R
/// Ok(())
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
pub trait BufRead: Read {
/// Returns the contents of the internal buffer, filling it with more data
@ -1901,22 +1902,24 @@ pub trait BufRead: Read {
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.
///
/// 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
/// `buf`.
///
/// 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
/// an attacker to continuously send bytes without ever sending a newline
/// or EOF.
///
/// [`Ok(0)`]: Ok
///
/// # Errors
///
/// This function has the same error semantics as [`read_until`] and will
@ -1976,7 +1979,7 @@ pub trait BufRead: Read {
/// also yielded an error.
///
/// [`io::Result`]: self::Result
/// [`Vec<u8>`]: crate::vec::Vec
/// [`Vec<u8>`]: Vec
/// [`read_until`]: Self::read_until
///
/// # Examples
@ -2008,7 +2011,7 @@ pub trait BufRead: Read {
///
/// The iterator returned from this function will yield instances of
/// [`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
///

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.
///
/// [`io::stdin`]: fn.stdin.html
/// [`BufRead`]: trait.BufRead.html
/// [`io::stdin`]: stdin
///
/// ### Note: Windows Portability Consideration
///
@ -283,10 +282,6 @@ pub struct Stdin {
/// This handle implements both the [`Read`] and [`BufRead`] traits, and
/// 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
///
/// 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
/// locking, see the [`Stdin::lock`] method.
///
/// [`Stdin::lock`]: struct.Stdin.html#method.lock
///
/// ### Note: Windows Portability Consideration
/// 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
@ -380,9 +373,6 @@ impl Stdin {
/// returned guard also implements the [`Read`] and [`BufRead`] traits for
/// accessing the underlying data.
///
/// [`Read`]: trait.Read.html
/// [`BufRead`]: trait.BufRead.html
///
/// # Examples
///
/// ```no_run
@ -407,8 +397,6 @@ impl Stdin {
/// For detailed semantics of this method, see the documentation on
/// [`BufRead::read_line`].
///
/// [`BufRead::read_line`]: trait.BufRead.html#method.read_line
///
/// # Examples
///
/// ```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
/// an error.
///
/// [`lock`]: #method.lock
/// [`io::stdout`]: fn.stdout.html
/// [`lock`]: Stdout::lock
/// [`io::stdout`]: stdout
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Stdout {
// 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
/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
/// an error.
///
/// [`Write`]: trait.Write.html
/// [`Stdout::lock`]: struct.Stdout.html#method.lock
#[stable(feature = "rust1", since = "1.0.0")]
pub struct StdoutLock<'a> {
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
/// locking, see the [`Stdout::lock`] method.
///
/// [`Stdout::lock`]: struct.Stdout.html#method.lock
///
/// ### Note: Windows Portability Consideration
/// 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
@ -724,7 +707,7 @@ impl fmt::Debug for StdoutLock<'_> {
///
/// For more information, see the [`io::stderr`] method.
///
/// [`io::stderr`]: fn.stderr.html
/// [`io::stderr`]: stderr
///
/// ### Note: Windows Portability Consideration
/// 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
/// the [`Stderr::lock`] method.
///
/// [`Stderr::lock`]: struct.Stderr.html#method.lock
///
/// ### Note: Windows Portability Consideration
/// 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
@ -819,7 +800,7 @@ impl Stderr {
/// guard.
///
/// 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
///

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
/// working with filesystem paths, see the [`fs::copy`] function.
///
/// [`fs::copy`]: ../fs/fn.copy.html
/// [`fs::copy`]: crate::fs::copy
///
/// # Errors
///
/// This function will return an error immediately if any call to `read` or
/// `write` returns an error. All instances of `ErrorKind::Interrupted` are
/// This function will return an error immediately if any call to [`read`] or
/// [`write`] returns an error. All instances of [`ErrorKind::Interrupted`] are
/// handled by this function and the underlying operation is retried.
///
/// [`read`]: Read::read
/// [`write`]: Write::write
///
/// # Examples
///
/// ```
@ -70,10 +73,8 @@ where
/// A reader which is always at EOF.
///
/// This struct is generally created by calling [`empty`]. Please see
/// the documentation of [`empty()`][`empty`] for more details.
///
/// [`empty`]: fn.empty.html
/// This struct is generally created by calling [`empty()`]. Please see
/// the documentation of [`empty()`] for more details.
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Empty {
_priv: (),
@ -83,8 +84,6 @@ pub struct Empty {
///
/// All reads from the returned reader will return [`Ok`]`(0)`.
///
/// [`Ok`]: ../result/enum.Result.html#variant.Ok
///
/// # Examples
///
/// 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...
///
/// This struct is generally created by calling [`repeat`][repeat]. Please
/// see the documentation of `repeat()` for more details.
///
/// [repeat]: fn.repeat.html
/// This struct is generally created by calling [`repeat()`]. Please
/// see the documentation of [`repeat()`] for more details.
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Repeat {
byte: u8,
@ -199,10 +196,8 @@ impl fmt::Debug for Repeat {
/// A writer which will move data into the void.
///
/// This struct is generally created by calling [`sink`][sink]. Please
/// see the documentation of `sink()` for more details.
///
/// [sink]: fn.sink.html
/// This struct is generally created by calling [`sink`]. Please
/// see the documentation of [`sink()`] for more details.
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Sink {
_priv: (),
@ -210,9 +205,11 @@ pub struct Sink {
/// 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.
///
/// [`write`]: Write::write
///
/// # Examples
///
/// ```rust