Improve Path and PathBuf docs
This commit is contained in:
Guillaume Gomez
ggomez
parent
9d6520f97b
commit
96e3103cfe
2 changed files with 149 additions and 34 deletions
|
|
@ -1511,8 +1511,11 @@ pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
|
|||
|
||||
/// Returns an iterator over the entries within a directory.
|
||||
///
|
||||
/// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
|
||||
/// be encountered after an iterator is initially constructed.
|
||||
/// The iterator will yield instances of [`io::Result`]`<`[`DirEntry`]`>`.
|
||||
/// New errors may be encountered after an iterator is initially constructed.
|
||||
///
|
||||
/// [`io::Result`]: ../io/type.Result.html
|
||||
/// [`DirEntry`]: struct.DirEntry.html
|
||||
///
|
||||
/// # Platform-specific behavior
|
||||
///
|
||||
|
|
|
|||
|
|
@ -986,11 +986,16 @@ impl<'a> cmp::Ord for Components<'a> {
|
|||
// Basic types and traits
|
||||
////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// An owned, mutable path (akin to `String`).
|
||||
/// An owned, mutable path (akin to [`String`]).
|
||||
///
|
||||
/// This type provides methods like `push` and `set_extension` that mutate the
|
||||
/// path in place. It also implements `Deref` to `Path`, meaning that all
|
||||
/// methods on `Path` slices are available on `PathBuf` values as well.
|
||||
/// This type provides methods like [`push`] and [`set_extension`] that mutate
|
||||
/// 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
|
||||
///
|
||||
/// More details about the overall approach can be found in
|
||||
/// the module documentation.
|
||||
|
|
@ -1017,12 +1022,31 @@ impl PathBuf {
|
|||
}
|
||||
|
||||
/// Allocates an empty `PathBuf`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::PathBuf;
|
||||
///
|
||||
/// let path = PathBuf::new();
|
||||
/// ```
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn new() -> PathBuf {
|
||||
PathBuf { inner: OsString::new() }
|
||||
}
|
||||
|
||||
/// Coerces to a `Path` slice.
|
||||
/// Coerces to a [`Path`] slice.
|
||||
///
|
||||
/// [`Path`]: struct.Path.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::{Path, PathBuf};
|
||||
///
|
||||
/// let p = PathBuf::from("/test");
|
||||
/// assert_eq!(Path::new("/test"), p.as_path());
|
||||
/// ```
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn as_path(&self) -> &Path {
|
||||
self
|
||||
|
|
@ -1087,10 +1111,26 @@ impl PathBuf {
|
|||
self.inner.push(path);
|
||||
}
|
||||
|
||||
/// Truncate `self` to `self.parent()`.
|
||||
/// Truncate `self` to [`self.parent()`].
|
||||
///
|
||||
/// Returns false and does nothing if `self.file_name()` is `None`.
|
||||
/// Returns false and does nothing if [`self.file_name()`] is `None`.
|
||||
/// Otherwise, returns `true`.
|
||||
///
|
||||
/// [`self.parent()`]: struct.PathBuf.html#method.parent
|
||||
/// [`self.file_name()`]: struct.PathBuf.html#method.file_name
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::{Path, PathBuf};
|
||||
///
|
||||
/// let mut p = PathBuf::from("/test/test.rs");
|
||||
///
|
||||
/// p.pop();
|
||||
/// assert_eq!(Path::new("/test"), p.as_path());
|
||||
/// p.pop();
|
||||
/// assert_eq!(Path::new("/"), p.as_path());
|
||||
/// ```
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn pop(&mut self) -> bool {
|
||||
match self.parent().map(|p| p.as_u8_slice().len()) {
|
||||
|
|
@ -1102,11 +1142,13 @@ impl PathBuf {
|
|||
}
|
||||
}
|
||||
|
||||
/// Updates `self.file_name()` to `file_name`.
|
||||
/// 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
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
|
@ -1133,12 +1175,29 @@ impl PathBuf {
|
|||
self.push(file_name);
|
||||
}
|
||||
|
||||
/// Updates `self.extension()` to `extension`.
|
||||
/// Updates [`self.extension()`] to `extension`.
|
||||
///
|
||||
/// If `self.file_name()` is `None`, does nothing and returns `false`.
|
||||
/// If [`self.file_name()`] is `None`, does nothing and returns `false`.
|
||||
///
|
||||
/// Otherwise, returns `true`; if `self.extension()` is `None`, the extension
|
||||
/// is added; otherwise it is replaced.
|
||||
/// 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
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::{Path, PathBuf};
|
||||
///
|
||||
/// let mut p = PathBuf::from("/feel/the");
|
||||
///
|
||||
/// p.set_extension("force");
|
||||
/// assert_eq!(Path::new("/feel/the.force"), p.as_path());
|
||||
///
|
||||
/// p.set_extension("dark_side");
|
||||
/// assert_eq!(Path::new("/feel/the.dark_side"), p.as_path());
|
||||
/// ```
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool {
|
||||
self._set_extension(extension.as_ref())
|
||||
|
|
@ -1163,7 +1222,18 @@ impl PathBuf {
|
|||
true
|
||||
}
|
||||
|
||||
/// Consumes the `PathBuf`, yielding its internal `OsString` storage.
|
||||
/// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
|
||||
///
|
||||
/// [`OsString`]: ../ffi/struct.OsString.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::PathBuf;
|
||||
///
|
||||
/// let p = PathBuf::from("/the/head");
|
||||
/// let os_str = p.into_os_string();
|
||||
/// ```
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn into_os_string(self) -> OsString {
|
||||
self.inner
|
||||
|
|
@ -1301,7 +1371,7 @@ impl Into<OsString> for PathBuf {
|
|||
}
|
||||
}
|
||||
|
||||
/// A slice of a path (akin to `str`).
|
||||
/// A slice of a path (akin to [`str`]).
|
||||
///
|
||||
/// This type supports a number of operations for inspecting a path, including
|
||||
/// breaking the path into its components (separated by `/` or `\`, depending on
|
||||
|
|
@ -1310,7 +1380,10 @@ impl Into<OsString> for PathBuf {
|
|||
/// the module documentation.
|
||||
///
|
||||
/// This is an *unsized* type, meaning that it must always be used behind a
|
||||
/// pointer like `&` or `Box`.
|
||||
/// pointer like `&` or [`Box`].
|
||||
///
|
||||
/// [`str`]: ../primitive.str.html
|
||||
/// [`Box`]: ../boxed/struct.Box.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1372,7 +1445,9 @@ impl Path {
|
|||
unsafe { mem::transmute(s.as_ref()) }
|
||||
}
|
||||
|
||||
/// Yields the underlying `OsStr` slice.
|
||||
/// Yields the underlying [`OsStr`] slice.
|
||||
///
|
||||
/// [`OsStr`]: ../ffi/struct.OsStr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1387,10 +1462,12 @@ impl Path {
|
|||
&self.inner
|
||||
}
|
||||
|
||||
/// Yields a `&str` slice if the `Path` is valid unicode.
|
||||
/// Yields a [`&str`] slice if the `Path` is valid unicode.
|
||||
///
|
||||
/// This conversion may entail doing a check for UTF-8 validity.
|
||||
///
|
||||
/// [`&str`]: ../primitive.str.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
|
@ -1404,10 +1481,12 @@ impl Path {
|
|||
self.inner.to_str()
|
||||
}
|
||||
|
||||
/// Converts a `Path` to a `Cow<str>`.
|
||||
/// Converts a `Path` to a [`Cow<str>`].
|
||||
///
|
||||
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
|
||||
///
|
||||
/// [`Cow<str>`]: ../borrow/enum.Cow.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
|
@ -1421,7 +1500,9 @@ impl Path {
|
|||
self.inner.to_string_lossy()
|
||||
}
|
||||
|
||||
/// Converts a `Path` to an owned `PathBuf`.
|
||||
/// Converts a `Path` to an owned [`PathBuf`].
|
||||
///
|
||||
/// [`PathBuf`]: struct.PathBuf.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1569,6 +1650,18 @@ impl Path {
|
|||
///
|
||||
/// If `base` is not a prefix of `self` (i.e. `starts_with`
|
||||
/// returns `false`), returns `Err`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::path::Path;
|
||||
///
|
||||
/// let path = Path::new("/test/haha/foo.txt");
|
||||
///
|
||||
/// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));
|
||||
/// assert_eq!(path.strip_prefix("test").is_ok(), false);
|
||||
/// assert_eq!(path.strip_prefix("/haha").is_ok(), false);
|
||||
/// ```
|
||||
#[stable(since = "1.7.0", feature = "path_strip_prefix")]
|
||||
pub fn strip_prefix<'a, P: ?Sized>(&'a self, base: &'a P)
|
||||
-> Result<&'a Path, StripPrefixError>
|
||||
|
|
@ -1630,7 +1723,9 @@ impl Path {
|
|||
iter_after(self.components().rev(), child.components().rev()).is_some()
|
||||
}
|
||||
|
||||
/// Extracts the stem (non-extension) portion of `self.file_name()`.
|
||||
/// Extracts the stem (non-extension) portion of [`self.file_name()`].
|
||||
///
|
||||
/// [`self.file_name()`]: struct.Path.html#method.file_name
|
||||
///
|
||||
/// The stem is:
|
||||
///
|
||||
|
|
@ -1653,7 +1748,9 @@ impl Path {
|
|||
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
|
||||
}
|
||||
|
||||
/// Extracts the extension of `self.file_name()`, if possible.
|
||||
/// Extracts the extension of [`self.file_name()`], if possible.
|
||||
///
|
||||
/// [`self.file_name()`]: struct.Path.html#method.file_name
|
||||
///
|
||||
/// The extension is:
|
||||
///
|
||||
|
|
@ -1676,9 +1773,12 @@ impl Path {
|
|||
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
|
||||
}
|
||||
|
||||
/// Creates an owned `PathBuf` with `path` adjoined to `self`.
|
||||
/// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
|
||||
///
|
||||
/// See `PathBuf::push` for more details on what it means to adjoin a 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
|
||||
///
|
||||
|
|
@ -1698,9 +1798,12 @@ impl Path {
|
|||
buf
|
||||
}
|
||||
|
||||
/// Creates an owned `PathBuf` like `self` but with the given file name.
|
||||
/// Creates an owned [`PathBuf`] like `self` but with the given file name.
|
||||
///
|
||||
/// See `PathBuf::set_file_name` for more details.
|
||||
/// See [`PathBuf::set_file_name`] for more details.
|
||||
///
|
||||
/// [`PathBuf`]: struct.PathBuf.html
|
||||
/// [`PathBuf::set_file_name`]: struct.PathBuf.html#method.set_file_name
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1721,9 +1824,12 @@ impl Path {
|
|||
buf
|
||||
}
|
||||
|
||||
/// Creates an owned `PathBuf` like `self` but with the given extension.
|
||||
/// Creates an owned [`PathBuf`] like `self` but with the given extension.
|
||||
///
|
||||
/// See `PathBuf::set_extension` for more details.
|
||||
/// See [`PathBuf::set_extension`] for more details.
|
||||
///
|
||||
/// [`PathBuf`]: struct.PathBuf.html
|
||||
/// [`PathBuf::set_extension`]: struct.PathBuf.html#method.set_extension
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1771,7 +1877,9 @@ impl Path {
|
|||
}
|
||||
}
|
||||
|
||||
/// Produce an iterator over the path's components viewed as `OsStr` slices.
|
||||
/// Produce an iterator over the path's components viewed as [`OsStr`] slices.
|
||||
///
|
||||
/// [`OsStr`]: ../ffi/struct.OsStr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -1790,9 +1898,11 @@ impl Path {
|
|||
Iter { inner: self.components() }
|
||||
}
|
||||
|
||||
/// Returns an object that implements `Display` for safely printing paths
|
||||
/// Returns an object that implements [`Display`] for safely printing paths
|
||||
/// that may contain non-Unicode data.
|
||||
///
|
||||
/// [`Display`]: ../fmt/trait.Display.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
|
@ -1854,11 +1964,13 @@ impl Path {
|
|||
|
||||
/// Returns an iterator over the entries within a directory.
|
||||
///
|
||||
/// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
|
||||
/// be encountered after an iterator is initially constructed.
|
||||
/// The iterator will yield instances of [`io::Result`]`<`[`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
|
||||
#[stable(feature = "path_ext", since = "1.5.0")]
|
||||
pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue