Skip to content

Tracking Issue for std::fs::MediaDirs (feature(fs_media_dirs)) #162083

Description

@CAD97

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.)

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.
    • As these paths should primarily be used in conjunction with a file picker, should the determination of file picker starting paths be left to the crate implementing the file picker?
  • 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.
  • 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 Tracking Issue for std::fs::HomeDirs (feature(fs_home_dirs)) #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.

Footnotes

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

Metadata

Metadata

Assignees

Labels

C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCS-tracking-unimplementedStatus: The feature has not been implemented.T-libsRelevant to the library team, which will review and decide on the PR/issue.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions