Struct near_sdk::store::unordered_map::UnorderedMap

pub struct UnorderedMap<K, V, H = Sha256>
where
    K: BorshSerialize + Ord,
    V: BorshSerialize,
    H: ToKey,
{ /* private fields */ }

👎Deprecated since 5.0.0: Suboptimal iteration performance. See performance considerations doc for details.

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.

Performance considerations

Note that this collection is optimized for fast removes at the expense of key management. If the amount of removes is significantly higher than the amount of inserts the iteration becomes more costly. See remove for details. If this is the use-case - see ’UnorderedMap`.

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

impl<K, V> UnorderedMap<K, V, Sha256>

where K: BorshSerialize + Ord, V: BorshSerialize,

pub fn new<S>(prefix: S) -> Self

where 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");

impl<K, V, H> UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, H: ToKey,

pub fn with_hasher<S>(prefix: S) -> Self

where 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");

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);

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());

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());

pub fn iter(&self) -> Iter<'_, K, V, H>

where K: BorshDeserialize,

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);
}

pub fn iter_mut(&mut self) -> IterMut<'_, K, V, H>

where K: BorshDeserialize,

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);
}

pub fn keys(&self) -> Keys<'_, K>

where K: BorshDeserialize,

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);
}

pub fn values(&self) -> Values<'_, K, V, H>

where K: BorshDeserialize,

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);
}

pub fn values_mut(&mut self) -> ValuesMut<'_, K, V, H>

where K: BorshDeserialize,

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);
}

pub fn drain(&mut self) -> Drain<'_, K, V, H>

where K: BorshDeserialize,

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());

impl<K, V, H> UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize + BorshDeserialize, H: ToKey,

pub fn get<Q>(&self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: BorshSerialize + ToOwned<Owned = K> + ?Sized,

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));

pub fn get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: BorshSerialize + ToOwned<Owned = K> + ?Sized,

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);

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]);

pub fn contains_key<Q>(&self, k: &Q) -> bool

where K: Borrow<Q>, Q: BorshSerialize + ToOwned<Owned = K> + Ord + ?Sized,

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"));

pub fn remove<Q>(&mut self, k: &Q) -> Option<V>

where K: Borrow<Q> + BorshDeserialize, Q: BorshSerialize + ToOwned<Owned = K> + ?Sized,

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.

Performance

When elements are removed, the underlying vector of keys isn’t rearranged; instead, the removed key is replaced with a placeholder value. These empty slots are reused on subsequent insert operations.

In cases where there are a lot of removals and not a lot of insertions, these leftover placeholders might make iteration more costly, driving higher gas costs. If you need to remedy this, take a look at defrag.

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);

pub fn remove_entry<Q>(&mut self, k: &Q) -> Option<(K, V)>

where K: Borrow<Q> + BorshDeserialize, Q: BorshSerialize + ToOwned<Owned = K> + ?Sized,

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.

Performance

When elements are removed, the underlying vector of keys isn’t rearranged; instead, the removed key is replaced with a placeholder value. These empty slots are reused on subsequent insert operations.

In cases where there are a lot of removals and not a lot of insertions, these leftover placeholders might make iteration more costly, driving higher gas costs. If you need to remedy this, take a look at defrag.

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);

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);

impl<K, V, H> UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, H: ToKey,

pub fn flush(&mut self)

Flushes the intermediate values of the map before this is called when the structure is Droped. This will write all modified values to storage but keep all cached values in memory.

impl<K, V, H> UnorderedMap<K, V, H>

where K: BorshSerialize + BorshDeserialize + Ord + Clone, V: BorshSerialize + BorshDeserialize, H: ToKey,

pub fn defrag(&mut self)

Remove empty placeholders leftover from calling remove.

When elements are removed using remove, the underlying vector isn’t rearranged; instead, the removed element is replaced with a placeholder value. These empty slots are reused on subsequent insert operations.

In cases where there are a lot of removals and not a lot of insertions, these leftover placeholders might make iteration more costly, driving higher gas costs. This method is meant to remedy that by removing all empty slots from the underlying vector and compacting it.

Note that this might exceed the available gas amount depending on the amount of free slots, therefore has to be used with caution.

Examples

use near_sdk::store::UnorderedMap;

let mut map = UnorderedMap::new(b"b");

for i in 0..4 {
    map.insert(i, i);
}

map.remove(&1);
map.remove(&3);

map.defrag();

Trait Implementations

impl<K, V, H> BorshDeserialize for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, H: ToKey,

fn deserialize_reader<R: Read>(reader: &mut R) -> Result<Self, Error>

fn deserialize(buf: &mut &[u8]) -> Result<Self, Error>

Deserializes this instance from a given slice of bytes. Updates the buffer to point at the remaining bytes.

fn try_from_slice(v: &[u8]) -> Result<Self, Error>

Deserialize this instance from a slice of bytes.

fn try_from_reader<R>(reader: &mut R) -> Result<Self, Error>

where R: Read,

impl<K, V, H> BorshSerialize for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, H: ToKey,

fn serialize<W: Write>(&self, writer: &mut W) -> Result<(), Error>

impl<K, V, H> Debug for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord + BorshDeserialize + Debug, V: BorshSerialize, H: ToKey,

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

Formats the value using the given formatter.

impl<K, V, H> Drop for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, H: ToKey,

fn drop(&mut self)

Executes the destructor for this type.

impl<K, V, H> Extend<(K, V)> for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord + BorshDeserialize + Clone, V: BorshSerialize + BorshDeserialize, H: ToKey,

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = (K, V)>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, V, H, Q> Index<&Q> for UnorderedMap<K, V, H>

where K: BorshSerialize + Ord + Clone + Borrow<Q>, V: BorshSerialize + BorshDeserialize, H: ToKey, Q: BorshSerialize + ToOwned<Owned = K> + ?Sized,

fn index(&self, index: &Q) -> &Self::Output

Returns reference to value corresponding to key.

Panics

Panics if the key does not exist in the map

type Output = V

The returned type after indexing.

impl<'a, K, V, H> IntoIterator for &'a UnorderedMap<K, V, H>

where K: BorshSerialize + Ord + BorshDeserialize + Clone, V: BorshSerialize + BorshDeserialize, H: ToKey,

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V, H>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V, H> IntoIterator for &'a mut UnorderedMap<K, V, H>

where K: BorshSerialize + Ord + BorshDeserialize + Clone, V: BorshSerialize + BorshDeserialize, H: ToKey,

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V, H>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.