-
Notifications
You must be signed in to change notification settings - Fork 13.6k
Closed
Labels
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-enhancementCategory: An issue proposing an enhancement or a PR with one.Category: An issue proposing an enhancement or a PR with one.T-libsRelevant to the library team, which will review and decide on the PR/issue.Relevant to the library team, which will review and decide on the PR/issue.
Description
rust/library/std/src/io/mod.rs
Lines 1886 to 1926 in a55748f
#[stable(feature = "rust1", since = "1.0.0")] | |
pub trait BufRead: Read { | |
/// Returns the contents of the internal buffer, filling it with more data | |
/// from the inner reader if it is empty. | |
/// | |
/// This function is a lower-level call. It needs to be paired with the | |
/// [`consume`] method to function properly. When calling this | |
/// method, none of the contents will be "read" in the sense that later | |
/// calling `read` may return the same contents. As such, [`consume`] must | |
/// be called with the number of bytes that are consumed from this buffer to | |
/// ensure that the bytes are never returned twice. | |
/// | |
/// [`consume`]: BufRead::consume | |
/// | |
/// An empty buffer returned indicates that the stream has reached EOF. | |
/// | |
/// # Errors | |
/// | |
/// This function will return an I/O error if the underlying reader was | |
/// read, but returned an error. | |
/// | |
/// # Examples | |
/// | |
/// A locked standard input implements `BufRead`: | |
/// | |
/// ```no_run | |
/// use std::io; | |
/// use std::io::prelude::*; | |
/// | |
/// let stdin = io::stdin(); | |
/// let mut stdin = stdin.lock(); | |
/// | |
/// let buffer = stdin.fill_buf().unwrap(); | |
/// | |
/// // work with buffer | |
/// println!("{:?}", buffer); | |
/// | |
/// // ensure the bytes we worked with aren't returned again later | |
/// let length = buffer.len(); | |
/// stdin.consume(length); | |
/// ``` |
The doc states thatfill_buf()
needs to be paired with consume()
to function properly, which can be comprehended to imply that if consume()
is not called immediately after fill_buf()
it would cause undefined behavior.
Also, it is said that later calling read
may return the same contents. It's confusing that may is used instead of will here, and this confuses the reader to a deeper level.
Metadata
Metadata
Assignees
Labels
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-enhancementCategory: An issue proposing an enhancement or a PR with one.Category: An issue proposing an enhancement or a PR with one.T-libsRelevant to the library team, which will review and decide on the PR/issue.Relevant to the library team, which will review and decide on the PR/issue.