Struct MediaDirs 

pub struct MediaDirs { /* private fields */ }

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Common user directory paths used for user-specific media files.

It is not required that the media directories are accessible by the current user, nor that there is a directory at that path. A robust application should handle the case where media directories are incorrectly configured.

Even when configured correctly, multiple paths may point to the same location. You should not assume that a file written relative to one directory will not conflict with the same relative path in a different media directory.

Platform-specific behavior

As the filesystem conventions for discovering directories varies between operating systems, constructors for MediaDirs that use the host platform’s conventions are provided as extension traits under the std::os module.

Implementations

impl MediaDirs

pub fn empty() -> Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Create a known user directory set with no known directories.

This is useful with the builder set_* methods to create a MediaDirs with exactly the directories you want, without any other defaults.

pub fn desktop(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Desktop” directory, often the Desktop folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir DESKTOP ($HOME/Desktop)
Darwin (macOS)	NSDesktopDirectory ($HOME/Desktop)
Windows	{FOLDERID_Desktop} (%USERPROFILE%\Desktop)

Other paths can be configured via set_desktop.

pub fn documents(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Documents” directory, often the Documents folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir DOCUMENTS ($HOME/Documents)
Darwin (macOS)	NSDocumentDirectory ($HOME/Documents)
Windows	{FOLDERID_Documents} (%USERPROFILE%\Documents)

Other paths can be configured via set_documents.

pub fn downloads(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Downloads” directory, often the Downloads folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir DOWNLOAD ($HOME/Downloads)
Darwin (macOS)	NSDownloadsDirectory ($HOME/Downloads)
Windows	{FOLDERID_Downloads} (%USERPROFILE%\Downloads)

Other paths can be configured via set_downloads.

pub fn music(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Music” directory, often the Music folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir MUSIC ($HOME/Music)
Darwin (macOS)	NSMusicDirectory ($HOME/Music)
Windows	{FOLDERID_Music} (%USERPROFILE%\Music)

Other paths can be configured via set_music.

pub fn pictures(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Pictures” directory, often the Pictures folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir PICTURES ($HOME/Pictures)
Darwin (macOS)	NSPicturesDirectory ($HOME/Pictures)
Windows	{FOLDERID_Pictures} (%USERPROFILE%\Pictures)

Other paths can be configured via set_pictures.

pub fn videos(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-recognized user “Videos” directory, often the Videos folder in the user’s home directory.

As a media directory, this should typically be used as a default path for file selection dialogs, not for automatically accessed file paths.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	xdg-user-dir VIDEOS ($HOME/Videos)
Darwin (macOS)	NSMoviesDirectory ($HOME/Movies)
Windows	{FOLDERID_Videos} (%USERPROFILE%\Videos)

Other paths can be configured via set_videos.

impl MediaDirs

pub fn set_desktop(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::desktop.

Panics

Panics if the provided path is not absolute.

pub fn set_documents(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::documents.

Panics

Panics if the provided path is not absolute.

pub fn set_downloads(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::downloads.

Panics

Panics if the provided path is not absolute.

pub fn set_music(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::music.

Panics

Panics if the provided path is not absolute.

pub fn set_pictures(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::pictures.

Panics

Panics if the provided path is not absolute.

pub fn set_videos(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the path for Self::videos.

Panics

Panics if the provided path is not absolute.

Trait Implementations

impl Clone for MediaDirs

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MediaDirs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MediaDirsExt for MediaDirs

Available on Unix only.

fn xdg() -> Result<Self>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Load the user directory paths according to the xdg-user-dirs tool.

fn templates(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

The OS-privileged user “Templates” directory, often the Templates folder in the user’s home directory.

fn set_templates(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_media_dirs #162083)

Set the paths for Self::templates.