Struct ink_storage::Mapping

pub struct Mapping<K, V> { /* private fields */ }

A mapping of key-value pairs directly into contract storage.

Important

If you use this data structure you must use the function ink_lang::utils::initialize_contract in your contract’s constructors!

Note that in order to use this function your contract’s storage struct must implement the SpreadAllocate trait.

This is an example of how you can do this:

use ink_storage::{traits::SpreadAllocate, Mapping};

#[ink(storage)]
#[derive(SpreadAllocate)]
pub struct MyContract {
    balances: Mapping<AccountId, Balance>,
}

impl MyContract {
    #[ink(constructor)]
    pub fn new() -> Self {
        ink_lang::utils::initialize_contract(Self::new_init)
    }

    /// Default initializes the contract.
    fn new_init(&mut self) {
        let caller = Self::env().caller();
        let value: Balance = Default::default();
        self.balances.insert(&caller, &value);
    }
}

More usage examples can be found in the ink! examples.

Implementations

impl<K, V> Mapping<K, V> where
    K: PackedLayout,
    V: PackedLayout, 

pub fn insert<Q, R>(&mut self, key: Q, value: &R) where
    Q: EncodeLike<K>,
    R: EncodeLike<V> + PackedLayout, 

Insert the given value to the contract storage.

pub fn insert_return_size<Q, R>(&mut self, key: Q, value: &R) -> Option<u32> where
    Q: EncodeLike<K>,
    R: EncodeLike<V> + PackedLayout, 

Insert the given value to the contract storage.

Returns the size of the pre-existing value at the specified key if any.

pub fn get<Q>(&self, key: Q) -> Option<V> where
    Q: EncodeLike<K>, 

Get the value at key from the contract storage.

Returns None if no value exists at the given key.

pub fn size<Q>(&self, key: Q) -> Option<u32> where
    Q: EncodeLike<K>, 

Get the size of a value stored at key in the contract storage.

Returns None if no value exists at the given key.

pub fn contains<Q>(&self, key: Q) -> bool where
    Q: EncodeLike<K>, 

Checks if a value is stored at the given key in the contract storage.

Returns None if no value exists at the given key.

pub fn remove<Q>(&self, key: Q) where
    Q: EncodeLike<K>, 

Clears the value at key from storage.

Trait Implementations

impl<K, V> Debug for Mapping<K, V>

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

Formats the value using the given formatter.

impl<K, V> Default for Mapping<K, V>

We implement this manually because the derived implementation adds trait bounds.

fn default() -> Self

Returns the “default value” for a type.

impl<K, V> SpreadAllocate for Mapping<K, V>

fn allocate_spread(ptr: &mut KeyPtr) -> Self

Default initializes the implementing type using spread layout.

impl<K, V> SpreadLayout for Mapping<K, V>

const FOOTPRINT: u64 = 1u64

The footprint of the type.

const REQUIRES_DEEP_CLEAN_UP: bool = false

Indicates whether a type requires deep clean-up of its state meaning that a clean-up routine has to decode an entity into an instance in order to eventually recurse upon its tear-down. This is not required for the majority of primitive data types such as i32, however types such as storage::Box that might want to forward the clean-up procedure to their inner T require a deep clean-up.

fn pull_spread(ptr: &mut KeyPtr) -> Self

Pulls an instance of Self from the contract storage.

fn push_spread(&self, ptr: &mut KeyPtr)

Pushes an instance of Self to the contract storage.

fn clear_spread(&self, ptr: &mut KeyPtr)

Clears an instance of Self from the contract storage.

impl<K, V> StorageLayout for Mapping<K, V> where
    K: TypeInfo + 'static,
    V: TypeInfo + 'static, 

fn layout(key_ptr: &mut KeyPtr) -> Layout

Returns the static storage layout of Self.

impl<K, V> TypeInfo for Mapping<K, V> where
    PhantomData<fn() -> (K, V)>: TypeInfo + 'static,
    K: TypeInfo + 'static,
    V: TypeInfo + 'static, 

type Identity = Mapping<K, V>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.