From 746329201546d38875bf1a7fa232453e833c01eb Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 11 Jan 2021 19:17:13 -0800 Subject: [PATCH] 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 fdc0198945ef..5540891c646d 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`)