Struct MapMapper 

pub struct MapMapper<SA, K, V, A = CurrentStorage>
where
    SA: StorageMapperApi,
    K: TopEncode + TopDecode + NestedEncode + NestedDecode + 'static,
    A: StorageAddress<SA>,
    V: TopEncode + TopDecode + 'static,
{ /* private fields */ }

A storage mapper implementing a key-value map with efficient lookup and iteration.

Storage Layout

The MapMapper uses a SetMapper to track keys and stores values separately:

1. Key tracking (via SetMapper):

   • base_key + ".info" → QueueMapperInfo (length, front, back, new node counter)
   • base_key + ".node_links" + node_id → Node structure (previous, next)
   • base_key + ".value" + node_id → key value
   • base_key + ".node_id" + encoded_key → node ID lookup

2. Value storage:

   • base_key + ".mapped" + encoded_key → value associated with the key

Main Operations

• Insert: insert(key, value) - Adds or updates a key-value pair. Returns old value if key existed. O(1).
• Remove: remove(key) - Removes a key-value pair. Returns the value if it existed. O(1).
• Lookup: get(key) - Retrieves the value for a key. O(1) with one storage read.
• Contains: contains_key(key) - Checks if a key exists. O(1) with one storage read.
• Entry API: entry(key) - Provides entry-based manipulation (or_insert, and_modify, etc.).
• Iteration: iter() - Iterates over (key, value) pairs; keys() - keys only; values() - values only.

Trade-offs

• Pros: Familiar HashMap-like API; efficient lookups; supports entry pattern for conditional updates.
• Cons: Uses more storage than simple key-value pairs (overhead from SetMapper); iteration order is arbitrary.

Example

// Insert key-value pairs
mapper.insert(1, 100);
mapper.insert(2, 200);
mapper.insert(3, 300);

assert_eq!(mapper.get(&2), Some(200));
assert_eq!(mapper.len(), 3);

// Update using entry API
mapper.entry(2).and_modify(|v| *v += 50);
assert_eq!(mapper.get(&2), Some(250));

// Remove a key
let removed = mapper.remove(&1);
assert_eq!(removed, Some(100));
assert_eq!(mapper.len(), 2);

// Iterate over key-value pairs
for (key, value) in mapper.iter() {
    // Process pairs
}

Implementations

impl<SA, K, V> MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode, V: TopEncode + TopDecode,

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

Sets the value of the entry, and returns the entry’s old value.

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

Takes the value out of the entry, and returns it.

impl<SA, A, K, V> MapMapper<SA, K, V, A>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode, A: StorageAddress<SA>, V: TopEncode + TopDecode,

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

Returns true if the map contains a value for the specified key.

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

Gets a reference to the value in the entry.

pub fn keys(&self) -> Iter<'_, SA, A, K>

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

pub fn len(&self) -> usize

Returns the number of elements in the map.

pub fn entry(&mut self, key: K) -> Entry<'_, SA, A, K, V>

Gets the given key’s corresponding entry in the map for in-place manipulation.

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

An iterator visiting all values in arbitrary order. The iterator element type is &'a V.

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

An iterator visiting all key-value pairs in arbitrary order. The iterator element type is (&'a K, &'a V).

Trait Implementations

impl<'a, SA, A, K, V> IntoIterator for &'a MapMapper<SA, K, V, A>

where SA: StorageMapperApi, A: StorageAddress<SA>, K: TopEncode + TopDecode + NestedEncode + NestedDecode, V: TopEncode + TopDecode,

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, SA, A, K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<SA, K, V> StorageClearable for MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode, V: TopEncode + TopDecode,

fn clear(&mut self)

Clears all the entries owned by the storage.

impl<SA, K, V> StorageMapper<SA> for MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode, V: TopEncode + TopDecode,

fn new(base_key: StorageKey<SA>) -> Self

Will be called automatically by the #[storage_mapper] annotation generated code.

impl<SA, K, V> StorageMapperFromAddress<SA> for MapMapper<SA, K, V, ManagedAddress<SA>>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode, V: TopEncode + TopDecode,

fn new_from_address( address: ManagedAddress<SA>, base_key: StorageKey<SA>, ) -> Self

Will be called automatically by the #[storage_mapper_from_address] annotation generated code.

impl<SA, K, V> TopEncodeMulti for MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode + 'static, V: TopEncode + TopDecode + 'static,

Behaves like a MultiResultVec<MultiValue2<K, V>> when an endpoint result.

fn multi_encode_or_handle_err<O, H>( &self, output: &mut O, h: H, ) -> Result<(), H::HandledErr>

where O: TopEncodeMultiOutput, H: EncodeErrorHandler,

Version of top_encode that can handle errors as soon as they occur. For instance in can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn multi_encode<O>(&self, output: &mut O) -> Result<(), EncodeError>

where O: TopEncodeMultiOutput,

Attempt to serialize the value to output.

impl<SA, K, V> TypeAbi for MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode + TypeAbi + 'static, V: TopEncode + TopDecode + TypeAbi + 'static,

Behaves like a MultiResultVec<MultiValue<K, V>> when an endpoint result.

type Unmanaged = MapMapper<SA, K, V>

fn type_name() -> TypeName

The type name, as it shows up in the ABI.

fn type_name_rust() -> TypeName

The type name as it shows up in Rust code. Used for proxies.

fn provide_type_descriptions<TDC: TypeDescriptionContainer>( accumulator: &mut TDC, )

A type can provide more than its own name. For instance, a struct can also provide the descriptions of the type of its fields. TypeAbi doesn’t care for the exact accumulator type, which is abstracted by the TypeDescriptionContainer trait.

fn type_names() -> TypeNames

fn type_name_specific() -> Option<TypeName>

Specific name to be optionally added to the ABI.

impl<SA, K, V> TypeAbiFrom<MapMapper<SA, K, V>> for MapMapper<SA, K, V, CurrentStorage>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode + 'static, V: TopEncode + TopDecode + 'static,

impl<SA, K, V> TypeAbiFrom<MapMapper<SA, K, V>> for MultiValueEncoded<SA, MultiValue2<K, V>>

where SA: StorageMapperApi, K: TopEncode + TopDecode + NestedEncode + NestedDecode + 'static, V: TopEncode + TopDecode + 'static,