Struct nonvolatile::State

pub struct State { /* fields omitted */ }

Implementations

impl State

pub fn set<T>(&mut self, var: &str, value: T) -> Result<()> where
    T: Serialize, 

Set a variable with name var and value value.

The name of the set value must be distinct from any other values you set, but otherwise no restrictions apply. The type of value must be serializable, but no other restrictions apply.

The value is written out to storage immediately.

Example

let my_var = String::from("this is like a string or something");
state.set("my var", my_var);

let some_other_var: HashMap<u64, String> = HashMap::new();
... //add some stuff to the map
state.set("some_other_var", some_other_var.clone()) //save the map for later!

pub fn get<'de, T>(&self, var: &str) -> Option<T> where
    for<'a> T: Deserialize<'a>, 

Try to retrieve a variable that was previously written to storage.

The return will be the value if it can be found, or None if:

• no value with that name is stored, or
• the stored value had a type incompatible with the get call.

get does not modify or remove the stored value, it only reads it.

Example

let my_var: String = state.get("my var");

let some_other_var = state.get::<HashMap<u64, String>>("some_other_var");

pub fn has(&self, item: &str) -> bool

Check if the given item/key exists in the state.

Example

state.delete("user_wants_to_die");
println!("{}", state.has("user_wants_to_die")); // false
state.set("user_wants_to_die", true);
println!("{}", state.has("user_wants_to_die")); // true

pub fn delete(&mut self, name: &str) -> Result<()>

Delete a stored variable. If the variable does not exist, nothing happens.

Example

let my_var = String::from("wait no don't delete me");
state.set("my var", my_var);
...
 // oop, looks like we don't need my_var to be stored for some reason
state.delete("my var");

pub fn load_else_create(name: &str) -> Result<State>

Load state of the given name if it exists. If not, create new state and return that.

The name must obey naming rules for your filesystem. To simplify cross platform compatibility, names are restricted to alphanumeric characters, spaces, and any of -_~.().

Example

let state = State::load_else_create("my_state");
let my_var = String::from("this is like a string or something");
state.set("my var", &my_var);

pub fn load_else_create_from(name: &str, storage_path: &str) -> Result<State>

Load state of the given name from the given custom storage location if the state exists exists. If not, create new state at the custom location and return that.

The name must obey naming rules for your filesystem. To simplify cross platform compatibility, names are restricted to alphanumeric characters, spaces, and any of -_~.().

the storage path may be relative or absolute, and doesn’t have to already exist (but it must be creatable). The state will be stored in <storage_path>/<name>. Accessing that location directly is not recommended.

Example

let state = State::load_else_create_from("my_state", ".");	// load or create state from the CWD
let my_var = String::from("this is like a string or something");
state.set("my var", &my_var);

pub fn new(name: &str) -> Result<State>

Create a new State object with the given name.

The name must obey naming rules for your filesystem. To simplify cross platform compatibility, names are restricted to alphanumeric characters, spaces, and any of -_~.().

If there is a preexisting state with that name, it will be overwritten by new. If the preexisting state is open by someone or something else, then new will fail and return an error.

Example

let state = State::new("my_state");
let my_var = String::from("this is like a string or something");
state.set("my var", my_var);

pub fn new_from(name: &str, storage_path: &str) -> Result<State>

Create a new State object with the given name, and a custom storage location.

The name must obey naming rules for your filesystem. To simplify cross platform compatibility, names are restricted to alphanumeric characters, spaces, and any of -_~.().

the storage path may be relative or absolute, and doesn’t have to already exist (but it must be creatable). The state will be stored in <storage_path>/<name>. Accessing that location directly is not recommended.

If there is a preexisting state with that name, it will be overwritten by new_from. If the preexisting state is open by someone or something else, then new_from will fail and return an error.

Example

let state = State::new_from("my_state", ".");	// create the state in the CWD
let my_var = String::from("this is like a string or something");
state.set("my var", my_var);

pub fn load(name: &str) -> Result<State>

Attempt to load state of the given name

If there is no state with that name, an error will be returned.

Example

let state = State::load("my_state");
let my_var = String::from("this is like a string or something");
state.set("my var", my_var);

pub fn load_from(name: &str, storage_path: &str) -> Result<State>

Attempt to load state of the given name from a custom storage location.

If there is no state with that name at that location, an error will be returned.

Example

let state = State::load_from("my_state", ".");	// load state from the CWD
let my_var = String::from("this is like a string or something");
state.set("my var", &my_var);

pub fn destroy_state(name: &str)

Destroy the state of the given name. If no state exists with that name, nothing happens.

Example

let state = State::load_else_create("foo").unwrap();
... // do stuff with the state
drop(state);

 // ... 

 //oh, turns out we don't need those settings stored after all...?
State::destroy_state("foo");

pub fn destroy_state_from(name: &str, storage_path: &str)

Destroy the state of the given name at the given custom storage location. If no state exists with that name at that location, nothing happens.

Example

let state = State::load_else_create_from("foo", ".").unwrap(); // load or create the state in the CWD
... // do stuff with the state
drop(state);

 // ... 

 //oh, turns out we don't need those settings stored after all...?
State::destroy_state_from("foo", ".");

Trait Implementations

impl Debug for State

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for State

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Drop for State

fn drop(&mut self)

Executes the destructor for this type.

impl Serialize for State

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.