Skip to content

Commit

Permalink
Add missing links and examples for path modules and structs
Browse files Browse the repository at this point in the history
  • Loading branch information
@GuillaumeGomez
GuillaumeGomez committed Jan 11, 2017
1 parent bd16aa0 commit 28d1ac3
Showing 1 changed file with 95 additions and 22 deletions.
117 changes: 95 additions & 22 deletions src/libstd/path.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,20 @@

//! 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
//!
//! 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;
//!
Expand All @@ -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:\\");
Expand Down Expand Up @@ -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")]

Expand Down Expand Up @@ -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> {
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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(());
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
Expand Down Expand Up @@ -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
///
/// ```
Expand All @@ -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
///
/// ```
Expand Down Expand Up @@ -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
Expand All @@ -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> {
fs::metadata(self)
Expand All @@ -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::Metadata> {
fs::symlink_metadata(self)
Expand All @@ -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<PathBuf> {
fs::canonicalize(self)
Expand All @@ -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<PathBuf> {
fs::read_link(self)
Expand All @@ -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::ReadDir> {
fs::read_dir(self)
Expand Down

0 comments on commit 28d1ac3

Please sign in to comment.