diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 4f97ae8f69b..8ffeeea9d57 100644 --- a/src/libstd/fs.rs +++ b/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>(&self, path: P) -> io::Result { 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>(path: P) -> io::Result<()> { fs_imp::unlink(path.as_ref()) @@ -504,7 +704,7 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// /// # Examples /// -/// ```rust,no_run +/// ```rust /// # fn foo() -> std::io::Result<()> { /// use std::fs; /// @@ -526,20 +726,23 @@ pub fn metadata>(path: P) -> io::Result { /// 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, Q: AsRef>(from: P, to: Q) -> io::Result<()> { fs_imp::rename(from.as_ref(), to.as_ref()) @@ -553,14 +756,6 @@ pub fn rename, Q: AsRef>(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, Q: AsRef>(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, Q: AsRef>(from: P, to: Q) -> io::Result { let from = from.as_ref(); @@ -592,6 +795,17 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// /// 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, Q: AsRef>(src: P, dst: Q) -> io::Result<()> { fs_imp::link(src.as_ref(), dst.as_ref()) @@ -600,6 +814,17 @@ pub fn hard_link, Q: AsRef>(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, Q: AsRef>(src: P, dst: Q) -> io::Result<()> { fs_imp::symlink(src.as_ref(), dst.as_ref()) @@ -612,6 +837,17 @@ pub fn soft_link, Q: AsRef>(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>(path: P) -> io::Result { fs_imp::readlink(path.as_ref()) @@ -619,18 +855,21 @@ pub fn read_link>(path: P) -> io::Result { /// 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>(path: P) -> io::Result<()> { fs_imp::mkdir(path.as_ref()) @@ -645,6 +884,17 @@ pub fn create_dir>(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>(path: P) -> io::Result<()> { let path = path.as_ref(); @@ -655,18 +905,21 @@ pub fn create_dir_all>(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>(path: P) -> io::Result<()> { fs_imp::rmdir(path.as_ref()) @@ -680,7 +933,18 @@ pub fn remove_dir>(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>(path: P) -> io::Result<()> { let path = path.as_ref();