From 7d9822a7228aec80c86aa8f66224fc7e030019bb Mon Sep 17 00:00:00 2001 From: Sekar-C-Mca Date: Fri, 2 Jan 2026 11:59:16 +0530 Subject: [PATCH] Clarify BufRead::fill_buf doesn't consume data The previous documentation said 'via Read methods' which incorrectly implied that fill_buf consumes the data. This restores the historical clarification that read() can return the same contents as fill_buf, and emphasizes the relationship with consume(). This addresses the concerns raised in the issue where implementations like BufReader and Cursor do not actually consume data when fill_buf is called - subsequent read() calls can still read the same bytes until consume() is explicitly called. --- library/std/src/io/mod.rs | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index b7756befa11e9..deb35ef9f3f61 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -2346,10 +2346,19 @@ fn skip_until(r: &mut R, delim: u8) -> Result { #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "IoBufRead")] pub trait BufRead: Read { - /// Returns the contents of the internal buffer, filling it with more data, via `Read` methods, if empty. + /// Returns the contents of the internal buffer, filling it with more data from the underlying reader if it is empty. + /// + /// This function will not read data into the buffer if some is already present. + /// 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. + /// + /// [`read`]: Read::read + /// [`consume`]: BufRead::consume /// /// This is a lower-level method and is meant to be used together with [`consume`], - /// which can be used to mark bytes that should not be returned by subsequent calls to `read`. + /// which marks bytes as consumed so they will not be returned by subsequent calls to [`read`]. /// /// [`consume`]: BufRead::consume ///