Tracking issue for PathBuf::as_mut_os_string and Path::as_mut_os_str

[zertosh]

Feature gate: #![feature(path_as_mut_os_str)]

This is a tracking issue for adding PathBuf::as_mut_os_string and Path::as_mut_os_str (rust-lang/libs-team#140).

Public API

impl PathBuf {
    // ...
    pub fn as_mut_os_string(&mut self) -> &mut OsString {
        &mut self.inner
    }
    // ...
}

impl Path {
    // ...
    pub fn as_mut_os_str(&mut self) -> &mut OsStr {
        &mut self.inner
    }
    // ...
}

Steps / History

• Implementation: Add PathBuf::as_mut_os_string and Path::as_mut_os_str #105002
• Implement DerefMut for PathBuf #105018: the initial example for Path::as_mut_os_str was contrived because one must go through into_boxed_path to get a &mut Path. A DerefMut impl makes it possible to demonstrate a more realistic use.
• Realistic Path::as_mut_os_str doctest #105801
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[the8472]

That seems questionable to me. Right now we don't have any restrictions what goes into a Path, but on some future platform it might be necessary to have a validation on Path::new (e.g. only a restricted set of prefixes is allowed) and that can't be done if it can be freely mutated as a osstring.

[dtolnay]

On platforms that would need such a restriction, would Path::new have a different return type, or a different name, or would panic? In addition to Path::new, there's already impl AsRef<Path> for str, impl AsRef<Path> for OsStr, and probably a bunch of others that bake in the expectation that paths are arbitrary OS strings. If we're gonna be making those panic or be conditionally compiled, doing the same for Path::as_mut_os_str is no more complex than any of those. But it seems more likely to me that the way we would address platform-specific path restrictions would be by leaving it to the system calls to report failure on an unsupported contents of a path, or doing validation in Rust before the system call, not during PathBuf mutations.

[zertosh]

Stabilization Report

Implementation History

• PathBuf::as_mut_os_string and Path::as_mut_os_str implemented in Add PathBuf::as_mut_os_string and Path::as_mut_os_str #105002.
• DerefMut for PathBuf was implemented in Implement DerefMut for PathBuf #105018 to make this feature more usable.
• More realisitic doctests were added in Realistic Path::as_mut_os_str doctest #105801 (now possible with Implement DerefMut for PathBuf #105018).

API Summary

A summary of the API is included at the top of this tracking issue.

Experience Report

n/a

[zertosh]

@dtolnay, can you please start an FCP? (as per Stabilization PR Checklist)

[dtolnay]

@rust-lang/libs-api
@rfcbot fcp merge

This stabilizes PathBuf::as_mut_os_string and Path::as_mut_os_str.

The point of these methods is illustrated in the documentation examples. They let you mutate the path contents in place without going through PathBuf's limited mutation API (e.g. every push adding a separator).

path.as_mut_os_string().push("-suffix");

// equivalent to:
let mut os_string = std::mem::take(path).into_os_string();
os_string.push("-suffix");
*path = PathBuf::from(os_string);

Note that a Path::as_os_str has existed since 1.0.0 to help people avoid using AsRef<OsStr> for Path in places that an as_ref() call might be ambiguous. Meanwhile PathBuf::as_os_string has not come up so far as a thing anyone wants.

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[dtolnay]

I'm marking yaahc's box because she has stepped down from T-libs-api after the point that this feature got proposed for FCP.

[dtolnay]

@Amanieu or @joshtriplett or @m-ou-se?

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.