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,
impl<K, V, KeyType> Mapping<K, V, KeyType>where
V: Packed,
KeyType: StorageKey,
source§impl<K, V, KeyType> Mapping<K, V, KeyType>
impl<K, V, KeyType> Mapping<K, V, KeyType>
sourcepub fn insert<Q, R>(&mut self, key: Q, value: &R) -> Option<u32>
pub fn insert<Q, R>(&mut self, key: Q, value: &R) -> Option<u32>
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.
sourcepub fn try_insert<Q, R>(&mut self, key: Q, value: &R) -> Result<Option<u32>>
pub fn try_insert<Q, R>(&mut self, key: Q, value: &R) -> Result<Option<u32>>
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 thekey
together with thevalue
exceeds the static buffer size.
sourcepub fn get<Q>(&self, key: Q) -> Option<V>where
Q: EncodeLike<K>,
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.
sourcepub fn try_get<Q>(&self, key: Q) -> Option<Result<V>>where
Q: EncodeLike<K>,
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.
sourcepub fn take<Q>(&self, key: Q) -> Option<V>where
Q: EncodeLike<K>,
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.
sourcepub fn try_take<Q>(&self, key: Q) -> Option<Result<V>>where
Q: EncodeLike<K>,
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.
sourcepub fn size<Q>(&self, key: Q) -> Option<u32>where
Q: EncodeLike<K>,
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
.
sourcepub fn contains<Q>(&self, key: Q) -> boolwhere
Q: EncodeLike<K>,
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
.
sourcepub fn remove<Q>(&self, key: Q)where
Q: EncodeLike<K>,
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> Default for Mapping<K, V, KeyType>where
V: Packed,
KeyType: StorageKey,
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§impl<K, V, KeyType> Storable for Mapping<K, V, KeyType>where
V: Packed,
KeyType: StorageKey,
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)
fn encode<T: Output + ?Sized>(&self, _dest: &mut T)
source§fn decode<I: Input>(_input: &mut I) -> Result<Self, Error>
fn decode<I: Input>(_input: &mut I) -> Result<Self, Error>
source§fn encoded_size(&self) -> usize
fn encoded_size(&self) -> usize
source§impl<K, V, Key, InnerKey> StorableHint<Key> for Mapping<K, V, InnerKey>
impl<K, V, Key, InnerKey> StorableHint<Key> for Mapping<K, V, InnerKey>
§type PreferredKey = InnerKey
type PreferredKey = InnerKey
source§impl<K, V, KeyType> StorageKey for Mapping<K, V, KeyType>where
V: Packed,
KeyType: StorageKey,
impl<K, V, KeyType> StorageKey for Mapping<K, V, KeyType>where
V: Packed,
KeyType: StorageKey,
source§impl<K, V, KeyType> StorageLayout for Mapping<K, V, KeyType>where
K: TypeInfo + 'static,
V: Packed + StorageLayout + TypeInfo + 'static,
KeyType: StorageKey + TypeInfo + 'static,
impl<K, V, KeyType> StorageLayout for Mapping<K, V, KeyType>where
K: TypeInfo + 'static,
V: Packed + StorageLayout + TypeInfo + 'static,
KeyType: StorageKey + TypeInfo + 'static,
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,
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,
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> FmtForward for T
impl<T> FmtForward for T
source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self
to use its Display
implementation when
Debug
-formatted.source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self
, then passes self.as_ref()
into the pipe function.source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self
, then passes self.as_mut()
into the pipe
function.source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self
, then passes self.deref()
into the pipe function.source§impl<T> Tap for T
impl<T> Tap for T
source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B>
of a value. Read moresource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B>
of a value. Read moresource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R>
view of a value. Read moresource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R>
view of a value. Read moresource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref()
only in debug builds, and is erased in release
builds.source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut()
only in debug builds, and is erased in release
builds.source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref()
only in debug builds, and is erased in release
builds.