OpenE2K
/
rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Auto merge of #75293 - poliorcetics:intra-doc-links-std-path, r=jyn514 

Move to intra-doc links in library/std/src/path.rs

Helps with #75080.

@rustbot modify labels: T-doc, A-intra-doc-links, T-rustdoc

Known issue: The following links are broken (they are inside trait impls, undocumented in this file, inheriting from the original doc):

- [`Hasher`]
- [`Self`] (referencing `../primitive.slice.html`)
- [`Ordering`]
This commit is contained in:
bors 2020-08-09 12:31:03 +00:00
parent 8e738539be 6d77e40afe
commit 8bc801b050
1 changed files with 45 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
library/std/src/path.rs
View File

@ -56,16 +56,8 @@
//! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect();
//! ```
//!
//! [`Component`]: ../../std/path/enum.Component.html
//! [`components`]: ../../std/path/struct.Path.html#method.components
//! [`PathBuf`]: ../../std/path/struct.PathBuf.html
//! [`Path`]: ../../std/path/struct.Path.html
//! [`push`]: ../../std/path/struct.PathBuf.html#method.push
//! [`String`]: ../../std/string/struct.String.html
//!
//! [`str`]: ../../std/primitive.str.html
//! [`OsString`]: ../../std/ffi/struct.OsString.html
//! [`OsStr`]: ../../std/ffi/struct.OsStr.html
//! [`components`]: Path::components
//! [`push`]: PathBuf::push
#![stable(feature = "rust1", since = "1.0.0")]
@ -390,12 +382,9 @@ enum State {
/// # }
/// ```
///
/// [`as_os_str`]: #method.as_os_str
/// [`Component`]: enum.Component.html
/// [`kind`]: #method.kind
/// [`OsStr`]: ../../std/ffi/struct.OsStr.html
/// [`Prefix` variant]: enum.Component.html#variant.Prefix
/// [`Prefix`]: enum.Prefix.html
/// [`as_os_str`]: PrefixComponent::as_os_str
/// [`kind`]: PrefixComponent::kind
/// [`Prefix` variant]: Component::Prefix
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Copy, Clone, Eq, Debug)]
pub struct PrefixComponent<'a> {
@ -411,16 +400,12 @@ impl<'a> PrefixComponent<'a> {
///
/// See [`Prefix`]'s documentation for more information on the different
/// kinds of prefixes.
///
/// [`Prefix`]: enum.Prefix.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn kind(&self) -> Prefix<'a> {
self.parsed
}
/// Returns the raw [`OsStr`] slice for this prefix.
///
/// [`OsStr`]: ../../std/ffi/struct.OsStr.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_os_str(&self) -> &'a OsStr {
self.raw
@ -477,10 +462,6 @@ impl Hash for PrefixComponent<'_> {
/// Component::Normal("bar.txt".as_ref()),
/// ]);
/// ```
///
/// [`Components`]: struct.Components.html
/// [`Path`]: struct.Path.html
/// [`Path::components`]: struct.Path.html#method.components
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Component<'a> {
@ -490,8 +471,6 @@ pub enum Component<'a> {
/// for more.
///
/// Does not occur on Unix.
///
/// [`Prefix`]: enum.Prefix.html
#[stable(feature = "rust1", since = "1.0.0")]
Prefix(#[stable(feature = "rust1", since = "1.0.0")] PrefixComponent<'a>),
@ -529,8 +508,6 @@ impl<'a> Component<'a> {
/// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect();
/// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]);
/// ```
///
/// [`OsStr`]: ../../std/ffi/struct.OsStr.html
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_os_str(self) -> &'a OsStr {
match self {
@ -574,9 +551,7 @@ impl AsRef<Path> for Component<'_> {
/// }
/// ```
///
/// [`Component`]: enum.Component.html
/// [`components`]: struct.Path.html#method.components
/// [`Path`]: struct.Path.html
/// [`components`]: Path::components
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Components<'a> {
@ -602,10 +577,7 @@ pub struct Components<'a> {
/// This `struct` is created by the [`iter`] method on [`Path`].
/// See its documentation for more.
///
/// [`Component`]: enum.Component.html
/// [`iter`]: struct.Path.html#method.iter
/// [`OsStr`]: ../../std/ffi/struct.OsStr.html
/// [`Path`]: struct.Path.html
/// [`iter`]: Path::iter
#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a> {
@ -1002,8 +974,7 @@ impl cmp::Ord for Components<'_> {
/// }
/// ```
///
/// [`ancestors`]: struct.Path.html#method.ancestors
/// [`Path`]: struct.Path.html
/// [`ancestors`]: Path::ancestors
#[derive(Copy, Clone, Debug)]
#[stable(feature = "path_ancestors", since = "1.28.0")]
pub struct Ancestors<'a> {
@ -1034,11 +1005,8 @@ impl FusedIterator for Ancestors<'_> {}
/// the path in place. It also implements [`Deref`] to [`Path`], meaning that
/// all methods on [`Path`] slices are available on `PathBuf` values as well.
///
/// [`String`]: ../string/struct.String.html
/// [`Path`]: struct.Path.html
/// [`push`]: struct.PathBuf.html#method.push
/// [`set_extension`]: struct.PathBuf.html#method.set_extension
/// [`Deref`]: ../ops/trait.Deref.html
/// [`push`]: PathBuf::push
/// [`set_extension`]: PathBuf::set_extension
///
/// More details about the overall approach can be found in
/// the [module documentation](index.html).
@ -1127,8 +1095,7 @@ impl PathBuf {
/// assert_eq!(capacity, path.capacity());
/// ```
///
/// [`with_capacity`]: ../ffi/struct.OsString.html#method.with_capacity
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`with_capacity`]: OsString::with_capacity
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn with_capacity(capacity: usize) -> PathBuf {
PathBuf { inner: OsString::with_capacity(capacity) }
@ -1136,8 +1103,6 @@ impl PathBuf {
/// Coerces to a [`Path`] slice.
///
/// [`Path`]: struct.Path.html
///
/// # Examples
///
/// ```
@ -1224,8 +1189,7 @@ impl PathBuf {
/// Returns `false` and does nothing if [`self.parent`] is [`None`].
/// Otherwise, returns `true`.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`self.parent`]: struct.PathBuf.html#method.parent
/// [`self.parent`]: Path::parent
///
/// # Examples
///
@ -1259,9 +1223,8 @@ impl PathBuf {
/// `file_name`. The new path will be a sibling of the original path.
/// (That is, it will have the same parent.)
///
/// [`self.file_name`]: struct.PathBuf.html#method.file_name
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`pop`]: struct.PathBuf.html#method.pop
/// [`self.file_name`]: Path::file_name
/// [`pop`]: PathBuf::pop
///
/// # Examples
///
@ -1297,9 +1260,8 @@ impl PathBuf {
/// 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
/// [`self.file_name`]: Path::file_name
/// [`self.extension`]: Path::extension
///
/// # Examples
///
@ -1344,8 +1306,6 @@ impl PathBuf {
/// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
///
/// [`OsString`]: ../ffi/struct.OsString.html
///
/// # Examples
///
/// ```
@ -1360,9 +1320,6 @@ impl PathBuf {
}
/// Converts this `PathBuf` into a [boxed][`Box`] [`Path`].
///
/// [`Box`]: ../../std/boxed/struct.Box.html
/// [`Path`]: struct.Path.html
#[stable(feature = "into_boxed_path", since = "1.20.0")]
pub fn into_boxed_path(self) -> Box<Path> {
let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path;
@ -1371,8 +1328,7 @@ impl PathBuf {
/// Invokes [`capacity`] on the underlying instance of [`OsString`].
///
/// [`capacity`]: ../ffi/struct.OsString.html#method.capacity
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`capacity`]: OsString::capacity
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn capacity(&self) -> usize {
self.inner.capacity()
@ -1380,8 +1336,7 @@ impl PathBuf {
/// Invokes [`clear`] on the underlying instance of [`OsString`].
///
/// [`clear`]: ../ffi/struct.OsString.html#method.clear
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`clear`]: OsString::clear
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn clear(&mut self) {
self.inner.clear()
@ -1389,8 +1344,7 @@ impl PathBuf {
/// Invokes [`reserve`] on the underlying instance of [`OsString`].
///
/// [`reserve`]: ../ffi/struct.OsString.html#method.reserve
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`reserve`]: OsString::reserve
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn reserve(&mut self, additional: usize) {
self.inner.reserve(additional)
@ -1398,8 +1352,7 @@ impl PathBuf {
/// Invokes [`reserve_exact`] on the underlying instance of [`OsString`].
///
/// [`reserve_exact`]: ../ffi/struct.OsString.html#method.reserve_exact
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`reserve_exact`]: OsString::reserve_exact
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn reserve_exact(&mut self, additional: usize) {
self.inner.reserve_exact(additional)
@ -1407,8 +1360,7 @@ impl PathBuf {
/// Invokes [`shrink_to_fit`] on the underlying instance of [`OsString`].
///
/// [`shrink_to_fit`]: ../ffi/struct.OsString.html#method.shrink_to_fit
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`shrink_to_fit`]: OsString::shrink_to_fit
#[stable(feature = "path_buf_capacity", since = "1.44.0")]
pub fn shrink_to_fit(&mut self) {
self.inner.shrink_to_fit()
@ -1416,8 +1368,7 @@ impl PathBuf {
/// Invokes [`shrink_to`] on the underlying instance of [`OsString`].
///
/// [`shrink_to`]: ../ffi/struct.OsString.html#method.shrink_to
/// [`OsString`]: ../ffi/struct.OsString.html
/// [`shrink_to`]: OsString::shrink_to
#[unstable(feature = "shrink_to", issue = "56431")]
pub fn shrink_to(&mut self, min_capacity: usize) {
self.inner.shrink_to(min_capacity)
@ -1703,10 +1654,6 @@ impl AsRef<OsStr> for PathBuf {
/// pointer like `&` or [`Box`]. For an owned version of this type,
/// see [`PathBuf`].
///
/// [`str`]: ../primitive.str.html
/// [`Box`]: ../boxed/struct.Box.html
/// [`PathBuf`]: struct.PathBuf.html
///
/// More details about the overall approach can be found in
/// the [module documentation](index.html).
///
@ -1745,8 +1692,7 @@ pub struct Path {
/// This `struct` is created by the [`strip_prefix`] method on [`Path`].
/// See its documentation for more.
///
/// [`strip_prefix`]: struct.Path.html#method.strip_prefix
/// [`Path`]: struct.Path.html
/// [`strip_prefix`]: Path::strip_prefix
#[derive(Debug, Clone, PartialEq, Eq)]
#[stable(since = "1.7.0", feature = "strip_prefix")]
pub struct StripPrefixError(());
@ -1791,8 +1737,6 @@ impl Path {
/// Yields the underlying [`OsStr`] slice.
///
/// [`OsStr`]: ../ffi/struct.OsStr.html
///
/// # Examples
///
/// ```
@ -1812,7 +1756,7 @@ impl Path {
/// Note that validation is performed because non-UTF-8 strings are
/// perfectly valid for some OS.
///
/// [`&str`]: ../primitive.str.html
/// [`&str`]: str
///
/// # Examples
///
@ -1832,8 +1776,8 @@ impl Path {
/// Any non-Unicode sequences are replaced with
/// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
///
/// [`Cow<str>`]: ../borrow/enum.Cow.html
/// [U+FFFD]: ../char/constant.REPLACEMENT_CHARACTER.html
/// [`Cow<str>`]: Cow
/// [U+FFFD]: super::char::REPLACEMENT_CHARACTER
///
/// # Examples
///
@ -1855,8 +1799,6 @@ impl Path {
/// Converts a `Path` to an owned [`PathBuf`].
///
/// [`PathBuf`]: struct.PathBuf.html
///
/// # Examples
///
/// ```
@ -1888,7 +1830,7 @@ impl Path {
/// assert!(!Path::new("foo.txt").is_absolute());
/// ```
///
/// [`has_root`]: #method.has_root
/// [`has_root`]: Path::has_root
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)]
pub fn is_absolute(&self) -> bool {
@ -1912,7 +1854,7 @@ impl Path {
/// assert!(Path::new("foo.txt").is_relative());
/// ```
///
/// [`is_absolute`]: #method.is_absolute
/// [`is_absolute`]: Path::is_absolute
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_relative(&self) -> bool {
!self.is_absolute()
@ -1947,8 +1889,6 @@ impl Path {
///
/// Returns [`None`] if the path terminates in a root or prefix.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
@ -2001,8 +1941,7 @@ impl Path {
/// assert_eq!(ancestors.next(), None);
/// ```
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`parent`]: struct.Path.html#method.parent
/// [`parent`]: Path::parent
#[stable(feature = "path_ancestors", since = "1.28.0")]
pub fn ancestors(&self) -> Ancestors<'_> {
Ancestors { next: Some(&self) }
@ -2015,8 +1954,6 @@ impl Path {
///
/// Returns [`None`] if the path terminates in `..`.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```
@ -2045,8 +1982,7 @@ impl Path {
/// 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
/// [`starts_with`]: Path::starts_with
///
/// # Examples
///
@ -2132,7 +2068,7 @@ impl Path {
/// Extracts the stem (non-extension) portion of [`self.file_name`].
///
/// [`self.file_name`]: struct.Path.html#method.file_name
/// [`self.file_name`]: Path::file_name
///
/// The stem is:
///
@ -2141,8 +2077,6 @@ impl Path {
/// * 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
///
/// ```
@ -2165,8 +2099,7 @@ impl Path {
/// * [`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
/// [`self.file_name`]: Path::file_name
///
/// # Examples
///
@ -2185,9 +2118,6 @@ impl Path {
///
/// See [`PathBuf::push`] for more details on what it means to adjoin a path.
///
/// [`PathBuf`]: struct.PathBuf.html
/// [`PathBuf::push`]: struct.PathBuf.html#method.push
///
/// # Examples
///
/// ```
@ -2211,9 +2141,6 @@ impl Path {
///
/// See [`PathBuf::set_file_name`] for more details.
///
/// [`PathBuf`]: struct.PathBuf.html
/// [`PathBuf::set_file_name`]: struct.PathBuf.html#method.set_file_name
///
/// # Examples
///
/// ```
@ -2240,9 +2167,6 @@ impl Path {
///
/// See [`PathBuf::set_extension`] for more details.
///
/// [`PathBuf`]: struct.PathBuf.html
/// [`PathBuf::set_extension`]: struct.PathBuf.html#method.set_extension
///
/// # Examples
///
/// ```
@ -2299,8 +2223,7 @@ impl Path {
/// assert_eq!(components.next(), None)
/// ```
///
/// [`Component`]: enum.Component.html
/// [`CurDir`]: enum.Component.html#variant.CurDir
/// [`CurDir`]: Component::CurDir
#[stable(feature = "rust1", since = "1.0.0")]
pub fn components(&self) -> Components<'_> {
let prefix = parse_prefix(self.as_os_str());
@ -2320,8 +2243,7 @@ impl Path {
/// For more information about the particulars of how the path is separated
/// into components, see [`components`].
///
/// [`components`]: #method.components
/// [`OsStr`]: ../ffi/struct.OsStr.html
/// [`components`]: Path::components
///
/// # Examples
///
@ -2343,7 +2265,7 @@ impl Path {
/// Returns an object that implements [`Display`] for safely printing paths
/// that may contain non-Unicode data.
///
/// [`Display`]: ../fmt/trait.Display.html
/// [`Display`]: fmt::Display
///
/// # Examples
///
@ -2366,8 +2288,6 @@ impl Path {
///
/// This is an alias to [`fs::metadata`].
///
/// [`fs::metadata`]: ../fs/fn.metadata.html
///
/// # Examples
///
/// ```no_run
@ -2386,8 +2306,6 @@ impl Path {
///
/// This is an alias to [`fs::symlink_metadata`].
///
/// [`fs::symlink_metadata`]: ../fs/fn.symlink_metadata.html
///
/// # Examples
///
/// ```no_run
@ -2407,8 +2325,6 @@ impl Path {
///
/// This is an alias to [`fs::canonicalize`].
///
/// [`fs::canonicalize`]: ../fs/fn.canonicalize.html
///
/// # Examples
///
/// ```no_run
@ -2426,8 +2342,6 @@ impl Path {
///
/// This is an alias to [`fs::read_link`].
///
/// [`fs::read_link`]: ../fs/fn.read_link.html
///
/// # Examples
///
/// ```no_run
@ -2443,15 +2357,11 @@ impl Path {
/// Returns an iterator over the entries within a directory.
///
/// The iterator will yield instances of [`io::Result`]`<`[`DirEntry`]`>`. New
/// The iterator will yield instances of [`io::Result`]`<`[`fs::DirEntry`]`>`. New
/// errors may be encountered after an iterator is initially constructed.
///
/// This is an alias to [`fs::read_dir`].
///
/// [`io::Result`]: ../io/type.Result.html
/// [`DirEntry`]: ../fs/struct.DirEntry.html
/// [`fs::read_dir`]: ../fs/fn.read_dir.html
///
/// # Examples
///
/// ```no_run
@ -2487,9 +2397,7 @@ impl Path {
/// # See Also
///
/// This is a convenience function that coerces errors to false. If you want to
/// check errors, call [fs::metadata].
///
/// [fs::metadata]: ../../std/fs/fn.metadata.html
/// check errors, call [`fs::metadata`].
#[stable(feature = "path_ext", since = "1.5.0")]
pub fn exists(&self) -> bool {
fs::metadata(self).is_ok()
@ -2514,20 +2422,14 @@ impl Path {
/// # See Also
///
/// This is a convenience function that coerces errors to false. If you want to
/// check errors, call [`fs::metadata`] and handle its Result. Then call
/// [`fs::Metadata::is_file`] if it was Ok.
/// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
/// [`fs::Metadata::is_file`] if it was [`Ok`].
///
/// When the goal is simply to read from (or write to) the source, the most
/// reliable way to test the source can be read (or written to) is to open
/// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
/// a Unix-like system for example. See [`File::open`] or
/// [`OpenOptions::open`] for more information.
///
/// [`fs::metadata`]: ../../std/fs/fn.metadata.html
/// [`fs::Metadata`]: ../../std/fs/struct.Metadata.html
/// [`fs::Metadata::is_file`]: ../../std/fs/struct.Metadata.html#method.is_file
/// [`File::open`]: ../../std/fs/struct.File.html#method.open
/// [`OpenOptions::open`]: ../../std/fs/struct.OpenOptions.html#method.open
/// a Unix-like system for example. See [`fs::File::open`] or
/// [`fs::OpenOptions::open`] for more information.
#[stable(feature = "path_ext", since = "1.5.0")]
pub fn is_file(&self) -> bool {
fs::metadata(self).map(|m| m.is_file()).unwrap_or(false)
@ -2552,11 +2454,8 @@ impl Path {
/// # See Also
///
/// This is a convenience function that coerces errors to false. If you want to
/// check errors, call [fs::metadata] and handle its Result. Then call
/// [fs::Metadata::is_dir] if it was Ok.
///
/// [fs::metadata]: ../../std/fs/fn.metadata.html
/// [fs::Metadata::is_dir]: ../../std/fs/struct.Metadata.html#method.is_dir
/// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call
/// [`fs::Metadata::is_dir`] if it was [`Ok`].
#[stable(feature = "path_ext", since = "1.5.0")]
pub fn is_dir(&self) -> bool {
fs::metadata(self).map(|m| m.is_dir()).unwrap_or(false)
@ -2564,9 +2463,6 @@ impl Path {
/// Converts a [`Box<Path>`][`Box`] into a [`PathBuf`] without copying or
/// allocating.
///
/// [`Box`]: ../../std/boxed/struct.Box.html
/// [`PathBuf`]: struct.PathBuf.html
#[stable(feature = "into_boxed_path", since = "1.20.0")]
pub fn into_path_buf(self: Box<Path>) -> PathBuf {
let rw = Box::into_raw(self) as *mut OsStr;
@ -2605,10 +2501,8 @@ impl fmt::Debug for Path {
/// println!("{}", path.display());
/// ```
///
/// [`Display`]: ../../std/fmt/trait.Display.html
/// [`format!`]: ../../std/macro.format.html
/// [`Path`]: struct.Path.html
/// [`Path::display`]: struct.Path.html#method.display
/// [`Display`]: fmt::Display
/// [`format!`]: crate::format
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Display<'a> {
path: &'a Path,