Add more examples and documentation for std::fs
This commit is contained in:
Steve Klabnik
parent
d528aa9960
commit
187355178b
348
src/libstd/fs.rs
348
src/libstd/fs.rs
@ -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();
|
||||
|
||||
Loading…
Reference in New Issue
Block a user