Add more examples and documentation for std::fs

This commit is contained in:
Steve Klabnik 2015-03-31 23:47:50 -04:00
parent d528aa9960
commit 187355178b

View file

@ -96,10 +96,41 @@ pub struct WalkDir {
/// Options and flags which can be used to configure how a file is opened.
///
/// This builder exposes the ability to configure how a `File` is opened and
/// what operations are permitted on the open file. The `File::open` and
/// `File::create` methods are aliases for commonly used options using this
/// builder.
/// This builder exposes the ability to configure how a `File` is opened and what operations are
/// permitted on the open file. The `File::open` and `File::create` methods are aliases for
/// commonly used options using this builder.
///
/// Generally speaking, when using `OpenOptions`, you'll first call `new()`, then chain calls to
/// methods to set each option, then call `open()`, passing the path of the file you're trying to
/// open. This will give you a [`io::Result`][result] with a [`File`][file] inside that you can
/// further operate on.
///
/// [result]: ../io/type.Result.html
/// [file]: struct.File.html
///
/// # Examples
///
/// Opening a file to read:
///
/// ```no_run
/// use std::fs;
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().read(true).open("foo.txt");
/// ```
///
/// Opening a file for both reading and writing, as well as creating it if it doesn't exist:
///
/// ```
/// use std::fs;
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new()
/// .read(true)
/// .write(true)
/// .create(true)
/// .open("foo.txt");
/// ```
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct OpenOptions(fs_imp::OpenOptions);
@ -317,6 +348,14 @@ impl OpenOptions {
/// Creates a blank net set of options ready for configuration.
///
/// All options are initially set to `false`.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new() -> OpenOptions {
OpenOptions(fs_imp::OpenOptions::new())
@ -326,6 +365,14 @@ pub fn new() -> OpenOptions {
///
/// This option, when true, will indicate that the file should be
/// `read`-able if opened.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().read(true).open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read(&mut self, read: bool) -> &mut OpenOptions {
self.0.read(read); self
@ -335,6 +382,14 @@ pub fn read(&mut self, read: bool) -> &mut OpenOptions {
///
/// This option, when true, will indicate that the file should be
/// `write`-able if opened.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().write(true).open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn write(&mut self, write: bool) -> &mut OpenOptions {
self.0.write(write); self
@ -344,6 +399,14 @@ pub fn write(&mut self, write: bool) -> &mut OpenOptions {
///
/// This option, when true, means that writes will append to a file instead
/// of overwriting previous contents.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().append(true).open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn append(&mut self, append: bool) -> &mut OpenOptions {
self.0.append(append); self
@ -353,6 +416,14 @@ pub fn append(&mut self, append: bool) -> &mut OpenOptions {
///
/// If a file is successfully opened with this option set it will truncate
/// the file to 0 length if it already exists.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().truncate(true).open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn truncate(&mut self, truncate: bool) -> &mut OpenOptions {
self.0.truncate(truncate); self
@ -362,6 +433,14 @@ pub fn truncate(&mut self, truncate: bool) -> &mut OpenOptions {
///
/// This option indicates whether a new file will be created if the file
/// does not yet already exist.
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().create(true).open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create(&mut self, create: bool) -> &mut OpenOptions {
self.0.create(create); self
@ -378,6 +457,14 @@ pub fn create(&mut self, create: bool) -> &mut OpenOptions {
/// * Attempting to open a file with access that the user lacks
/// permissions for
/// * Filesystem-level errors (full disk, etc)
///
/// # Examples
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().open("foo.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
let path = path.as_ref();
@ -392,18 +479,70 @@ fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions { &mut self.0 }
impl Metadata {
/// Returns whether this metadata is for a directory.
///
/// # Examples
///
/// ```
/// # fn foo() -> std::io::Result<()> {
/// use std::fs;
///
/// let metadata = try!(fs::metadata("foo.txt"));
///
/// assert!(!metadata.is_dir());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_dir(&self) -> bool { self.0.is_dir() }
/// Returns whether this metadata is for a regular file.
///
/// # Examples
///
/// ```
/// # fn foo() -> std::io::Result<()> {
/// use std::fs;
///
/// let metadata = try!(fs::metadata("foo.txt"));
///
/// assert!(metadata.is_file());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_file(&self) -> bool { self.0.is_file() }
/// Returns the size of the file, in bytes, this metadata is for.
///
/// # Examples
///
/// ```
/// # fn foo() -> std::io::Result<()> {
/// use std::fs;
///
/// let metadata = try!(fs::metadata("foo.txt"));
///
/// assert_eq!(0, metadata.len());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> u64 { self.0.size() }
/// Returns the permissions of the file this metadata is for.
///
/// # Examples
///
/// ```
/// # fn foo() -> std::io::Result<()> {
/// use std::fs;
///
/// let metadata = try!(fs::metadata("foo.txt"));
///
/// assert!(!metadata.permissions().readonly());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn permissions(&self) -> Permissions {
Permissions(self.0.perm())
@ -430,6 +569,20 @@ pub fn modified(&self) -> u64 { self.0.modified() }
impl Permissions {
/// Returns whether these permissions describe a readonly file.
///
/// # Examples
///
/// ```
/// use std::fs::File;
///
/// # fn foo() -> std::io::Result<()> {
/// let mut f = try!(File::create("foo.txt"));
/// let metadata = try!(f.metadata());
///
/// assert_eq!(false, metadata.permissions().readonly());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn readonly(&self) -> bool { self.0.readonly() }
@ -437,6 +590,27 @@ pub fn readonly(&self) -> bool { self.0.readonly() }
///
/// This operation does **not** modify the filesystem. To modify the
/// filesystem use the `fs::set_permissions` function.
///
/// # Examples
///
/// ```
/// use std::fs::File;
///
/// # fn foo() -> std::io::Result<()> {
/// let mut f = try!(File::create("foo.txt"));
/// let metadata = try!(f.metadata());
/// let mut permissions = metadata.permissions();
///
/// permissions.set_readonly(true);
///
/// // filesystem doesn't change
/// assert_eq!(false, metadata.permissions().readonly());
///
/// // just this particular `permissions`.
/// assert_eq!(true, permissions.readonly());
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn set_readonly(&mut self, readonly: bool) {
self.0.set_readonly(readonly)
@ -468,20 +642,35 @@ impl DirEntry {
///
/// The full path is created by joining the original path to `read_dir` or
/// `walk_dir` with the filename of this entry.
///
/// # Examples
///
/// ```
/// use std::fs;
/// # fn foo() -> std::io::Result<()> {
/// for entry in try!(fs::read_dir(".")) {
/// let dir = try!(entry);
/// println!("{:?}", dir.path());
/// }
/// # Ok(())
/// # }
/// ```
///
/// This prints output like:
///
/// ```text
/// "./whatever.txt"
/// "./foo.html"
/// "./hello_world.rs"
/// ```
///
/// The exact text, of course, depends on what files you have in `.`.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn path(&self) -> PathBuf { self.0.path() }
}
/// Remove a file from the underlying filesystem.
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fs::remove_file("/some/file/path.txt");
/// ```
///
/// Note that, just because an unlink call was successful, it is not
/// guaranteed that a file is immediately deleted (e.g. depending on
/// platform, other open file descriptors may prevent immediate removal).
@ -491,6 +680,17 @@ pub fn path(&self) -> PathBuf { self.0.path() }
/// This function will return an error if `path` points to a directory, if the
/// user lacks permissions to remove the file, or if some other filesystem-level
/// error occurs.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::remove_file("a.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
fs_imp::unlink(path.as_ref())
@ -504,7 +704,7 @@ pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
///
/// # Examples
///
/// ```rust,no_run
/// ```rust
/// # fn foo() -> std::io::Result<()> {
/// use std::fs;
///
@ -526,20 +726,23 @@ pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
/// Rename a file or directory to a new name.
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fs::rename("foo", "bar");
/// ```
///
/// # Errors
///
/// This function will return an error if the provided `from` doesn't exist, if
/// the process lacks permissions to view the contents, if `from` and `to`
/// reside on separate filesystems, or if some other intermittent I/O error
/// occurs.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::rename("a.txt", "b.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
fs_imp::rename(from.as_ref(), to.as_ref())
@ -553,14 +756,6 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
/// Note that if `from` and `to` both point to the same file, then the file
/// will likely get truncated by this operation.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// fs::copy("foo.txt", "bar.txt");
/// ```
///
/// # Errors
///
/// This function will return an error in the following situations, but is not
@ -570,6 +765,14 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
/// * The `from` file does not exist
/// * The current process does not have the permission rights to access
/// `from` or write `to`
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fs::copy("foo.txt", "bar.txt");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
let from = from.as_ref();
@ -592,6 +795,17 @@ pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
///
/// The `dst` path will be a link pointing to the `src` path. Note that systems
/// often require these two paths to both be located on the same filesystem.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::hard_link("a.txt", "b.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
fs_imp::link(src.as_ref(), dst.as_ref())
@ -600,6 +814,17 @@ pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<(
/// Creates a new soft link on the filesystem.
///
/// The `dst` path will be a soft link pointing to the `src` path.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::soft_link("a.txt", "b.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
fs_imp::symlink(src.as_ref(), dst.as_ref())
@ -612,6 +837,17 @@ pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<(
/// This function will return an error on failure. Failure conditions include
/// reading a file that does not exist or reading a file that is not a soft
/// link.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// let path = try!(fs::read_link("a.txt"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
fs_imp::readlink(path.as_ref())
@ -619,18 +855,21 @@ pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
/// Create a new, empty directory at the provided path
///
/// # Errors
///
/// This function will return an error if the user lacks permissions to make a
/// new directory at the provided `path`, or if the directory already exists.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// fs::create_dir("/some/dir");
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::create_dir("/some/dir"));
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// This function will return an error if the user lacks permissions to make a
/// new directory at the provided `path`, or if the directory already exists.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
fs_imp::mkdir(path.as_ref())
@ -645,6 +884,17 @@ pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
/// does not already exist and it could not be created otherwise. The specific
/// error conditions for when a directory is being created (after it is
/// determined to not exist) are outlined by `fs::create_dir`.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::create_dir_all("/some/dir"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
let path = path.as_ref();
@ -655,18 +905,21 @@ pub fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
/// Remove an existing, empty directory
///
/// # Errors
///
/// This function will return an error if the user lacks permissions to remove
/// the directory at the provided `path`, or if the directory isn't empty.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// fs::remove_dir("/some/dir");
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::remove_dir("/some/dir"));
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// This function will return an error if the user lacks permissions to remove
/// the directory at the provided `path`, or if the directory isn't empty.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
fs_imp::rmdir(path.as_ref())
@ -680,7 +933,18 @@ pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
///
/// # Errors
///
/// See `file::remove_file` and `fs::remove_dir`
/// See `file::remove_file` and `fs::remove_dir`.
///
/// # Examples
///
/// ```
/// use std::fs;
///
/// # fn foo() -> std::io::Result<()> {
/// try!(fs::remove_dir_all("/some/dir"));
/// # Ok(())
/// # }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
let path = path.as_ref();