Skip to content

Commit 1245178

Browse files
committed
Document that File does not buffer reads/writes, refer to BufReader/BufWriter
1 parent 57ad505 commit 1245178

File tree

1 file changed

+10
-3
lines changed

1 file changed

+10
-3
lines changed

library/std/src/fs.rs

+10-3
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ use crate::time::SystemTime;
3131
/// on closing are ignored by the implementation of `Drop`. Use the method
3232
/// [`sync_all`] if these errors must be manually handled.
3333
///
34+
/// `File` objects do not buffer reads and writes by default. For efficiency,
35+
/// consider wrapping the file in a [`BufReader`] or [`BufWriter`] when performing
36+
/// multiple [`read`] or [`write`] calls, unless unbuffered reads and writes
37+
/// are required.
38+
///
3439
/// # Examples
3540
///
3641
/// Creates a new file and write bytes to it (you can also use [`write()`]):
@@ -61,8 +66,7 @@ use crate::time::SystemTime;
6166
/// }
6267
/// ```
6368
///
64-
/// It can be more efficient to read the contents of a file with a buffered
65-
/// [`Read`]er. This can be accomplished with [`BufReader<R>`]:
69+
/// Using a buffered [`Read`]er:
6670
///
6771
/// ```no_run
6872
/// use std::fs::File;
@@ -93,8 +97,11 @@ use crate::time::SystemTime;
9397
/// perform synchronous I/O operations. Therefore the underlying file must not
9498
/// have been opened for asynchronous I/O (e.g. by using `FILE_FLAG_OVERLAPPED`).
9599
///
96-
/// [`BufReader<R>`]: io::BufReader
100+
/// [`BufReader`]: io::BufReader
101+
/// [`BufWriter`]: io::BufReader
97102
/// [`sync_all`]: File::sync_all
103+
/// [`write`]: File::write
104+
/// [`read`]: File::read
98105
#[stable(feature = "rust1", since = "1.0.0")]
99106
#[cfg_attr(not(test), rustc_diagnostic_item = "File")]
100107
pub struct File {

0 commit comments

Comments
 (0)