Struct ink_storage::Mapping

pub struct Mapping<K, V: Packed, KeyType: StorageKey = AutoKey> { /* private fields */ }

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

Important

The mapping requires its own pre-defined storage key where to store values. By default, the is automatically calculated using AutoKey during compilation. However, anyone can specify a storage key using ManualKey. Specifying the storage key can be helpful for upgradeable contracts or you want to be resistant to future changes of storage key calculation strategy.

This is an example of how you can do this:

use ink::storage::{traits::ManualKey, Mapping};

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

impl MyContract {
    #[ink(constructor)]
    pub fn new() -> Self {
        let mut instance = Self::default();
        let caller = Self::env().caller();
        let value: Balance = Default::default();
        instance.balances.insert(&caller, &value);
        instance
    }

}

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

Implementations

impl<K, V, KeyType> Mapping<K, V, KeyType>where
    V: Packed,
    KeyType: StorageKey,

pub const fn new() -> Self

Creates a new empty Mapping.

impl<K, V, KeyType> Mapping<K, V, KeyType>where
    K: Encode,
    V: Packed,
    KeyType: StorageKey,

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

Insert the given value to the contract storage.

Returns the size in bytes 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 take<Q>(&self, key: Q) -> Option<V>where
    Q: EncodeLike<K>,

Removes the value at key, returning the previous value at key from storage.

Returns None if no value exists at the given key. WARNING: this method uses the unstable interface, which is unsafe and normally is not available on production chains.

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) -> boolwhere
    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, KeyType> Debug for Mapping<K, V, KeyType>where
    V: Packed,
    KeyType: StorageKey,

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

Formats the value using the given formatter.

impl<K, V, KeyType> Default for Mapping<K, V, KeyType>where
    V: Packed,
    KeyType: StorageKey,

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

fn default() -> Self

Returns the “default value” for a type.

impl<K, V, KeyType> Storable for Mapping<K, V, KeyType>where
    V: Packed,
    KeyType: StorageKey,

fn encode<T: Output + ?Sized>(&self, _dest: &mut T)

Convert self to a slice and append it to the destination.

fn decode<I: Input>(_input: &mut I) -> Result<Self, Error>

Attempt to deserialize the value from input.

impl<K, V, Key, InnerKey> StorableHint<Key> for Mapping<K, V, InnerKey>where
    V: Packed,
    Key: StorageKey,
    InnerKey: StorageKey,

type Type = Mapping<K, V, Key>

Storable type with storage key inside.

type PreferredKey = InnerKey

The storage key that the type prefers. It can be overwritten by an auto-generated storage key.

impl<K, V, KeyType> StorageKey for Mapping<K, V, KeyType>where
    V: Packed,
    KeyType: StorageKey,

const KEY: Key = KeyType::KEY

Storage key of the type.

fn key(&self) -> u32

Returns the storage key.

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

fn layout(_: &Key) -> Layout

Returns the static storage layout of Self.

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

type Identity = Mapping<K, V, KeyType>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.