diff --git a/src/libstd/path.rs b/src/libstd/path.rs index d13baea40a9ff..14323c5203c2f 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -10,9 +10,9 @@ //! Cross-platform path manipulation. //! -//! This module provides two types, `PathBuf` and `Path` (akin to `String` and -//! `str`), for working with paths abstractly. These types are thin wrappers -//! around `OsString` and `OsStr` respectively, meaning that they work directly +//! This module provides two types, [`PathBuf`] and [`Path`][`Path`] (akin to [`String`] +//! and [`str`]), for working with paths abstractly. These types are thin wrappers +//! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly //! on strings according to the local platform's path syntax. //! //! ## Simple usage @@ -20,10 +20,10 @@ //! Path manipulation includes both parsing components from slices and building //! new owned paths. //! -//! To parse a path, you can create a `Path` slice from a `str` +//! To parse a path, you can create a [`Path`] slice from a [`str`] //! slice and start asking questions: //! -//! ```rust +//! ``` //! use std::path::Path; //! use std::ffi::OsStr; //! @@ -39,9 +39,9 @@ //! assert_eq!(extension, Some(OsStr::new("txt"))); //! ``` //! -//! To build or modify paths, use `PathBuf`: +//! To build or modify paths, use [`PathBuf`]: //! -//! ```rust +//! ``` //! use std::path::PathBuf; //! //! let mut path = PathBuf::from("c:\\"); @@ -103,6 +103,13 @@ //! that `b` is a symbolic link (so its parent isn't `a`). Further //! normalization is possible to build on top of the components APIs, //! and will be included in this library in the near future. +//! +//! [`PathBuf`]: ../../std/path/struct.PathBuf.html +//! [`Path`]: ../../std/path/struct.Path.html +//! [`String`]: ../../std/string/struct.String.html +//! [`str`]: ../../std/primitive.str.html +//! [`OsString`]: ../../std/ffi/struct.OsString.html +//! [`OsStr`]: ../../std/ffi/struct.OsStr.html #![stable(feature = "rust1", since = "1.0.0")] @@ -527,7 +534,9 @@ pub struct Components<'a> { back: State, } -/// An iterator over the components of a path, as `OsStr` slices. +/// An iterator over the components of a path, as [`OsStr`] slices. +/// +/// [`OsStr`]: ../../std/ffi/struct.OsStr.html #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a> { @@ -1089,10 +1098,11 @@ impl PathBuf { /// Updates [`self.file_name()`] to `file_name`. /// - /// If [`self.file_name()`] was `None`, this is equivalent to pushing + /// If [`self.file_name()`] was [`None`], this is equivalent to pushing /// `file_name`. /// /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -1124,11 +1134,12 @@ impl PathBuf { /// /// If [`self.file_name()`] is `None`, does nothing and returns `false`. /// - /// Otherwise, returns `true`; if [`self.extension()`] is `None`, the + /// Otherwise, returns `true`; if [`self.extension()`] is [`None`], the /// extension is added; otherwise it is replaced. /// /// [`self.file_name()`]: struct.PathBuf.html#method.file_name /// [`self.extension()`]: struct.PathBuf.html#method.extension + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -1356,8 +1367,10 @@ pub struct Path { inner: OsStr, } -/// An error returned from the `Path::strip_prefix` method indicating that the +/// An error returned from the [`Path::strip_prefix`] method indicating that the /// prefix was not found in `self`. +/// +/// [`Path::strip_prefix`]: struct.Path.html#method.strip_prefix #[derive(Debug, Clone, PartialEq, Eq)] #[stable(since = "1.7.0", feature = "strip_prefix")] pub struct StripPrefixError(()); @@ -1534,7 +1547,9 @@ impl Path { /// The path without its final component, if any. /// - /// Returns `None` if the path terminates in a root or prefix. + /// Returns [`None`] if the path terminates in a root or prefix. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -1565,7 +1580,9 @@ impl Path { /// The final component of the path, if it is a normal file. /// - /// If the path terminates in `..`, `file_name` will return `None`. + /// If the path terminates in `..`, `file_name` will return [`None`]. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -1603,8 +1620,11 @@ impl Path { /// /// # Errors /// - /// If `base` is not a prefix of `self` (i.e. `starts_with` - /// returns `false`), returns `Err`. + /// If `base` is not a prefix of `self` (i.e. [`starts_with`] + /// returns `false`), returns [`Err`]. + /// + /// [`starts_with`]: #method.starts_with + /// [`Err`]: ../../std/result/enum.Result.html#variant.Err /// /// # Examples /// @@ -1684,11 +1704,13 @@ impl Path { /// /// The stem is: /// - /// * None, if there is no file name; + /// * [`None`], if there is no file name; /// * The entire file name if there is no embedded `.`; /// * The entire file name if the file name begins with `.` and has no other `.`s within; /// * Otherwise, the portion of the file name before the final `.` /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1705,15 +1727,16 @@ impl Path { /// Extracts the extension of [`self.file_name()`], if possible. /// - /// [`self.file_name()`]: struct.Path.html#method.file_name - /// /// The extension is: /// - /// * None, if there is no file name; - /// * None, if there is no embedded `.`; - /// * None, if the file name begins with `.` and has no other `.`s within; + /// * [`None`], if there is no file name; + /// * [`None`], if there is no embedded `.`; + /// * [`None`], if the file name begins with `.` and has no other `.`s within; /// * Otherwise, the portion of the file name after the final `.` /// + /// [`self.file_name()`]: struct.Path.html#method.file_name + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// ``` @@ -1872,7 +1895,6 @@ impl Path { Display { path: self } } - /// Query the file system to get information about a file, directory, etc. /// /// This function will traverse symbolic links to query information about the @@ -1881,6 +1903,16 @@ impl Path { /// This is an alias to [`fs::metadata`]. /// /// [`fs::metadata`]: ../fs/fn.metadata.html + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// + /// let path = Path::new("/Minas/tirith"); + /// let metadata = path.metadata().expect("metadata call failed"); + /// println!("{:?}", metadata.file_type()); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn metadata(&self) -> io::Result { fs::metadata(self) @@ -1891,6 +1923,16 @@ impl Path { /// This is an alias to [`fs::symlink_metadata`]. /// /// [`fs::symlink_metadata`]: ../fs/fn.symlink_metadata.html + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// + /// let path = Path::new("/Minas/tirith"); + /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed"); + /// println!("{:?}", metadata.file_type()); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn symlink_metadata(&self) -> io::Result { fs::symlink_metadata(self) @@ -1902,6 +1944,15 @@ impl Path { /// This is an alias to [`fs::canonicalize`]. /// /// [`fs::canonicalize`]: ../fs/fn.canonicalize.html + /// + /// # Examples + /// + /// ```no_run + /// use std::path::{Path, PathBuf}; + /// + /// let path = Path::new("/foo/test/../test/bar.rs"); + /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs")); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn canonicalize(&self) -> io::Result { fs::canonicalize(self) @@ -1912,6 +1963,15 @@ impl Path { /// This is an alias to [`fs::read_link`]. /// /// [`fs::read_link`]: ../fs/fn.read_link.html + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// + /// let path = Path::new("/laputa/sky_castle.rs"); + /// let path_link = path.read_link().expect("read_link call failed"); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn read_link(&self) -> io::Result { fs::read_link(self) @@ -1927,6 +1987,19 @@ impl Path { /// [`io::Result`]: ../io/type.Result.html /// [`DirEntry`]: ../fs/struct.DirEntry.html /// [`fs::read_dir`]: ../fs/fn.read_dir.html + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// + /// let path = Path::new("/laputa"); + /// for entry in path.read_dir().expect("read_dir call failed") { + /// if let Ok(entry) = entry { + /// println!("{:?}", entry.path()); + /// } + /// } + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn read_dir(&self) -> io::Result { fs::read_dir(self)