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

Jump to bottom

Improve Path and PathBuf docs #35786

Merged
merged 1 commit into from
Sep 1, 2016
Merged

Improve Path and PathBuf docs #35786

Show file tree
Hide file tree
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
7 changes: 5 additions & 2 deletions src/libstd/fs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down
176 changes: 144 additions & 32 deletions src/libstd/path.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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()) {
Expand All @@ -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
///
/// ```
Expand All @@ -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`.
///
/// 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};
///
/// If `self.file_name()` is `None`, does nothing and returns `false`.
/// let mut p = PathBuf::from("/feel/the");
///
/// Otherwise, returns `true`; if `self.extension()` is `None`, the extension
/// is added; otherwise it is replaced.
/// 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())
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
Expand All @@ -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
///
/// ```
Expand All @@ -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
///
/// ```
Expand All @@ -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
///
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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:
///
Expand All @@ -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:
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand All @@ -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
///
Expand Down Expand Up @@ -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
///
Expand All @@ -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
///
/// ```
Expand Down Expand Up @@ -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> {
Expand Down