Struct LookupMap

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

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

impl<K, V> LookupMap<K, V, Identity>

where K: BorshSerialize + Ord, V: BorshSerialize,

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

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

impl<K, V, H> LookupMap<K, V, H>

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

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

where S: IntoStorageKey,

Initialize a LookupMap with a custom hash function.

Example

use near_sdk::store::{LookupMap, key::Keccak256};

let map = LookupMap::<String, String, Keccak256>::with_hasher(b"m");

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

impl<K, V, H> LookupMap<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.

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

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.

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

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

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.

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

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

where K: Borrow<Q>, 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.

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

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

impl<K, V, H> LookupMap<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.

Trait Implementations

impl<K, V, H> BorshDeserialize for LookupMap<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> BorshSchema for LookupMap<K, V, H>

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

fn declaration() -> Declaration

Get the name of the type without brackets.

fn add_definitions_recursively( definitions: &mut BTreeMap<Declaration, Definition>, )

Recursively, using DFS, add type definitions required for this type. Type definition partially explains how to serialize/deserialize a type.

impl<K, V, H> BorshSerialize for LookupMap<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 LookupMap<K, V, H>

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

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

Formats the value using the given formatter.

impl<K, V, H> Drop for LookupMap<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 LookupMap<K, V, H>

where K: BorshSerialize + Ord, V: BorshSerialize, 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 LookupMap<K, V, H>

where K: BorshSerialize + Ord + 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.