Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing links and examples for path modules and structs #38946

Merged
merged 1 commit into from
Jan 14, 2017
Merged

Add missing links and examples for path modules and structs #38946

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 95 additions & 22 deletions src/libstd/path.rs
View file
Open in desktop
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};
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unused import: PathBuf

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unused import: PathBuf

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is used.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(certainly github bug actually)

///
/// 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