Struct directories::BaseDirs

source ·
pub struct BaseDirs { /* private fields */ }
Expand description

BaseDirs provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on.

To compute the location of cache, config or data directories for individual projects or applications, use ProjectDirs instead.

Examples

All examples on this page are computed with a user named Alice.

use directories::BaseDirs;
if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.config_dir();
    // Linux:   /home/alice/.config
    // Windows: C:\Users\Alice\AppData\Roaming
    // macOS:   /Users/Alice/Library/Application Support
}

Implementations§

source§

impl BaseDirs

source

pub fn new() -> Option<BaseDirs>

Creates a BaseDirs struct which holds the paths to user-invisible directories for cache, config, etc. data on the system.

The returned value depends on the operating system and is either

  • Some, containing a snapshot of the state of the system’s paths at the time new() was invoked, or
  • None, if no valid home directory path could be retrieved from the operating system.

To determine whether a system provides a valid $HOME path, the following rules are applied:

Linux and macOS:
  • Use $HOME if it is set and not empty.
  • If $HOME is not set or empty, then the function getpwuid_r is used to determine the home directory of the current user.
  • If getpwuid_r lacks an entry for the current user id or the home directory field is empty, then the function returns None.
Windows:
  • Retrieve the user profile folder using SHGetKnownFolderPath.
  • If this fails, then the function returns None.

Note: This logic differs from std::env::home_dir, which works incorrectly on Linux, macOS and Windows.

source

pub fn home_dir(&self) -> &Path

Returns the path to the user’s home directory.

PlatformValueExample
Linux$HOME/home/alice
macOS$HOME/Users/Alice
Windows{FOLDERID_Profile}C:\Users\Alice
source

pub fn cache_dir(&self) -> &Path

Returns the path to the user’s cache directory.

PlatformValueExample
Linux$XDG_CACHE_HOME or $HOME/.cache/home/alice/.cache
macOS$HOME/Library/Caches/Users/Alice/Library/Caches
Windows{FOLDERID_LocalAppData}C:\Users\Alice\AppData\Local
source

pub fn config_dir(&self) -> &Path

Returns the path to the user’s config directory.

PlatformValueExample
Linux$XDG_CONFIG_HOME or $HOME/.config/home/alice/.config
macOS$HOME/Library/Application Support/Users/Alice/Library/Application Support
Windows{FOLDERID_RoamingAppData}C:\Users\Alice\AppData\Roaming
source

pub fn config_local_dir(&self) -> &Path

Returns the path to the user’s local config directory.

PlatformValueExample
Linux$XDG_CONFIG_HOME or $HOME/.config/home/alice/.config
macOS$HOME/Library/Application Support/Users/Alice/Library/Application Support
Windows{FOLDERID_LocalAppData}C:\Users\Alice\AppData\Local
source

pub fn data_dir(&self) -> &Path

Returns the path to the user’s data directory.

PlatformValueExample
Linux$XDG_DATA_HOME or $HOME/.local/share/home/alice/.local/share
macOS$HOME/Library/Application Support/Users/Alice/Library/Application Support
Windows{FOLDERID_RoamingAppData}C:\Users\Alice\AppData\Roaming
source

pub fn data_local_dir(&self) -> &Path

Returns the path to the user’s local data directory.

PlatformValueExample
Linux$XDG_DATA_HOME or $HOME/.local/share/home/alice/.local/share
macOS$HOME/Library/Application Support/Users/Alice/Library/Application Support
Windows{FOLDERID_LocalAppData}C:\Users\Alice\AppData\Local
source

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

Returns the path to the user’s executable directory.

PlatformValueExample
Linux$XDG_BIN_HOME or $XDG_DATA_HOME/../bin or $HOME/.local/bin/home/alice/.local/bin
macOS
Windows
source

pub fn preference_dir(&self) -> &Path

Returns the path to the user’s preference directory.

PlatformValueExample
Linux$XDG_CONFIG_HOME or $HOME/.config/home/alice/.config
macOS$HOME/Library/Preferences/Users/Alice/Library/Preferences
Windows{FOLDERID_RoamingAppData}C:\Users\Alice\AppData\Roaming
source

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

Returns the path to the user’s runtime directory.

PlatformValueExample
Linux$XDG_RUNTIME_DIR/run/user/1001/
macOS
Windows
source

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

Returns the path to the user’s state directory.

The state directory contains data that should be retained between sessions (unlike the runtime directory), but may not be important/portable enough to be synchronized across machines (unlike the config/preferences/data directories).

The returned value depends on the operating system and is either a Some, containing a value from the following table, or a None.

PlatformValueExample
Linux$XDG_STATE_HOME or $HOME/.local/state/home/alice/.local/state
macOS
Windows

Trait Implementations§

source§

impl Clone for BaseDirs

source§

fn clone(&self) -> BaseDirs

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for BaseDirs

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.