Trait preferences::Preferences
[−]
[src]
pub trait Preferences: Sized { 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>; }
Trait for types that can be saved & loaded as user data.
This type is automatically implemented for any struct/enum T
which implements both
Encodable
and Decodable
(from rustc-serialize
). (Trivially, you can annotate the type
with #[derive(RustcEncodable, RustcDecodable)
). 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
fn save<S: AsRef<str>>(&self,
app: &AppInfo,
key: S)
-> Result<(), PreferencesError>
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.
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.
Failures
If a deserialization or file I/O error (e.g. permission denied) occurs, or if no user data
exists at that path
.
fn save_to<W: Write>(&self, writer: &mut W) -> Result<(), PreferencesError>
Same as save
, but writes the serialized preferences to an arbitrary writer.
fn load_from<R: Read>(reader: &mut R) -> Result<Self, PreferencesError>
Same as load
, but reads the serialized preferences from an arbitrary writer.