Struct ink_storage::Mapping

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

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§

source§

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

source

pub const fn new() -> Self

Creates a new empty Mapping.

source§

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

source

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.

Panics

Traps if encoding the key together with the value doesn’t fit into the static buffer.

source

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

Try to insert the given value into the mapping under given key.

Fails if key or value exceeds the static buffer size.

Returns:

  • Ok(Some(_)) if the value was inserted successfully, containing the size in bytes of the pre-existing value at the specified key if any.
  • Ok(None) if the insert was successful but there was no pre-existing value.
  • Err(_) if encoding the key together with the value exceeds the static buffer size.
source

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.

Panics

Traps if the the encoded key or value doesn’t fit into the static buffer.

source

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

Try to get the value at the given key.

Returns:

  • Some(Ok(_)) containing the value if it existed and was decoded successfully.
  • Some(Err(_)) if either (a) the encoded key doesn’t fit into the static buffer or (b) the value existed but its length exceeds the static buffer size.
  • None if there was no value under this mapping key.
source

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.

Panics

Traps if the encoded key or value doesn’t fit into the static buffer.

Warning

This method uses the unstable interface, which is unsafe and normally is not available on production chains.

source

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

Try to take the value at the given key. On success, this operation will remove the value from the mapping

Returns:

  • Some(Ok(_)) containing the value if it existed and was decoded successfully.
  • Some(Err(_)) if either (a) the encoded key doesn’t fit into the static buffer or (b) the value existed but its length exceeds the static buffer size.
  • None if there was no value under this mapping key.
Warning

This method uses the unstable interface, which is unsafe and normally is not available on production chains.

source

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

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

Returns None if no value exists at the given key.

source

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 false if no value exists at the given key.

source

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

Clears the value at key from storage.

Trait Implementations§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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.

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

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

source§

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

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

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

Attempt to deserialize the value from input.
source§

fn encoded_size(&self) -> usize

The exact number of bytes this type consumes in the encoded form.
source§

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.
source§

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

source§

const KEY: Key = KeyType::KEY

Storage key of the type.
source§

fn key(&self) -> u32

Returns the storage key.
source§

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

source§

fn layout(_: &Key) -> Layout

Returns the static storage layout of Self. Read more
source§

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. Read more
source§

fn type_info() -> Type

Returns the static type identifier for Self.

Auto Trait Implementations§

§

impl<K, V, KeyType> RefUnwindSafe for Mapping<K, V, KeyType>

§

impl<K, V, KeyType> Send for Mapping<K, V, KeyType>

§

impl<K, V, KeyType> Sync for Mapping<K, V, KeyType>

§

impl<K, V, KeyType> Unpin for Mapping<K, V, KeyType>

§

impl<K, V, KeyType> UnwindSafe for Mapping<K, V, KeyType>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Conv for T

§

fn conv<T>(self) -> Twhere Self: Into<T>,

Converts self into T using Into<T>. Read more
§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pipe for Twhere T: ?Sized,

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> Rwhere Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> Rwhere Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R ) -> Rwhere Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> StaticTypeInfo for Twhere T: TypeInfo + 'static,