Tracking Issue for `std::fs::MediaDirs` (`feature(fs_media_dirs)`)

Feature gate: #![feature(fs_media_dirs)]

This is a tracking issue for std::fs::MediaDirs and related functionality.

Sister feature tracking issue: std::fs::HomeDirs

MediaDirs exposes common user directory paths useful for storing media files.

Public API

// mod std::fs
pub struct MediaDirs { /* ... */ }
impl MediaDirs {
    pub fn empty() -> Self;

    pub fn desktop(&self) -> Option<&Path>;
    pub fn documents(&self) -> Option<&Path>;
    pub fn downloads(&self) -> Option<&Path>;
    pub fn music(&self) -> Option<&Path>;
    pub fn pictures(&self) -> Option<&Path>;
    pub fn videos(&self) -> Option<&Path>;

    pub fn set_desktop(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_documents(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_downloads(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_music(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_pictures(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_videos(&mut self, path: PathBuf) -> &mut Self;
}

// mod std::os::darwin::fs
impl MediaDirsExt for MediaDirs { /* ... */ }
pub impl(self) trait MediaDirsExt {
    fn sysdir() -> io::Result<Self>;
}

// mod std::os::unix::fs
impl MediaDirsExt for MediaDirs { /* ... */ }
pub impl(self) trait MediaDirsExt {
    fn xdg() -> io::Result<Self>;

    fn templates(&self) -> Option<&Path>;
    fn set_templates(&mut self, path: PathBuf) -> &mut Self;
}

// mod std::os::windows::fs
impl MediaDirsExt for MediaDirs { /* ... */ }
pub impl(self) trait MediaDirsExt {
    fn known_folders() -> io::Result<Self>;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: https://github.com/rust-lang/libs-team/issues/830
• Implementation: https://github.com/rust-lang/rust/pull/158936
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• Is this API sufficiently platform-agnostic, resilient to new OS developments, and generally useful to live in std?
  • The author believes so. T-libs-api has approved in-tree experimentation.
  • Should these paths be exposed by std or left to an external crate? CLI tools are likely to prefer using passed-in paths, and GUI apps are likely to have a GUI framework that could be a reasonable home for this functionality.
• I (@CAD97) think that a fn take(&mut self) -> Self method would be useful for builder-API style usage of the set_* methods. T-libs-api agreed we don't. I will defer to T-libs-api here, but want to log this note.
  • #t-libs/api-changes > MediaDirs::take
• Should the Windows MediaDirsExt provide access to more of the PERUSER KNOWNFOLDERIDs?
• APIs for home dirs are out of scope for this tracking issue; for those, see https://github.com/rust-lang/rust/issues/162082.
• APIs for app dirs (which are subdirs of the home dirs) is explicitly out of scope for this tracking issue and should get a new ACP.