Struct near_sdk::store::lookup_map::LookupMap
source · pub struct LookupMap<K, V, H = Identity>{ /* private fields */ }
Expand description
A non-iterable, lazily loaded storage map that stores its content directly on the storage trie.
This map stores the values under a hash of the map’s prefix
and BorshSerialize
of the key
and transformed using the map’s ToKey
implementation.
The default hash function for LookupMap
is Identity
which just prefixes the serialized
key object and uses these bytes as the key. This is to be backwards-compatible with
collections::LookupMap
and be fast for small keys.
To use a custom function, use with_hasher
. Alternative builtin hash functions can be found
at near_sdk::store::key
.
§Examples
use near_sdk::store::LookupMap;
// Initializes a map, the generic types can be inferred to `LookupMap<String, u8, Identity>`
// The `b"a"` parameter is a prefix for the storage keys of this data structure.
let mut map = LookupMap::new(b"a");
map.set("test".to_string(), Some(7u8));
assert!(map.contains_key("test"));
assert_eq!(map.get("test"), Some(&7u8));
let prev = map.insert("test".to_string(), 5u8);
assert_eq!(prev, Some(7u8));
assert_eq!(map["test"], 5u8);
LookupMap
also implements an Entry API
, which allows
for more complex methods of getting, setting, updating and removing keys and
their values:
use near_sdk::store::LookupMap;
// type inference lets us omit an explicit type signature (which
// would be `LookupMap<String, u8>` in this example).
let mut player_stats = LookupMap::new(b"m");
fn random_stat_buff() -> u8 {
// could actually return some random value here - let's just return
// some fixed value for now
42
}
// insert a key only if it doesn't already exist
player_stats.entry("health".to_string()).or_insert(100);
// insert a key using a function that provides a new value only if it
// doesn't already exist
player_stats.entry("defence".to_string()).or_insert_with(random_stat_buff);
// update a key, guarding against the key possibly not being set
let stat = player_stats.entry("attack".to_string()).or_insert(100);
*stat += random_stat_buff();
Implementations§
source§impl<K, V> LookupMap<K, V, Identity>
impl<K, V> LookupMap<K, V, Identity>
sourcepub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
pub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
Create a new LookupMap
with the prefix provided.
This prefix can be anything that implements IntoStorageKey
. The prefix is used when
storing and looking up values in storage to ensure no collisions with other collections.
§Examples
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
source§impl<K, V, H> LookupMap<K, V, H>
impl<K, V, H> LookupMap<K, V, H>
sourcepub fn with_hasher<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
pub fn with_hasher<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
sourcepub fn set(&mut self, key: K, value: Option<V>)
pub fn set(&mut self, key: K, value: Option<V>)
Overwrites the current value for the given key.
This function will not load the existing value from storage and return the value in storage.
Use LookupMap::insert
if you need the previous value.
Calling set
with a None
value will delete the entry from storage.
§Example
use near_sdk::store::LookupMap;
let mut map = LookupMap::new(b"m");
map.set("test".to_string(), Some(7u8));
assert!(map.contains_key("test"));
//Delete the entry from storage
map.set("test".to_string(), None);
assert!(!map.contains_key("test"));
source§impl<K, V, H> LookupMap<K, V, H>
impl<K, V, H> LookupMap<K, V, H>
sourcepub fn get<Q>(&self, k: &Q) -> Option<&V>
pub fn get<Q>(&self, k: &Q) -> Option<&V>
Returns a reference to the value corresponding to the key.
The key may be any borrowed form of the map’s key type, but
BorshSerialize
and ToOwned<Owned = K>
on the borrowed form must match those for
the key type.
§Example
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
map.insert(1, "a".to_string());
assert_eq!(map.get(&1), Some(&"a".to_string()));
assert_eq!(map.get(&2), None);
sourcepub fn get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>
pub fn get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>
Returns a mutable reference to the value corresponding to the key.
The key may be any borrowed form of the map’s key type, but
BorshSerialize
and ToOwned<Owned = K>
on the borrowed form must match those for
the key type.
§Example
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
map.insert(1, "a".to_string());
if let Some(x) = map.get_mut(&1) {
*x = "b".to_string();
assert_eq!(map[&1], "b".to_string());
}
sourcepub fn insert(&mut self, k: K, v: V) -> Option<V>where
K: Clone,
pub fn insert(&mut self, k: K, v: V) -> Option<V>where
K: Clone,
Inserts a key-value pair into the map.
If the map did not have this key present, None
is returned.
If the map did have this key present, the value is updated, and the old
value is returned. The key is not updated, though; this matters for
types that can be ==
without being identical.
§Example
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
assert_eq!(map.insert(37, "a".to_string()), None);
assert_eq!(map.contains_key(&37), true);
map.insert(37, "b".to_string());
assert_eq!(map.insert(37, "c".to_string()), Some("b".to_string()));
assert_eq!(map[&37], "c".to_string());
sourcepub fn contains_key<Q>(&self, k: &Q) -> bool
pub fn contains_key<Q>(&self, k: &Q) -> bool
Returns true
if the map contains a value for the specified key.
The key may be any borrowed form of the map’s key type, but
BorshSerialize
and ToOwned<Owned = K>
on the borrowed form must match those for
the key type.
§Example
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
map.insert(1, "a".to_string());
assert_eq!(map.contains_key(&1), true);
assert_eq!(map.contains_key(&2), false);
sourcepub fn remove<Q>(&mut self, k: &Q) -> Option<V>
pub fn remove<Q>(&mut self, k: &Q) -> Option<V>
Removes a key from the map, returning the value at the key if the key was previously in the map.
The key may be any borrowed form of the map’s key type, but
BorshSerialize
and ToOwned<Owned = K>
on the borrowed form must match those for
the key type.
§Example
use near_sdk::store::LookupMap;
let mut map: LookupMap<u32, String> = LookupMap::new(b"m");
map.insert(1, "a".to_string());
assert_eq!(map.remove(&1), Some("a".to_string()));
assert_eq!(map.remove(&1), None);
sourcepub fn entry(&mut self, key: K) -> Entry<'_, K, V>where
K: Clone,
pub fn entry(&mut self, key: K) -> Entry<'_, K, V>where
K: Clone,
Gets the given key’s corresponding entry in the map for in-place manipulation.
use near_sdk::store::LookupMap;
let mut count = LookupMap::new(b"m");
for ch in [7, 2, 4, 7, 4, 1, 7] {
let counter = count.entry(ch).or_insert(0);
*counter += 1;
}
assert_eq!(count[&4], 2);
assert_eq!(count[&7], 3);
assert_eq!(count[&1], 1);
assert_eq!(count.get(&8), None);
Trait Implementations§
source§impl<K, V, H> BorshDeserialize for LookupMap<K, V, H>
impl<K, V, H> BorshDeserialize for LookupMap<K, V, H>
fn deserialize_reader<R: Read>(reader: &mut R) -> Result<Self, Error>
source§fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>
fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>
source§fn try_from_slice(v: &[u8]) -> Result<Self, Error>
fn try_from_slice(v: &[u8]) -> Result<Self, Error>
fn try_from_reader<R>(reader: &mut R) -> Result<Self, Error>where
R: Read,
source§impl<K, V, H> BorshSerialize for LookupMap<K, V, H>
impl<K, V, H> BorshSerialize for LookupMap<K, V, H>
source§impl<K, V, H> Extend<(K, V)> for LookupMap<K, V, H>
impl<K, V, H> Extend<(K, V)> for LookupMap<K, V, H>
source§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (K, V)>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (K, V)>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)