Struct BiDiMapper 

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

A storage mapper implementing a bidirectional map with one-to-one correspondence between IDs and values.

Storage Layout

The BiDiMapper uses two UnorderedSetMapper instances and maintains bidirectional lookups:

1. ID set (via UnorderedSetMapper):

   • base_key + "_id.len" → count of IDs
   • base_key + "_id.item" + index → ID at index (1-based)
   • base_key + "_id.index" + encoded_id → index of ID

2. Value set (via UnorderedSetMapper):

   • base_key + "_value.len" → count of values
   • base_key + "_value.item" + index → value at index (1-based)
   • base_key + "_value.index" + encoded_value → index of value

3. Bidirectional mappings:

   • base_key + "_value_to_id" + encoded_value → corresponding ID
   • base_key + "_id_to_value" + encoded_id → corresponding value

Main Operations

• Insert: insert(id, value) - Adds bidirectional mapping. O(1). Fails if ID or value already exists.
• Lookup ID: get_id(value) - Retrieves ID for a value. O(1) with one storage read.
• Lookup Value: get_value(id) - Retrieves value for an ID. O(1) with one storage read.
• Contains: contains_id(id) / contains_value(value) - Checks existence. O(1).
• Remove by ID: remove_by_id(id) - Removes by ID, clears both directions. O(1).
• Remove by Value: remove_by_value(value) - Removes by value, clears both directions. O(1).
• Batch Remove: remove_all_by_ids(iter) / remove_all_by_values(iter) - Removes multiple entries.
• Iteration: iter() - Iterates over (ID, value) pairs; get_all_ids() / get_all_values() - specific direction.

Uniqueness Guarantee

Both IDs and values must be unique:

• Each ID maps to exactly one value
• Each value maps to exactly one ID
• Inserting a duplicate ID or value fails and returns false

Trade-offs

• Pros: O(1) bidirectional lookup; enforces one-to-one correspondence; efficient for reverse lookups.
• Cons: Double storage overhead (two sets + two mappings); removal changes element positions (swap_remove); cannot have duplicate IDs or values; more complex than unidirectional maps.

Use Cases

• Token ID ↔ Token name mappings
• User address ↔ Username associations
• NFT ID ↔ Metadata hash relationships
• Any scenario requiring efficient lookup in both directions
• Implementing invertible mappings

Example

// Insert bidirectional mappings
assert!(mapper.insert(1, 100));
assert!(mapper.insert(2, 200));
assert!(mapper.insert(3, 300));

// Cannot insert duplicate ID or value
assert!(!mapper.insert(1, 400));  // ID 1 already exists
assert!(!mapper.insert(4, 100));  // Value 100 already exists

assert_eq!(mapper.len(), 3);

// Bidirectional lookup
assert_eq!(mapper.get_value(&2), 200);
assert_eq!(mapper.get_id(&200), 2);

// Check existence in both directions
assert!(mapper.contains_id(&1));
assert!(mapper.contains_value(&300));

// Remove by ID
assert!(mapper.remove_by_id(&2));
assert!(!mapper.contains_id(&2));
assert!(!mapper.contains_value(&200));  // Both directions removed
assert_eq!(mapper.len(), 2);

// Remove by value
assert!(mapper.remove_by_value(&100));
assert!(!mapper.contains_id(&1));
assert!(!mapper.contains_value(&100));

// Iterate over all mappings
for (id, value) in mapper.iter() {
    // Process each bidirectional pair
}

// Iterate only IDs or values
for id in mapper.get_all_ids() {
    // Process IDs
}
for value in mapper.get_all_values() {
    // Process values
}

// Batch removal
mapper.remove_all_by_ids(vec![3]);
assert!(mapper.is_empty());

Implementations

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

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

pub fn get_id(&self, value: &V) -> K

pub fn get_value(&self, id: &K) -> V

pub fn contains_id(&self, id: &K) -> bool

pub fn contains_value(&self, value: &V) -> bool

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

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

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

pub fn is_empty(&self) -> bool

pub fn len(&self) -> usize

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

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

pub fn insert(&mut self, id: K, value: V) -> bool

pub fn remove_by_id(&mut self, id: &K) -> bool

pub fn remove_by_value(&mut self, value: &V) -> bool

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

where I: IntoIterator<Item = K>,

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

where I: IntoIterator<Item = V>,

Trait Implementations

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

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

type Item = (K, V)

The type of the elements being iterated over.

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

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> StorageMapper<SA> for BiDiMapper<SA, K, V, CurrentStorage>

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

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 BiDiMapper<SA, K, V, ManagedAddress<SA>>

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

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 BiDiMapper<SA, K, V, CurrentStorage>

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

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 BiDiMapper<SA, K, V, CurrentStorage>

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

type Unmanaged = BiDiMapper<SA, K, V>

fn type_name() -> TypeName

fn type_name_rust() -> TypeName

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

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

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

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

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