Struct concordium_std::StateBuilder

pub struct StateBuilder<S> { /* private fields */ }

An state builder that allows the creation of StateMap, StateSet, and StateBox. It is parametrized by a parameter S that is assumed to implement HasStateApi.

The state_builder is designed to provide an abstraction over the contract state, abstracting over the exact keys (keys in the sense of key-value store, which is the low-level semantics of contract state) that are used when storing specific values.

Implementations

impl<S> StateBuilder<S>where
S: HasStateApi,

pub fn open(state: S) -> Self

Open a new state_builder. Only a single instance of the state_builder should exist during contract execution, thus this should only be called at the very beginning of execution.

pub fn new_map<K, V>(&mut self) -> StateMap<K, V, S>

Create a new empty StateMap.

pub fn new_set<T>(&mut self) -> StateSet<T, S>

Create a new empty StateSet.

pub fn new_box<T: Serial>(&mut self, value: T) -> StateBox<T, S>

Create a new StateBox and insert the value into the state. This stores the serialized value in the contract state. Thus if the StateBox is dropped without calling delete then the value will remain in contract state, leading to a space leak.

Note that this dropping can happen implicitly via assignment. For example,

struct MyState<S: HasStateApi> {
    inner: StateBox<u64, S>,
}
fn incorrect_replace<S: HasStateApi>(
    state_builder: &mut StateBuilder<S>,
    state: &mut MyState<S>,
) {
    // The following is incorrect. The old value of `inner` is not properly deleted.
    // from the state.
    state.inner = state_builder.new_box(0); // ⚠️
}

Instead, the old value should be manually deleted.

fn correct_replace<S: HasStateApi>(
    state_builder: &mut StateBuilder<S>,
    state: &mut MyState<S>,
) {
    let old_box = mem::replace(&mut state.inner, state_builder.new_box(0));
    old_box.delete()
}

impl StateBuilder<TestStateApi>

pub fn new() -> Self

Create a new Self with an empty TestStateApi.

Trait Implementations

impl<S: Default> Default for StateBuilder<S>

fn default() -> StateBuilder<S>

Returns the “default value” for a type.