Struct LinkedListMapper 

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

A storage mapper implementing a doubly-linked list with efficient insertion and removal at any position.

Storage Layout

The LinkedListMapper stores metadata and individual nodes separately:

1. Metadata:

   • base_key + ".info" → LinkedListInfo struct containing:
     • len: number of elements
     • front: node ID of the first element
     • back: node ID of the last element
     • new: counter for generating unique node IDs

2. Nodes:

   • base_key + ".node" + node_id → LinkedListNode<T> containing:
     • value: the stored item
     • node_id: this node’s unique ID
     • next_id: ID of the next node (0 if none)
     • prev_id: ID of the previous node (0 if none)

Main Operations

• Append: push_back(item) - Adds to the end. O(1) with constant storage writes.
• Prepend: push_front(item) - Adds to the beginning. O(1) with constant storage writes.
• Insert: push_after(node, item) / push_before(node, item) - Inserts at specific position. O(1).
• Remove: pop_front() / pop_back() / remove_node(node) - Removes from any position. O(1).
• Access: front() / back() / get_node_by_id(id) - Retrieves nodes. O(1).
• Iteration: iter() - Traverses from front to back; iter_from_node_id(id) - starts from specific node.

Trade-offs

• Pros: O(1) insertion/removal at any position; maintains insertion order; efficient for queue/deque patterns.
• Cons: No random access by index; higher storage overhead per element (stores prev/next pointers); iteration requires following links; removed nodes leave “gaps” in node ID space.

Use Cases

• Task queues where items can be added/removed at any position
• Priority management where items move positions frequently
• Scenarios requiring both ordered iteration and arbitrary insertion/removal

Example

// Add elements
let node1 = mapper.push_back(100);
let node2 = mapper.push_back(200);
let node3 = mapper.push_back(300);

assert_eq!(mapper.len(), 3);
assert_eq!(mapper.front().unwrap().into_value(), 100);
assert_eq!(mapper.back().unwrap().into_value(), 300);

// Insert in the middle
let mut node2_mut = node2.clone();
mapper.push_after(&mut node2_mut, 250);
assert_eq!(mapper.len(), 4);

// Remove from front
let removed = mapper.pop_front().unwrap();
assert_eq!(removed.into_value(), 100);
assert_eq!(mapper.len(), 3);

// Remove specific node
mapper.remove_node(&node2);
assert_eq!(mapper.len(), 2);

// Iterate through remaining elements
for node in mapper.iter() {
    let value = node.into_value();
    // Process value
}

Implementations

impl<SA, T, A> LinkedListMapper<SA, T, A>

where SA: StorageMapperApi, A: StorageAddress<SA>, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

pub fn is_empty(&self) -> bool

pub fn len(&self) -> usize

pub fn front(&self) -> Option<LinkedListNode<T>>

pub fn back(&self) -> Option<LinkedListNode<T>>

pub fn get_node_by_id(&self, node_id: u32) -> Option<LinkedListNode<T>>

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

pub fn iter_from_node_id(&self, node_id: u32) -> Iter<'_, SA, T, A>

pub fn check_internal_consistency(&self) -> bool

impl<SA, T> LinkedListMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

pub fn pop_back(&mut self) -> Option<LinkedListNode<T>>

pub fn pop_front(&mut self) -> Option<LinkedListNode<T>>

pub fn push_after( &mut self, node: &mut LinkedListNode<T>, element: T, ) -> Option<LinkedListNode<T>>

pub fn push_before( &mut self, node: &mut LinkedListNode<T>, element: T, ) -> Option<LinkedListNode<T>>

pub fn push_after_node_id( &mut self, node_id: u32, element: T, ) -> Option<LinkedListNode<T>>

pub fn push_before_node_id( &mut self, node_id: u32, element: T, ) -> Option<LinkedListNode<T>>

pub fn push_back(&mut self, element: T) -> LinkedListNode<T>

pub fn push_front(&mut self, element: T) -> LinkedListNode<T>

pub fn set_node_value(&mut self, node: LinkedListNode<T>, new_value: T)

pub fn set_node_value_by_id(&mut self, node_id: u32, new_value: T)

pub fn remove_node(&mut self, node: &LinkedListNode<T>)

pub fn remove_node_by_id(&mut self, node_id: u32) -> Option<LinkedListNode<T>>

Trait Implementations

impl<'a, SA, T, A> IntoIterator for &'a LinkedListMapper<SA, T, A>

where SA: StorageMapperApi, A: StorageAddress<SA>, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone + 'static,

type Item = LinkedListNode<T>

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<SA, T> StorageClearable for LinkedListMapper<SA, T>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

fn clear(&mut self)

Clears all the entries owned by the storage.

impl<SA, T> StorageMapper<SA> for LinkedListMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

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

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

impl<SA, T> StorageMapperFromAddress<SA> for LinkedListMapper<SA, T, ManagedAddress<SA>>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

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, T> TopEncodeMulti for LinkedListMapper<SA, T>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

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, T> TypeAbi for LinkedListMapper<SA, T>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone + TypeAbi,

type Unmanaged = LinkedListMapper<SA, T>

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, T> TypeAbiFrom<LinkedListMapper<SA, T>> for LinkedListMapper<SA, T>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone,

impl<SA, T, U> TypeAbiFrom<LinkedListMapper<SA, T>> for MultiValueEncoded<SA, U>

where SA: StorageMapperApi, T: TopEncode + TopDecode + NestedEncode + NestedDecode + Clone, U: TypeAbiFrom<T>,