diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index fc26dcb321148..1c7efd2f5320a 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -29,7 +29,7 @@ use crate::time::SystemTime; /// /// # Examples /// -/// Creates a new file and write bytes to it: +/// Creates a new file and write bytes to it (you can also use [`write`]): /// /// ```no_run /// use std::fs::File; @@ -42,7 +42,7 @@ use crate::time::SystemTime; /// } /// ``` /// -/// Read the contents of a file into a [`String`]: +/// Read the contents of a file into a [`String`] (you can also use [`read`]): /// /// ```no_run /// use std::fs::File; @@ -89,6 +89,8 @@ use crate::time::SystemTime; /// [`Write`]: ../io/trait.Write.html /// [`BufReader`]: ../io/struct.BufReader.html /// [`sync_all`]: struct.File.html#method.sync_all +/// [`read`]: fn.read.html +/// [`write`]: fn.write.html #[stable(feature = "rust1", since = "1.0.0")] pub struct File { inner: fs_imp::File, @@ -397,6 +399,37 @@ impl File { OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref()) } + /// Returns a new OpenOptions object. + /// + /// This function returns a new OpenOptions object that you can use to + /// open or create a file with specific options if `open()` or `create()` + /// are not appropriate. + /// + /// It is equivalent to `OpenOptions::new()` but allows you to write more + /// readable code. Instead of `OpenOptions::new().read(true).open("foo.txt")` + /// you can write `File::with_options().read(true).open("foo.txt"). This + /// also avoids the need to import `OpenOptions`. + /// + /// See the [`OpenOptions::new`] function for more details. + /// + /// [`OpenOptions::new`]: struct.OpenOptions.html#method.new + /// + /// # Examples + /// + /// ```no_run + /// #![feature(with_options)] + /// use std::fs::File; + /// + /// fn main() -> std::io::Result<()> { + /// let mut f = File::with_options().read(true).open("foo.txt")?; + /// Ok(()) + /// } + /// ``` + #[unstable(feature = "with_options", issue = "65439")] + pub fn with_options() -> OpenOptions { + OpenOptions::new() + } + /// Attempts to sync all OS-internal metadata to disk. /// /// This function will attempt to ensure that all in-memory data reaches the