Skip to content

Commit

Permalink
Rollup merge of #108094 - kornelski:fsdocs, r=cuviper
Browse files Browse the repository at this point in the history
Demonstrate I/O in File examples

I've noticed that some Rust novices unnecessarily reinvent `std::fs::{read,write}`, presumably because they search for equivalents of `fopen` + `fwrite`. I've added links to `std::fs::{read,write}` in the docs.

The `File` examples were only showing how to open a file, but not how to use the opened handle, unnecessarily leaving out the next step. I've added a variety of different uses of file handles to their examples in docs.
  • Loading branch information
matthiaskrgr authored Feb 15, 2023
2 parents 863cd15 + 4c2d48e commit 5547101
Showing 1 changed file with 19 additions and 1 deletion.
20 changes: 19 additions & 1 deletion library/std/src/fs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,10 @@ impl File {
///
/// See the [`OpenOptions::open`] method for more details.
///
/// If you only need to read the entire file contents,
/// consider [`std::fs::read()`][self::read] or
/// [`std::fs::read_to_string()`][self::read_to_string] instead.
///
/// # Errors
///
/// This function will return an error if `path` does not already exist.
Expand All @@ -343,9 +347,12 @@ impl File {
///
/// ```no_run
/// use std::fs::File;
/// use std::io::Read;
///
/// fn main() -> std::io::Result<()> {
/// let mut f = File::open("foo.txt")?;
/// let mut data = vec![];
/// f.read_to_end(&mut data)?;
/// Ok(())
/// }
/// ```
Expand All @@ -361,16 +368,20 @@ impl File {
///
/// Depending on the platform, this function may fail if the
/// full directory path does not exist.
///
/// See the [`OpenOptions::open`] function for more details.
///
/// See also [`std::fs::write()`][self::write] for a simple function to
/// create a file with a given data.
///
/// # Examples
///
/// ```no_run
/// use std::fs::File;
/// use std::io::Write;
///
/// fn main() -> std::io::Result<()> {
/// let mut f = File::create("foo.txt")?;
/// f.write_all(&1234_u32.to_be_bytes())?;
/// Ok(())
/// }
/// ```
Expand All @@ -397,9 +408,11 @@ impl File {
/// #![feature(file_create_new)]
///
/// use std::fs::File;
/// use std::io::Write;
///
/// fn main() -> std::io::Result<()> {
/// let mut f = File::create_new("foo.txt")?;
/// f.write_all("Hello, world!".as_bytes())?;
/// Ok(())
/// }
/// ```
Expand All @@ -426,9 +439,11 @@ impl File {
///
/// ```no_run
/// use std::fs::File;
/// use std::io::Write;
///
/// fn main() -> std::io::Result<()> {
/// let mut f = File::options().append(true).open("example.log")?;
/// writeln!(&mut f, "new line")?;
/// Ok(())
/// }
/// ```
Expand Down Expand Up @@ -966,6 +981,9 @@ impl OpenOptions {
/// In order for the file to be created, [`OpenOptions::write`] or
/// [`OpenOptions::append`] access must be used.
///
/// See also [`std::fs::write()`][self::write] for a simple function to
/// create a file with a given data.
///
/// # Examples
///
/// ```no_run
Expand Down

0 comments on commit 5547101

Please sign in to comment.