//! you'll see a few different types of I/O throughout the documentation in
//! this module: [`File`]s, [`TcpStream`]s, and sometimes even [`Vec<T>`]s. For
//! example, [`Read`] adds a [`read`][`Read::read`] method, which we can use on
-//! `File`s:
+//! [`File`]s:
//!
//! ```
//! use std::io;
//! # }
//! ```
//!
-//! Note that you cannot use the `?` operator in functions that do not return
-//! a `Result<T, E>` (e.g. `main`). Instead, you can call `.unwrap()` or `match`
-//! on the return value to catch any possible errors:
+//! Note that you cannot use the [`?` operator] in functions that do not return
+//! a [`Result<T, E>`][`Result`] (e.g. `main`). Instead, you can call [`.unwrap()`]
+//! or `match` on the return value to catch any possible errors:
//!
//! ```
//! use std::io;
//! [`io::Result`]: type.Result.html
//! [`?` operator]: ../../book/first-edition/syntax-index.html
//! [`Read::read`]: trait.Read.html#tymethod.read
+//! [`Result`]: ../result/enum.Result.html
+//! [`.unwrap()`]: ../result/enum.Result.html#method.unwrap
#![stable(feature = "rust1", since = "1.0.0")]
///
/// 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;
///
/// 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:
/// 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;
/// 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
/// 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 {
/// 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
///
/// # 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;
/// # 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
///
/// # 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;
#[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
/// [`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;
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
///
/// # 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)]
/// 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;
/// # Examples
///
/// ```
- /// #![feature(more_io_inner_methods)]
- ///
/// # use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// # Ok(())
/// # }
/// ```
- #[unstable(feature = "more_io_inner_methods", issue="41519")]
+ #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
pub fn into_inner(self) -> (T, U) {
(self.first, self.second)
}
/// # Examples
///
/// ```
- /// #![feature(more_io_inner_methods)]
- ///
/// # use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// # Ok(())
/// # }
/// ```
- #[unstable(feature = "more_io_inner_methods", issue="41519")]
+ #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
pub fn get_ref(&self) -> (&T, &U) {
(&self.first, &self.second)
}
/// # Examples
///
/// ```
- /// #![feature(more_io_inner_methods)]
- ///
/// # use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// # Ok(())
/// # }
/// ```
- #[unstable(feature = "more_io_inner_methods", issue="41519")]
+ #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
pub fn get_mut(&mut self) -> (&mut T, &mut U) {
(&mut self.first, &mut self.second)
}
#[stable(feature = "rust1", since = "1.0.0")]
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
+ ///
+ /// ```
+ /// #![feature(take_set_limit)]
+ /// use std::io;
+ /// use std::io::prelude::*;
+ /// use std::fs::File;
+ ///
+ /// # fn foo() -> 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(())
+ /// # }
+ /// ```
+ #[unstable(feature = "take_set_limit", issue = "42781")]
+ pub fn set_limit(&mut self, limit: u64) {
+ self.limit = limit;
+ }
+
/// Consumes the `Take`, returning the wrapped reader.
///
/// # Examples
/// # Examples
///
/// ```
- /// #![feature(more_io_inner_methods)]
- ///
/// use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// # Ok(())
/// # }
/// ```
- #[unstable(feature = "more_io_inner_methods", issue="41519")]
+ #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
pub fn get_ref(&self) -> &T {
&self.inner
}
/// # Examples
///
/// ```
- /// #![feature(more_io_inner_methods)]
- ///
/// use std::io;
/// use std::io::prelude::*;
/// use std::fs::File;
/// # Ok(())
/// # }
/// ```
- #[unstable(feature = "more_io_inner_methods", issue="41519")]
+ #[stable(feature = "more_io_inner_methods", since = "1.20.0")]
pub fn get_mut(&mut self) -> &mut T {
&mut self.inner
}
projects / rust.git / blobdiff