Struct Map 

pub struct Map<K, V> { /* private fields */ }

A persistent map from keys of type K to storage values of type V.

Key identity is the XDR encoding

An entry’s storage slot is addressed by sha256(XDR-encode(key)) — the key’s WriteXDR encoding is its identity. Two keys address the same entry if and only if they encode to the same bytes; the in-memory K value (and any PartialEq/Eq/Hash it has) is never consulted by the storage layer. In particular, no Map operation consults K’s PartialEq/Eq: even the duplicate-key check in at_disjoint_mut compares the derived storage keypaths, not the keys themselves.

Key encoding invariant

A key’s storage slot is sha256 of its framed WriteXDR encoding, so the encoding is the key’s identity. Key types MUST encode injectively: distinct keys must produce distinct bytes. All SDK-provided and #[derive(XDR)] types satisfy this. A hand-written, non-canonical WriteXDR where a != b but encode(a) == encode(b) will silently alias the two keys onto one slot.

Implementations

impl<K, V> Map<K, V>

pub fn keypath(&self) -> &Keypath

pub fn at(&self, entry_key: &K) -> SlotRef<'_, Self, V>

where K: WriteXDR, V: StorageType,

pub fn at_mut(&mut self, entry_key: &K) -> SlotMut<'_, Self, V>

where K: WriteXDR, V: StorageType,

pub fn at_mut_exclusive(&mut self, entry_key: &K) -> SlotMut<'_, Self, V>

where K: WriteXDR, V: StorageType,

Like at_mut, but every successful write through the returned handle is followed by a request for an exclusive lock on the entry, so concurrent writers to it conflict. The lock lasts for the rest of the transaction: later writes through ordinary handles keep it, and only clear_flags removes it. Building, reading or dropping the handle requests nothing.

pub fn delete_at(&mut self, entry_key: &K)

where K: WriteXDR, V: StorageType + Deletable,

pub fn at_disjoint_mut<const N: usize>( &mut self, keys: [&K; N], ) -> DisjointMut<'_, Self, V, N>

where K: WriteXDR, V: StorageType,

Mutably borrow N elements at once. Panics if any keys are equal.

Returns a DisjointMut guard that borrows the map exclusively and provides DerefMut access to the [V; N] array.

Mirrors HashMap::get_disjoint_mut.

The duplicate-key check compares the derived storage keypaths — the actual slot identity — so it does not consult K’s PartialEq and is exact regardless of how (or whether) K implements it.

pub unsafe fn at_disjoint_unchecked_mut<const N: usize>( &mut self, keys: [&K; N], ) -> DisjointMut<'_, Self, V, N>

where K: WriteXDR, V: StorageType,

Mutably borrow N elements at once without checking for duplicates.

Safety

The caller must ensure all keys are disjoint. Passing duplicate keys creates aliased handles to the same storage slot across the syscall boundary, which may silently corrupt data.

Trait Implementations

impl<K: Debug, V: Debug> Debug for Map<K, V>

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

Formats the value using the given formatter.

impl<K, V> From<Keypath> for Map<K, V>

fn from(keypath: Keypath) -> Self

Converts to this type from the input type.

impl<K, V> StorageType for Map<K, V>