Auto merge of #104679 - dvdhrm:rw/dso, r=petrochenkov

[rust.git] / library / std / src / path.rs

diff --git a/library/std/src/path.rs b/library/std/src/path.rs
index 4f9dff1ef03536b2fc28b3fa7f9fc25135f38480..6c957c2fa90eb517088f085687474dbc3b6d702a 100644 (file)
--- a/library/std/src/path.rs
+++ b/library/std/src/path.rs
@@ -1463,6 +1463,30 @@ fn _set_extension(&mut self, extension: &OsStr) -> bool {
         true
     }
 
+    /// Yields a mutable reference to the underlying [`OsString`] instance.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(path_as_mut_os_str)]
+    /// use std::path::{Path, PathBuf};
+    ///
+    /// let mut path = PathBuf::from("/foo");
+    ///
+    /// path.push("bar");
+    /// assert_eq!(path, Path::new("/foo/bar"));
+    ///
+    /// // OsString's `push` does not add a separator.
+    /// path.as_mut_os_string().push("baz");
+    /// assert_eq!(path, Path::new("/foo/barbaz"));
+    /// ```
+    #[unstable(feature = "path_as_mut_os_str", issue = "105021")]
+    #[must_use]
+    #[inline]
+    pub fn as_mut_os_string(&mut self) -> &mut OsString {
+        &mut self.inner
+    }
+
     /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
     ///
     /// # Examples
@@ -1993,6 +2017,28 @@ pub fn as_os_str(&self) -> &OsStr {
         &self.inner
     }
 
+    /// Yields a mutable reference to the underlying [`OsStr`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(path_as_mut_os_str)]
+    /// use std::path::{Path, PathBuf};
+    ///
+    /// let mut path = PathBuf::from("/Foo.TXT").into_boxed_path();
+    ///
+    /// assert_ne!(&*path, Path::new("/foo.txt"));
+    ///
+    /// path.as_mut_os_str().make_ascii_lowercase();
+    /// assert_eq!(&*path, Path::new("/foo.txt"));
+    /// ```
+    #[unstable(feature = "path_as_mut_os_str", issue = "105021")]
+    #[must_use]
+    #[inline]
+    pub fn as_mut_os_str(&mut self) -> &mut OsStr {
+        &mut self.inner
+    }
+
     /// Yields a [`&str`] slice if the `Path` is valid unicode.
     ///
     /// This conversion may entail doing a check for UTF-8 validity.
@@ -2142,7 +2188,10 @@ pub fn has_root(&self) -> bool {
 
     /// Returns the `Path` without its final component, if there is one.
     ///
-    /// Returns [`None`] if the path terminates in a root or prefix.
+    /// This means it returns `Some("")` for relative paths with one component.
+    ///
+    /// Returns [`None`] if the path terminates in a root or prefix, or if it's
+    /// the empty string.
     ///
     /// # Examples
     ///
@@ -2156,8 +2205,17 @@ pub fn has_root(&self) -> bool {
     /// let grand_parent = parent.parent().unwrap();
     /// assert_eq!(grand_parent, Path::new("/"));
     /// assert_eq!(grand_parent.parent(), None);
+    ///
+    /// let relative_path = Path::new("foo/bar");
+    /// let parent = relative_path.parent();
+    /// assert_eq!(parent, Some(Path::new("foo")));
+    /// let grand_parent = parent.and_then(Path::parent);
+    /// assert_eq!(grand_parent, Some(Path::new("")));
+    /// let great_grand_parent = grand_parent.and_then(Path::parent);
+    /// assert_eq!(great_grand_parent, None);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[doc(alias = "dirname")]
     #[must_use]
     pub fn parent(&self) -> Option<&Path> {
         let mut comps = self.components();
@@ -2225,6 +2283,7 @@ pub fn ancestors(&self) -> Ancestors<'_> {
     /// assert_eq!(None, Path::new("/").file_name());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
+    #[doc(alias = "basename")]
     #[must_use]
     pub fn file_name(&self) -> Option<&OsStr> {
         self.components().next_back().and_then(|p| match p {