From b6fb3e34117008f7f97094b0f1521116a4e66473 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Fri, 29 Mar 2019 09:30:08 -0700 Subject: [PATCH] In doc examples, don't ignore read/write results Calling `Read::read` or `Write::write` without checking the returned `usize` value is almost always an error. Example code in the documentation should demonstrate how to use the return value correctly. Otherwise, people might copy the example code thinking that it is okay to "fire and forget" these methods. --- src/libstd/io/mod.rs | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 14c850b6b0547..14a16f3fc0f04 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -24,9 +24,9 @@ //! let mut buffer = [0; 10]; //! //! // read up to 10 bytes -//! f.read(&mut buffer)?; +//! let n = f.read(&mut buffer)?; //! -//! println!("The bytes: {:?}", buffer); +//! println!("The bytes: {:?}", &buffer[..n]); //! Ok(()) //! } //! ``` @@ -56,9 +56,9 @@ //! f.seek(SeekFrom::End(-10))?; //! //! // read up to 10 bytes -//! f.read(&mut buffer)?; +//! let n = f.read(&mut buffer)?; //! -//! println!("The bytes: {:?}", buffer); +//! println!("The bytes: {:?}", &buffer[..n]); //! Ok(()) //! } //! ``` @@ -537,7 +537,9 @@ pub trait Read { /// let mut buffer = [0; 10]; /// /// // read up to 10 bytes - /// f.read(&mut buffer[..])?; + /// let n = f.read(&mut buffer[..])?; + /// + /// println!("The bytes: {:?}", &buffer[..n]); /// Ok(()) /// } /// ``` @@ -1062,12 +1064,23 @@ impl Initializer { /// use std::fs::File; /// /// fn main() -> std::io::Result<()> { +/// let data = b"some bytes"; +/// +/// let mut pos = 0; /// let mut buffer = File::create("foo.txt")?; /// -/// buffer.write(b"some bytes")?; +/// while pos < data.len() { +/// let bytes_written = buffer.write(&data[pos..])?; +/// pos += bytes_written; +/// } /// Ok(()) /// } /// ``` +/// +/// The trait also provides convenience methods like [`write_all`], which calls +/// `write` in a loop until its entire input has been written. +/// +/// [`write_all`]: #method.write_all #[stable(feature = "rust1", since = "1.0.0")] #[doc(spotlight)] pub trait Write {