Tracking Issue for `std::io::read_to_string`

[camelid]

Feature gate: #![feature(io_read_to_string)]

This is a tracking issue for the 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.

Public API

pub fn read_to_string<R: Read>(reader: R) -> Result<String>;

Steps / History

• Implementation: Add a std::io::read_to_string function #80217
• FCP
• Stabilization PR (Stabilize std::io::read_to_string #100337)

Unresolved Questions

• Function signature (Remove &mut from io::read_to_string signature #92863)

[kartva]

What is the status on stabilizing this addition to the library?

[fee1-dead]

@m-ou-se / @rust-lang/libs

Can we start an FCP?

[m-ou-se]

Thinking a bit about the signature: Considering Read is already implemented for &mut impl Read, shouldn't this function just take an R instead of &mut R?

[camelid]

Thinking a bit about the signature: Considering Read is already implemented for &mut impl Read, shouldn't this function just take an R instead of &mut R?

I modeled it after Read::read_to_string, which takes an &mut self, but that has to use &mut self because it's defined as part of the trait. I don't know enough about the idiom for std here, so if that works, it seems okay to me.

[jkugelman]

I'm working on a related PR #89582 to have File::read_to_string enlarge the string buffer before reading to accommodate the full file size. A nice side effect is that it will make io::read_to_string more performant when the reader is a file.

If it lands do you think there's anything in this comment that should be updated?

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.

[camelid]

I'm working on a related PR #89582 to have File::read_to_string enlarge the string buffer before reading to accommodate the full file size. A nice side effect is that it will make io::read_to_string more performant when the reader is a file.

That's great; thanks for working on this!

If it lands do you think there's anything in this comment that should be updated?

Perhaps we could add another paragraph at the end like this:

Note that in some special cases, such as when reading files, this function will pre-allocate memory based on the size of the input is reading. In those cases, the performance should be as good as if you had used Read::read_to_string() with a manually pre-allocated buffer.

[jkugelman]

Done.

[jkugelman]

It seems like std::io::read_to_string should be paired with a std::io::read_to_end method to match the other pairings in the standard library:

• Read::read_to_end + Read::read_to_string
• fs::read + fs::read_to_string

Would it be read or read_to_end? I'd say read_to_end to match the Read trait since the reader might not be at the beginning.