Update mod.rs

library/std/src/io/mod.rs

@@ -917,6 +917,17 @@ pub trait Read {
     /// # }
     /// ```
     ///
+    /// # Usage Notes
+    ///
+    /// `read_to_end` attempts to read a source until EOF, but many sources are continuous streams
+    /// that do not send EOF. In these cases, `read_to_end` will block indefinitely. Standard input
+    /// is one such stream which may be finite if piped, but is typically continuous. For example,
+    /// `cat <file> | <my_rust_program>` will correctly terminate with an `EOF` upon closure of cat.
+    /// `yes "Data" | pv | <my_rust_program` or `tail -f <file> | <my_rust_program>` may not close
+    /// the stream or insert an `EOF` termination character.
+    ///
+    /// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
+    ///
     /// [`Vec::try_reserve`]: crate::vec::Vec::try_reserve
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize> {
@@ -960,6 +971,17 @@ pub trait Read {
     /// (See also the [`std::fs::read_to_string`] convenience function for
     /// reading from a file.)
     ///
+    /// # Usage Notes
+    ///
+    /// `read_to_string` attempts to read a source until EOF, but many sources are continuous streams
+    /// that do not send EOF. In these cases, `read_to_string` will block indefinitely. Standard input
+    /// is one such stream which may be finite if piped, but is typically continuous. For example,
+    /// `cat <file> | <my_rust_program>` will correctly terminate with an `EOF` upon closure of cat.
+    /// `yes "Data" | pv | <my_rust_program` or `tail -f <file> | <my_rust_program>` may not close
+    /// the stream or insert an `EOF` termination character.
+    ///
+    /// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
+    ///
     /// [`std::fs::read_to_string`]: crate::fs::read_to_string
     #[stable(feature = "rust1", since = "1.0.0")]
     fn read_to_string(&mut self, buf: &mut String) -> Result<usize> {
@@ -1262,6 +1284,17 @@ pub trait Read {
 ///     Ok(())
 /// }
 /// ```
+///
+/// # Usage Notes
+///
+/// `read_to_string` attempts to read a source until EOF, but many sources are continuous streams
+/// that do not send EOF. In these cases, `read_to_string` will block indefinitely. Standard input
+/// is one such stream which may be finite if piped, but is typically continuous. For example,
+/// `cat <file> | <my_rust_program>` will correctly terminate with an `EOF` upon closure of cat.
+/// `yes "Data" | pv | <my_rust_program` or `tail -f <file> | <my_rust_program>` may not close
+/// the stream or insert an `EOF` termination character.
+///
+/// Using `.lines()` with a [`BufReader`] or using [`read`] can provide a better solution
 #[stable(feature = "io_read_to_string", since = "1.65.0")]
 pub fn read_to_string<R: Read>(mut reader: R) -> Result<String> {
     let mut buf = String::new();