From 85310860c25c8525c03b2ffe12674c1914917aa0 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Mon, 2 Apr 2018 09:10:44 -0700 Subject: Add performance note to fs::read docs --- src/libstd/fs.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 479e4d08f4b..7bd1adc411a 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -231,7 +231,9 @@ fn initial_buffer_size(file: &File) -> usize { /// Read the entire contents of a file into a bytes vector. /// /// This is a convenience function for using [`File::open`] and [`read_to_end`] -/// with fewer imports and without an intermediate variable. +/// with fewer imports and without an intermediate variable. It pre-allocates a +/// buffer based on the file size when available, so it is generally faster than +/// reading into a vector created with `Vec::new()`. /// /// [`File::open`]: struct.File.html#method.open /// [`read_to_end`]: ../io/trait.Read.html#method.read_to_end @@ -270,7 +272,9 @@ pub fn read>(path: P) -> io::Result> { /// Read the entire contents of a file into a string. /// /// This is a convenience function for using [`File::open`] and [`read_to_string`] -/// with fewer imports and without an intermediate variable. +/// with fewer imports and without an intermediate variable. It pre-allocates a +/// buffer based on the file size when available, so it is generally faster than +/// reading into a string created with `String::new()`. /// /// [`File::open`]: struct.File.html#method.open /// [`read_to_string`]: ../io/trait.Read.html#method.read_to_string -- cgit 1.4.1-3-g733a5 From a2a0f21ba1d2d0d54e8a34d39d7435cbb4efe7e9 Mon Sep 17 00:00:00 2001 From: Rolf van de Krol Date: Mon, 2 Apr 2018 21:48:56 +0200 Subject: Fix typo --- src/libstd/io/buffered.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs index cefff2f143c..3e9ae261ab6 100644 --- a/src/libstd/io/buffered.rs +++ b/src/libstd/io/buffered.rs @@ -180,7 +180,7 @@ impl BufReader { /// /// # Examples /// - /// ```no_ru + /// ```no_run /// # #![feature(bufreader_buffer)] /// use std::io::{BufReader, BufRead}; /// use std::fs::File; -- cgit 1.4.1-3-g733a5 From 9ab5788e0e73d1d7edbc025627e34bb8d4fa9bdd Mon Sep 17 00:00:00 2001 From: Thayne McCombs Date: Mon, 2 Apr 2018 19:34:06 -0600 Subject: Fix "since" version for getpid feature. It was stabilized right before the beta branch was cut for 1.26.0. See https://github.com/rust-lang/rust/pull/49523#issuecomment-377996315 --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index b463a6d88fe..40bc84f4bc1 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1426,7 +1426,7 @@ pub fn abort() -> ! { /// ``` /// /// -#[stable(feature = "getpid", since = "1.27.0")] +#[stable(feature = "getpid", since = "1.26.0")] pub fn id() -> u32 { ::sys::os::getpid() } -- cgit 1.4.1-3-g733a5 From 333b0a0471c2593e46c8f13124ee28178f5c9643 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 3 Apr 2018 09:20:04 -0400 Subject: tweak format_args! docs Swap the variable names in the example. --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 47609f17221..5ef7c159655 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -341,8 +341,8 @@ pub mod builtin { /// format string in `format_args!`. /// /// ```rust - /// let display = format!("{:?}", format_args!("{} foo {:?}", 1, 2)); - /// let debug = format!("{}", format_args!("{} foo {:?}", 1, 2)); + /// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2)); + /// let display = format!("{}", format_args!("{} foo {:?}", 1, 2)); /// assert_eq!("1 foo 2", display); /// assert_eq!(display, debug); /// ``` -- cgit 1.4.1-3-g733a5 From 1ce98f34d38fa9338ff696f904bcb8c01856f935 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Mon, 2 Apr 2018 09:11:07 -0700 Subject: Cross-reference fs::read functions from io::Read docs --- src/libstd/io/mod.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 63b631ace96..3b8c42ddb39 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -595,6 +595,11 @@ pub trait Read { /// Ok(()) /// } /// ``` + /// + /// (See also the [`std::fs::read`] convenience function for reading from a + /// file.) + /// + /// [`std::fs::read`]: ../fs/fn.read.html #[stable(feature = "rust1", since = "1.0.0")] fn read_to_end(&mut self, buf: &mut Vec) -> Result { read_to_end(self, buf) @@ -633,6 +638,11 @@ pub trait Read { /// Ok(()) /// } /// ``` + /// + /// (See also the [`std::fs::read_to_string`] convenience function for + /// reading from a file.) + /// + /// [`std::fs::read_to_string`]: ../fs/fn.read_to_string.html #[stable(feature = "rust1", since = "1.0.0")] fn read_to_string(&mut self, buf: &mut String) -> Result { // Note that we do *not* call `.read_to_end()` here. We are passing -- cgit 1.4.1-3-g733a5 From 390f8367e74d72317ab4aa5097048243073968fa Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Mon, 2 Apr 2018 09:31:04 -0700 Subject: Add performance notes to BufReader/BufWriter docs --- src/libstd/io/buffered.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs index cefff2f143c..91f07ecc663 100644 --- a/src/libstd/io/buffered.rs +++ b/src/libstd/io/buffered.rs @@ -25,6 +25,12 @@ use memchr; /// results in a system call. A `BufReader` performs large, infrequent reads on /// the underlying [`Read`] and maintains an in-memory buffer of the results. /// +/// `BufReader` can improve the speed of programs that make *small* and +/// *repeated* read calls to the same file or network socket. It does not +/// help when reading very large amounts at once, or reading just one or a few +/// times. It also provides no advantage when reading from a source that is +/// already in memory, like a `Vec`. +/// /// [`Read`]: ../../std/io/trait.Read.html /// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read /// [`TcpStream`]: ../../std/net/struct.TcpStream.html @@ -359,6 +365,12 @@ impl Seek for BufReader { /// `BufWriter` keeps an in-memory buffer of data and writes it to an underlying /// writer in large, infrequent batches. /// +/// `BufWriter` can improve the speed of programs that make *small* and +/// *repeated* write calls to the same file or network socket. It does not +/// help when writing very large amounts at once, or writing just one or a few +/// times. It also provides no advantage when writing to a destination that is +/// in memory, like a `Vec`. +/// /// When the `BufWriter` is dropped, the contents of its buffer will be written /// out. However, any errors that happen in the process of flushing the buffer /// when the writer is dropped will be ignored. Code that wishes to handle such -- cgit 1.4.1-3-g733a5 From 97ac479066a16d06ad4eb2cc2a4f58d1e7aa37b8 Mon Sep 17 00:00:00 2001 From: Thayne McCombs Date: Tue, 3 Apr 2018 19:47:37 -0600 Subject: Stabilize parent_id() Fixes #46104 --- src/libstd/sys/unix/ext/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/unix/ext/process.rs b/src/libstd/sys/unix/ext/process.rs index 60309bec6d4..7b4ec20d91f 100644 --- a/src/libstd/sys/unix/ext/process.rs +++ b/src/libstd/sys/unix/ext/process.rs @@ -193,7 +193,7 @@ impl IntoRawFd for process::ChildStderr { } /// Returns the OS-assigned process identifier associated with this process's parent. -#[unstable(feature = "unix_ppid", issue = "46104")] +#[stable(feature = "unix_ppid", since = "1.27.0")] pub fn parent_id() -> u32 { ::sys::os::getppid() } -- cgit 1.4.1-3-g733a5