Trait preferences_serde1::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_serde1::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.

§Failures

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.