Rollup merge of #44010 - GuillaumeGomez:read-links, r=frewsxcv
Add missing links for Read trait r? @rust-lang/docs
This commit is contained in:
Guillaume Gomez
GitHub
commit
6b62f34ecd
1 changed files with 65 additions and 41 deletions
|
|
@ -401,28 +401,29 @@ fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize>
|
|||
///
|
||||
/// Implementors of the `Read` trait are called 'readers'.
|
||||
///
|
||||
/// Readers are defined by one required method, `read()`. Each call to `read`
|
||||
/// 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
|
||||
/// 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`
|
||||
/// 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`][bufread], such as
|
||||
/// [`BufReader`][bufreader], will be more efficient.
|
||||
///
|
||||
/// [bufread]: trait.BufRead.html
|
||||
/// [bufreader]: struct.BufReader.html
|
||||
/// 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`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`read()`]: trait.Read.html#tymethod.read
|
||||
/// [`std::io`]: ../../std/io/index.html
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
/// [`BufRead`]: trait.BufRead.html
|
||||
/// [`BufReader`]: struct.BufReader.html
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
@ -455,9 +456,9 @@ pub trait 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 but cannot
|
||||
/// it will typically signal this via an `Err` return value.
|
||||
/// it will typically signal this via an [`Err`] return value.
|
||||
///
|
||||
/// If the return value of this method is `Ok(n)`, then it must be
|
||||
/// 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:
|
||||
|
|
@ -478,14 +479,17 @@ pub trait Read {
|
|||
/// 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
|
||||
/// 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`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`Err`]: ../../std/result/enum.Result.html#variant.Err
|
||||
/// [`Ok(n)`]: ../../std/result/enum.Result.html#variant.Ok
|
||||
/// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
@ -511,8 +515,8 @@ pub trait Read {
|
|||
/// 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.
|
||||
/// 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
|
||||
|
|
@ -523,6 +527,9 @@ pub trait Read {
|
|||
/// This method is unsafe because a `Read`er could otherwise return a
|
||||
/// non-zeroing `Initializer` from another `Read` type without an `unsafe`
|
||||
/// block.
|
||||
///
|
||||
/// [`Initializer::nop()`]: ../../std/io/struct.Initializer.html#method.nop
|
||||
/// [`Initializer`]: ../../std/io/struct.Initializer.html
|
||||
#[unstable(feature = "read_initializer", issue = "42788")]
|
||||
#[inline]
|
||||
unsafe fn initializer(&self) -> Initializer {
|
||||
|
|
@ -532,16 +539,16 @@ pub trait Read {
|
|||
/// 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.
|
||||
/// `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
|
||||
/// [`ErrorKind::Interrupted`] then the error is ignored and the operation
|
||||
/// will continue.
|
||||
///
|
||||
/// If any other read error is encountered then this function immediately
|
||||
|
|
@ -550,9 +557,12 @@ pub trait Read {
|
|||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// [`File`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`read()`]: trait.Read.html#tymethod.read
|
||||
/// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
|
||||
/// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
@ -633,11 +643,11 @@ pub trait Read {
|
|||
/// # Errors
|
||||
///
|
||||
/// If this function encounters an error of the kind
|
||||
/// `ErrorKind::Interrupted` then the error is ignored and the operation
|
||||
/// [`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 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
|
||||
|
|
@ -649,9 +659,11 @@ pub trait Read {
|
|||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// [`File`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
/// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
|
||||
/// [`ErrorKind::UnexpectedEof`]: ../../std/io/enum.ErrorKind.html#variant.UnexpectedEof
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
@ -722,11 +734,11 @@ pub trait Read {
|
|||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
|
||||
|
||||
/// Transforms this `Read` instance to an `Iterator` over its bytes.
|
||||
/// Transforms this `Read` instance to an [`Iterator`] over its bytes.
|
||||
///
|
||||
/// The returned type implements `Iterator` where the `Item` is `Result<u8,
|
||||
/// R::Err>`. The yielded item is `Ok` if a byte was successfully read and
|
||||
/// `Err` otherwise for I/O errors. EOF is mapped to returning `None` from
|
||||
/// The returned type implements [`Iterator`] where the `Item` is [`Result`]`<`[`u8`]`,
|
||||
/// R::Err>`. The yielded item is [`Ok`] if a byte was successfully read and
|
||||
/// [`Err`] otherwise for I/O errors. EOF is mapped to returning [`None`] from
|
||||
/// this iterator.
|
||||
///
|
||||
/// # Examples
|
||||
|
|
@ -734,6 +746,12 @@ pub trait Read {
|
|||
/// [`File`][file]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`Iterator`]: ../../std/iter/trait.Iterator.html
|
||||
/// [`Result`]: ../../std/result/enum.Result.html
|
||||
/// [`u8`]: ../../std/primitive.u8.html
|
||||
/// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
|
||||
/// [`Err`]: ../../std/result/enum.Result.html#variant.Err
|
||||
/// [`None`]: ../../std/option/enum.Option.html#variant.None
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
@ -754,12 +772,12 @@ pub trait Read {
|
|||
Bytes { inner: self }
|
||||
}
|
||||
|
||||
/// Transforms this `Read` instance to an `Iterator` over `char`s.
|
||||
/// Transforms this `Read` instance to an [`Iterator`] over [`char`]s.
|
||||
///
|
||||
/// This adaptor will attempt to interpret this reader as a UTF-8 encoded
|
||||
/// sequence of characters. The returned iterator will return `None` once
|
||||
/// sequence of characters. The returned iterator will return [`None`] once
|
||||
/// EOF is reached for this reader. Otherwise each element yielded will be a
|
||||
/// `Result<char, E>` where `E` may contain information about what I/O error
|
||||
/// [`Result`]`<`[`char`]`, E>` where `E` may contain information about what I/O error
|
||||
/// occurred or where decoding failed.
|
||||
///
|
||||
/// Currently this adaptor will discard intermediate data read, and should
|
||||
|
|
@ -767,9 +785,13 @@ pub trait Read {
|
|||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// [`File`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
/// [`Iterator`]: ../../std/iter/trait.Iterator.html
|
||||
/// [`Result`]: ../../std/result/enum.Result.html
|
||||
/// [`char`]: ../../std/primitive.char.html
|
||||
/// [`None`]: ../../std/option/enum.Option.html#variant.None
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(io)]
|
||||
|
|
@ -832,15 +854,17 @@ pub trait Read {
|
|||
/// 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
|
||||
/// `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.
|
||||
/// calls to [`read()`] may succeed.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// [`File`][file]s implement `Read`:
|
||||
/// [`File`]s implement `Read`:
|
||||
///
|
||||
/// [file]: ../fs/struct.File.html
|
||||
/// [`File`]: ../fs/struct.File.html
|
||||
/// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
|
||||
/// [`read()`]: trait.Read.html#tymethod.read
|
||||
///
|
||||
/// ```
|
||||
/// use std::io;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue