Preferences

preferences

Trait Preferences 

Source 
pub trait Preferences: Sized {
    // Required methods
    fn save<S: AsRef<str>>(
        &self,
        app: &AppInfo,
        key: S,
    ) -> Result<(), PreferencesError>;
    fn load<S: AsRef<str>>(
        app: &AppInfo,
        key: S,
    ) -> Result<Self, PreferencesError>;
    fn save_to<W: Write>(&self, writer: &mut W) -> Result<(), PreferencesError>;
    fn load_from<R: Read>(reader: &mut R) -> Result<Self, PreferencesError>;
}
Expand description

Trait for types that can be saved & loaded as user data.

This type is automatically implemented for any struct/enum T which implements both Serialize and Deserialize (from serde). (Trivially, you can annotate the type with #[derive(Serialize, Deserialize)). It is encouraged to use the provided type, PreferencesMap, to bundle related user preferences.

For the app parameter of save(..) and load(..), it’s recommended that you use a single const instance of AppInfo that represents your program:

use preferences::AppInfo;
const APP_INFO: AppInfo = AppInfo{name: "Awesome App", author: "Dedicated Dev"};

The key parameter of save(..) and load(..) should be used to uniquely identify different preferences data. It roughly maps to a platform-dependent directory hierarchy, with forward slashes used as separators on all platforms. Keys are sanitized to be valid paths; to ensure human-readable paths, use only letters, digits, spaces, hyphens, underscores, periods, and slashes.

§Example keys

  • options/graphics
  • saves/quicksave
  • bookmarks/favorites

Required Methods§

Source

fn save<S: AsRef<str>>( &self, app: &AppInfo, key: S, ) -> Result<(), PreferencesError>

Saves the current state of this object. Implementation is platform-dependent, but the data will be local to the active user.

§Errors

If a serialization or file I/O error (e.g. permission denied) occurs.

Source

fn load<S: AsRef<str>>(app: &AppInfo, key: S) -> Result<Self, PreferencesError>

Loads this object’s state from previously saved user data with the same key. This is an instance method which completely overwrites the object’s state with the serialized data. Thus, it is recommended that you call this method immediately after instantiating the preferences object.

§Errors

If a deserialization or file I/O error (e.g. permission denied) occurs, or if no user data exists at that path.

Source

fn save_to<W: Write>(&self, writer: &mut W) -> Result<(), PreferencesError>

Same as save, but writes the serialized preferences to an arbitrary writer.

§Errors

If a write or serialization error occurs.

Source

fn load_from<R: Read>(reader: &mut R) -> Result<Self, PreferencesError>

Same as load, but reads the serialized preferences from an arbitrary writer.

§Errors

If a read or deserialization error occurs.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§