bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #38946 - GuillaumeGomez:path_doc, r=frewsxcv

Browse source 
Add missing links and examples for path modules and structs

r? @frewsxcv
This commit is contained in:
Guillaume Gomez 2017-01-13 10:42:28 +01:00 • committed by GitHub
commit 54535c59a4
1 changed files with 95 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

117
src/libstd/path.rs
View file

@ -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(());
@ -1539,7 +1552,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
///
@ -1570,7 +1585,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
///
@ -1608,8 +1625,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
///
@ -1689,11 +1709,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
///
/// ```
@ -1710,15 +1732,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
///
/// ```
@ -1877,7 +1900,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
@ -1886,6 +1908,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)
@ -1896,6 +1928,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)
@ -1907,6 +1949,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)
@ -1917,6 +1968,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)
@ -1932,6 +1992,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)