From 1f9a8a1620a677d668c981a8e6be3ce02ef06cd5 Mon Sep 17 00:00:00 2001 From: Camelid Date: Thu, 5 Nov 2020 00:44:42 -0800 Subject: [PATCH 1/4] Add a `std::io::read_to_string` function The equivalent of `std::fs::read_to_string`, but generalized to all `Read` impls. As the documentation on `std::io::read_to_string` says, the advantage of this function is that it means you don't have to create a variable first and it provides more type safety since you can only get the buffer out if there were no errors. If you use `Read::read_to_string`, you have to remember to check whether the read succeeded because otherwise your buffer will be empty. It's friendlier to newcomers and better in most cases to use an explicit return value instead of an out parameter. --- library/std/src/io/mod.rs | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index dfbf6c3f24443..7a1896e4e5901 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -945,6 +945,33 @@ pub trait Read { } } +/// Convenience function for [`Read::read_to_string`]. +/// +/// This avoids having to create a variable first and it provides more type safety +/// since you can only get the buffer out if there were no errors. (If you use +/// [`Read::read_to_string`] you have to remember to check whether the read succeeded +/// because otherwise your buffer will be empty.) +/// +/// # Examples +/// +/// ```no_run +/// #![feature(io_read_to_string)] +/// +/// # use std::io; +/// fn main() -> io::Result<()> { +/// let stdin = io::read_to_string(&mut io::stdin())?; +/// println!("Stdin was:"); +/// println!("{}", stdin); +/// Ok(()) +/// } +/// ``` +#[unstable(feature = "io_read_to_string", issue = "80218")] +pub fn read_to_string(reader: &mut R) -> Result { + let mut buf = String::new(); + reader.read_to_string(&mut buf)?; + Ok(buf) +} + /// A buffer type used with `Read::read_vectored`. /// /// It is semantically a wrapper around an `&mut [u8]`, but is guaranteed to be From 4ee6d1bf541a90206b9e5cba6840e774493abc57 Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 30 Dec 2020 11:33:06 -0800 Subject: [PATCH 2/4] Add description independent of `Read::read_to_string` --- library/std/src/io/mod.rs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index 7a1896e4e5901..1fdd82400d061 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -945,12 +945,13 @@ pub trait Read { } } -/// Convenience function for [`Read::read_to_string`]. +/// Read all bytes from a [reader][Read] into a new [`String`]. /// -/// This avoids having to create a variable first and it provides more type safety -/// since you can only get the buffer out if there were no errors. (If you use -/// [`Read::read_to_string`] you have to remember to check whether the read succeeded -/// because otherwise your buffer will be empty.) +/// This is a convenience function for [`Read::read_to_string`]. Using this +/// function avoids having to create a variable first and provides more type +/// safety since you can only get the buffer out if there were no errors. (If you +/// use [`Read::read_to_string`] you have to remember to check whether the read +/// succeeded because otherwise your buffer will be empty.) /// /// # Examples /// From 588786a788a5606dd3f4b4769ecd2e0c26a3ad20 Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 30 Dec 2020 11:44:03 -0800 Subject: [PATCH 3/4] Add error docs --- library/std/src/io/mod.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index 1fdd82400d061..fdc0198945ef9 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -951,7 +951,14 @@ pub trait Read { /// function avoids having to create a variable first and provides more type /// safety since you can only get the buffer out if there were no errors. (If you /// use [`Read::read_to_string`] you have to remember to check whether the read -/// succeeded because otherwise your buffer will be empty.) +/// succeeded because otherwise your buffer will be empty or only partially full.) +/// +/// # Errors +/// +/// This function forces you to handle errors because the output (the `String`) +/// is wrapped in a [`Result`]. See [`Read::read_to_string`] for the errors +/// that can occur. If any error occurs, you will get an [`Err`], so you +/// don't have to worry about your buffer being empty or partially full. /// /// # Examples /// From 746329201546d38875bf1a7fa232453e833c01eb Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 11 Jan 2021 19:17:13 -0800 Subject: [PATCH 4/4] Add docs on performance --- library/std/src/io/mod.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index fdc0198945ef9..5540891c646d5 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -953,6 +953,19 @@ pub trait Read { /// use [`Read::read_to_string`] you have to remember to check whether the read /// succeeded because otherwise your buffer will be empty or only partially full.) /// +/// # Performance +/// +/// The downside of this function's increased ease of use and type safety is +/// that it gives you less control over performance. For example, you can't +/// pre-allocate memory like you can using [`String::with_capacity`] and +/// [`Read::read_to_string`]. Also, you can't re-use the buffer if an error +/// occurs while reading. +/// +/// In many cases, this function's performance will be adequate and the ease of use +/// and type safety tradeoffs will be worth it. However, there are cases where you +/// need more control over performance, and in those cases you should definitely use +/// [`Read::read_to_string`] directly. +/// /// # Errors /// /// This function forces you to handle errors because the output (the `String`)