Struct near_sdk::store::unordered_map::UnorderedMap
source · pub struct UnorderedMap<K, V, H = Sha256>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,{ /* private fields */ }
Expand description
A lazily loaded storage map that stores its content directly on the storage trie.
This structure is similar to near_sdk::store::LookupMap
, except
that it stores the keys so that UnorderedMap
can be iterable.
This map stores the values under a hash of the map’s prefix
and BorshSerialize
of the key
using the map’s ToKey
implementation.
The default hash function for UnorderedMap
is Sha256
which uses a syscall
(or host function) built into the NEAR runtime to hash the key. 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::UnorderedMap;
// Initializes a map, the generic types can be inferred to `UnorderedMap<String, u8, Sha256>`
// The `b"a"` parameter is a prefix for the storage keys of this data structure.
let mut map = UnorderedMap::new(b"a");
map.insert("test".to_string(), 7u8);
assert!(map.contains_key("test"));
assert_eq!(map.get("test"), Some(&7u8));
let prev = std::mem::replace(map.get_mut("test").unwrap(), 5u8);
assert_eq!(prev, 7u8);
assert_eq!(map["test"], 5u8);
UnorderedMap
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::UnorderedMap;
// type inference lets us omit an explicit type signature (which
// would be `UnorderedMap<String, u8>` in this example).
let mut player_stats = UnorderedMap::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
sourceimpl<K, V> UnorderedMap<K, V, Sha256>where
K: BorshSerialize + Ord,
V: BorshSerialize,
impl<K, V> UnorderedMap<K, V, Sha256>where
K: BorshSerialize + Ord,
V: BorshSerialize,
sourcepub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
pub fn new<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
Create a new iterable map. Use prefix
as a unique prefix for keys.
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::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
sourceimpl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
sourcepub fn with_hasher<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
pub fn with_hasher<S>(prefix: S) -> Selfwhere
S: IntoStorageKey,
Initialize a UnorderedMap
with a custom hash function.
Example
use near_sdk::store::{UnorderedMap, key::Keccak256};
let map = UnorderedMap::<String, String, Keccak256>::with_hasher(b"m");
sourcepub fn len(&self) -> u32
pub fn len(&self) -> u32
Return the amount of elements inside of the map.
Example
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
assert_eq!(map.len(), 0);
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
assert_eq!(map.len(), 2);
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if there are no elements inside of the map.
Example
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
assert!(map.is_empty());
map.insert("a".to_string(), 1);
assert!(!map.is_empty());
sourcepub fn clear(&mut self)where
K: BorshDeserialize + Clone,
V: BorshDeserialize,
pub fn clear(&mut self)where
K: BorshDeserialize + Clone,
V: BorshDeserialize,
Clears the map, removing all key-value pairs. Keeps the allocated memory for reuse.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
map.insert("a".to_string(), 1);
map.clear();
assert!(map.is_empty());
sourcepub fn iter(&self) -> Iter<'_, K, V, H>ⓘNotable traits for Iter<'a, K, V, H>impl<'a, K, V, H> Iterator for Iter<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a V);
where
K: BorshDeserialize,
pub fn iter(&self) -> Iter<'_, K, V, H>ⓘNotable traits for Iter<'a, K, V, H>impl<'a, K, V, H> Iterator for Iter<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a V);
where
K: BorshDeserialize,
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a V);
An iterator visiting all key-value pairs in arbitrary order.
The iterator element type is (&'a K, &'a V)
.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::new(b"m");
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
map.insert("c".to_string(), 3);
for (key, val) in map.iter() {
println!("key: {} val: {}", key, val);
}
sourcepub fn iter_mut(&mut self) -> IterMut<'_, K, V, H>ⓘNotable traits for IterMut<'a, K, V, H>impl<'a, K, V, H> Iterator for IterMut<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a mut V);
where
K: BorshDeserialize,
pub fn iter_mut(&mut self) -> IterMut<'_, K, V, H>ⓘNotable traits for IterMut<'a, K, V, H>impl<'a, K, V, H> Iterator for IterMut<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a mut V);
where
K: BorshDeserialize,
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (&'a K, &'a mut V);
An iterator visiting all key-value pairs in arbitrary order,
with exclusive references to the values.
The iterator element type is (&'a K, &'a mut V)
.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::new(b"m");
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
map.insert("c".to_string(), 3);
// Update all values
for (_, val) in map.iter_mut() {
*val *= 2;
}
for (key, val) in &map {
println!("key: {} val: {}", key, val);
}
sourcepub fn keys(&self) -> Keys<'_, K>ⓘNotable traits for Keys<'a, K>impl<'a, K> Iterator for Keys<'a, K>where
K: BorshSerialize + BorshDeserialize, type Item = &'a K;
where
K: BorshDeserialize,
pub fn keys(&self) -> Keys<'_, K>ⓘNotable traits for Keys<'a, K>impl<'a, K> Iterator for Keys<'a, K>where
K: BorshSerialize + BorshDeserialize, type Item = &'a K;
where
K: BorshDeserialize,
K: BorshSerialize + BorshDeserialize, type Item = &'a K;
An iterator visiting all keys in arbitrary order.
The iterator element type is &'a K
.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::new(b"m");
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
map.insert("c".to_string(), 3);
for key in map.keys() {
println!("{}", key);
}
sourcepub fn values(&self) -> Values<'_, K, V, H>ⓘNotable traits for Values<'a, K, V, H>impl<'a, K, V, H> Iterator for Values<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a V;
where
K: BorshDeserialize,
pub fn values(&self) -> Values<'_, K, V, H>ⓘNotable traits for Values<'a, K, V, H>impl<'a, K, V, H> Iterator for Values<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a V;
where
K: BorshDeserialize,
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a V;
An iterator visiting all values in arbitrary order.
The iterator element type is &'a V
.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::new(b"m");
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
map.insert("c".to_string(), 3);
for val in map.values() {
println!("{}", val);
}
sourcepub fn values_mut(&mut self) -> ValuesMut<'_, K, V, H>ⓘNotable traits for ValuesMut<'a, K, V, H>impl<'a, K, V, H> Iterator for ValuesMut<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a mut V;
where
K: BorshDeserialize,
pub fn values_mut(&mut self) -> ValuesMut<'_, K, V, H>ⓘNotable traits for ValuesMut<'a, K, V, H>impl<'a, K, V, H> Iterator for ValuesMut<'a, K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a mut V;
where
K: BorshDeserialize,
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = &'a mut V;
A mutable iterator visiting all values in arbitrary order.
The iterator element type is &'a mut V
.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::new(b"m");
map.insert("a".to_string(), 1);
map.insert("b".to_string(), 2);
map.insert("c".to_string(), 3);
for val in map.values_mut() {
*val = *val + 10;
}
for val in map.values() {
println!("{}", val);
}
sourcepub fn drain(&mut self) -> Drain<'_, K, V, H>ⓘNotable traits for Drain<'a, K, V, H>impl<'a, K, V, H> Iterator for Drain<'a, K, V, H>where
K: BorshSerialize + BorshDeserialize + Ord + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (K, V);
where
K: BorshDeserialize,
pub fn drain(&mut self) -> Drain<'_, K, V, H>ⓘNotable traits for Drain<'a, K, V, H>impl<'a, K, V, H> Iterator for Drain<'a, K, V, H>where
K: BorshSerialize + BorshDeserialize + Ord + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (K, V);
where
K: BorshDeserialize,
K: BorshSerialize + BorshDeserialize + Ord + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey, type Item = (K, V);
Clears the map, returning all key-value pairs as an iterator.
This will clear all values, even if only some key/value pairs are yielded.
Examples
use near_sdk::store::UnorderedMap;
let mut a = UnorderedMap::new(b"m");
a.insert(1, "a".to_string());
a.insert(2, "b".to_string());
for (k, v) in a.drain().take(1) {
assert!(k == 1 || k == 2);
assert!(&v == "a" || &v == "b");
}
assert!(a.is_empty());
sourceimpl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize + BorshDeserialize,
H: ToKey,
impl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize + BorshDeserialize,
H: ToKey,
sourcepub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>where
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K>,
pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>where
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K>,
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.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
assert!(map.insert("test".to_string(), 5u8).is_none());
assert_eq!(map.get("test"), Some(&5));
sourcepub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V>where
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K>,
pub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V>where
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K>,
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.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
assert!(map.insert("test".to_string(), 5u8).is_none());
*map.get_mut("test").unwrap() = 6;
assert_eq!(map["test"], 6);
sourcepub fn insert(&mut self, k: K, value: V) -> Option<V>where
K: Clone + BorshDeserialize,
pub fn insert(&mut self, k: K, value: V) -> Option<V>where
K: Clone + BorshDeserialize,
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.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
assert!(map.is_empty());
map.insert("a".to_string(), 1);
assert!(!map.is_empty());
assert_eq!(map.values().collect::<Vec<_>>(), [&1]);
sourcepub fn contains_key<Q: ?Sized>(&self, k: &Q) -> boolwhere
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K> + Ord,
pub fn contains_key<Q: ?Sized>(&self, k: &Q) -> boolwhere
K: Borrow<Q>,
Q: BorshSerialize + ToOwned<Owned = K> + Ord,
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.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
map.insert("test".to_string(), 7u8);
assert!(map.contains_key("test"));
sourcepub fn remove<Q: ?Sized>(&mut self, k: &Q) -> Option<V>where
K: Borrow<Q> + BorshDeserialize,
Q: BorshSerialize + ToOwned<Owned = K>,
pub fn remove<Q: ?Sized>(&mut self, k: &Q) -> Option<V>where
K: Borrow<Q> + BorshDeserialize,
Q: BorshSerialize + ToOwned<Owned = K>,
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.
Examples
use near_sdk::store::UnorderedMap;
let mut map: UnorderedMap<String, u8> = UnorderedMap::new(b"b");
map.insert("test".to_string(), 7u8);
assert_eq!(map.len(), 1);
map.remove("test");
assert_eq!(map.len(), 0);
sourcepub fn remove_entry<Q: ?Sized>(&mut self, k: &Q) -> Option<(K, V)>where
K: Borrow<Q> + BorshDeserialize,
Q: BorshSerialize + ToOwned<Owned = K>,
pub fn remove_entry<Q: ?Sized>(&mut self, k: &Q) -> Option<(K, V)>where
K: Borrow<Q> + BorshDeserialize,
Q: BorshSerialize + ToOwned<Owned = K>,
Removes a key from the map, returning the stored key and value 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.
Examples
use near_sdk::store::UnorderedMap;
let mut map = UnorderedMap::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::UnorderedMap;
let mut count = UnorderedMap::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);
sourceimpl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
Trait Implementations
sourceimpl<K, V, H> BorshDeserialize for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> BorshDeserialize for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
sourceimpl<K, V, H> BorshSerialize for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> BorshSerialize for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
sourceimpl<K, V, H> Debug for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Debug,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> Debug for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Debug,
V: BorshSerialize,
H: ToKey,
sourceimpl<K, V, H> Drop for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
impl<K, V, H> Drop for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord,
V: BorshSerialize,
H: ToKey,
sourceimpl<K, V, H> Extend<(K, V)> for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey,
impl<K, V, H> Extend<(K, V)> for UnorderedMap<K, V, H>where
K: BorshSerialize + Ord + BorshDeserialize + Clone,
V: BorshSerialize + BorshDeserialize,
H: ToKey,
sourcefn 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)>,
sourcefn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)sourcefn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)