add Utf8PathBuf::leak

Author: sunshowers

build.rs

@@ -19,6 +19,7 @@ fn main() {
     println!("cargo:rustc-check-cfg=cfg(shrink_to)");
     println!("cargo:rustc-check-cfg=cfg(try_reserve_2)");
     println!("cargo:rustc-check-cfg=cfg(os_str_bytes)");
+    println!("cargo:rustc-check-cfg=cfg(os_string_pathbuf_leak)");
     println!("cargo:rustc-check-cfg=cfg(absolute_path)");
 
     let compiler = match rustc_version() {
@@ -61,6 +62,11 @@ fn main() {
     {
         println!("cargo:rustc-cfg=absolute_path");
     }
+    // os_string_pathbuf_leak was added in 1.89.
+    if (compiler.minor >= 89 && compiler.channel == ReleaseChannel::Stable) || compiler.minor >= 90
+    {
+        println!("cargo:rustc-cfg=os_string_pathbuf_leak");
+    }
 
     // Catch situations where the actual features aren't enabled. Currently, they're only shown with
     // `-vv` output, but maybe that will be noticed.

src/lib.rs

@@ -227,6 +227,27 @@ impl Utf8PathBuf {
         unsafe { Utf8Path::assume_utf8(&self.0) }
     }
 
+    /// Consumes and leaks the `Utf8PathBuf`, returning a mutable reference to the contents,
+    /// `&'a mut Utf8Path`.
+    ///
+    /// The caller has free choice over the returned lifetime, including 'static.
+    /// Indeed, this function is ideally used for data that lives for the remainder of
+    /// the program’s life, as dropping the returned reference will cause a memory leak.
+    ///
+    /// It does not reallocate or shrink the `Utf8PathBuf`, so the leaked allocation may include
+    /// unused capacity that is not part of the returned slice. If you want to discard excess
+    /// capacity, call [`into_boxed_path`], and then [`Box::leak`] instead.
+    /// However, keep in mind that trimming the capacity may result in a reallocation and copy.
+    ///
+    /// [`into_boxed_path`]: Self::into_boxed_path
+    #[cfg(os_string_pathbuf_leak)]
+    #[allow(clippy::incompatible_msrv)]
+    #[inline]
+    pub fn leak<'a>(self) -> &'a mut Utf8Path {
+        // SAFETY: every Utf8PathBuf constructor ensures that self is valid UTF-8
+        unsafe { Utf8Path::assume_utf8_mut(self.0.leak()) }
+    }
+
     /// Extends `self` with `path`.
     ///
     /// If `path` is absolute, it replaces the current path.