Struct UniqueIdMapper 

pub struct UniqueIdMapper<SA, A = CurrentStorage>
where
    SA: StorageMapperApi,
    A: StorageAddress<SA>,
{ /* private fields */ }

A space-optimized storage mapper for managing ID permutations with minimal storage overhead.

Storage Layout

The UniqueIdMapper is optimized for scenarios where most IDs map to themselves (identity mapping). It uses a VecMapper internally but only stores non-identity mappings:

• base_key + ".len" → number of slots in the mapper
• base_key + ".item" + index → stored value only if value != index (stores 0 otherwise)

Key Optimization: When Mapper[i] == i (identity mapping), it stores 0 instead of i, significantly reducing storage costs when most IDs remain in their original positions.

Important: Indexes are 1-based (range: 1..=len()), consistent with VecMapper conventions.

Main Operations

• Initialize: set_initial_len(n) - Sets the mapper size (can only be called once).
• Read: get(index) - Returns the ID at the given index. O(1) with one storage read.
• Write: set(index, id) - Assigns an ID to an index. O(1) with one storage write.
• Remove: swap_remove(index) - Removes an index by swapping with the last element. O(1).
• Iteration: iter() - Iterates over all ID values in index order.

Trade-offs

• Pros: Extremely space-efficient for permutation tracking; zero storage cost for identity mappings.
• Cons: Limited to ID permutations (1 to N); length must be set upfront and cannot be extended.

Use Cases

• NFT position tracking where most NFTs remain in their original slots
• Shuffle/permutation algorithms where most elements stay in place
• ID reassignment systems with minimal changes

Example

// Initialize with 5 slots (IDs 1-5)
mapper.set_initial_len(5);

// Initially, all IDs map to themselves: [1, 2, 3, 4, 5]
assert_eq!(mapper.get(1), 1);
assert_eq!(mapper.get(3), 3);

// Swap positions 2 and 4
mapper.set(2, 4);
mapper.set(4, 2);

// Now the mapping is: [1, 4, 3, 2, 5]
assert_eq!(mapper.get(2), 4);
assert_eq!(mapper.get(4), 2);

// Remove index 3 (swaps with last)
let removed = mapper.swap_remove(3);
assert_eq!(removed, 3);
assert_eq!(mapper.len(), 4);

Implementations

impl<SA, A> UniqueIdMapper<SA, A>

where SA: StorageMapperApi, A: StorageAddress<SA>,

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn get(&self, index: usize) -> UniqueId

Gets the value for the given index. If the entry is empty, index is returned.

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

Provides a forward iterator.

impl<SA> UniqueIdMapper<SA, CurrentStorage>

where SA: StorageMapperApi,

pub fn set_initial_len(&mut self, len: usize)

Initializes the mapper’s length. This may not be set again afterwards.

pub fn swap_remove(&mut self, index: usize) -> UniqueId

Gets the value from the index and removes it. The value is replaced by the last item, and length is decremented.

pub fn set(&mut self, index: usize, id: UniqueId)

Sets the value at the given index. If index == id, then the entry is cleared.

Trait Implementations

impl<'a, SA, A> IntoIterator for &'a UniqueIdMapper<SA, A>

where SA: StorageMapperApi, A: StorageAddress<SA>,

type Item = usize

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<SA> StorageMapper<SA> for UniqueIdMapper<SA, CurrentStorage>

where SA: StorageMapperApi,

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

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

impl<SA> StorageMapperFromAddress<SA> for UniqueIdMapper<SA, ManagedAddress<SA>>

where SA: StorageMapperApi,

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> TopEncodeMulti for UniqueIdMapper<SA, CurrentStorage>

where SA: StorageMapperApi,

Behaves like a MultiResultVec 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> TypeAbi for UniqueIdMapper<SA, CurrentStorage>

where SA: StorageMapperApi,

Behaves like a MultiResultVec when an endpoint result.

type Unmanaged = UniqueIdMapper<SA>

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> TypeAbiFrom<UniqueIdMapper<SA>> for MultiValueEncoded<SA, usize>

where SA: StorageMapperApi,

impl<SA> TypeAbiFrom<UniqueIdMapper<SA>> for UniqueIdMapper<SA, CurrentStorage>

where SA: StorageMapperApi,