Struct Map

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

Map is a ordered key-value dictionary.

The map is ordered by its keys. Iterating a map is stable and always returns the keys and values in order of the keys.

The map is stored in the Host and available to the Guest through the functions defined on Map. Values stored in the Map are transmitted to the Host as Vals, and when retrieved from the Map are transmitted back and converted from Val back into their type.

The pairs of keys and values in a Map are not guaranteed to be of type K/V and conversion will fail if they are not. Most functions on Map return a Result due to this.

There are some cases where this lack of guarantee is important:

• When storing a Map that has been provided externally as a contract function argument, be aware there is no guarantee that all pairs in the Map will be of type K and V. It may be necessary to validate all pairs, either before storing, or when loading with try_ variation functions.

• When accessing and iterating over a Map that has been provided externally as a contract function input, and the contract needs to be resilient to failure, use the try_ variation functions.

Maps have at most one entry per key. Setting a value for a key in the map that already has a value for that key replaces the value.

Map values can be stored as Storage, or in other types like Vec, Map, etc.

Examples

Maps can be created and iterated.

use soroban_sdk::{Env, Map, map};

let env = Env::default();
let map = map![&env, (2, 20), (1, 10)];
assert_eq!(map.len(), 2);
assert_eq!(map.iter().next(), Some((1, 10)));

Maps are ordered and so maps created with elements in different order will be equal.

use soroban_sdk::{Env, Map, map};

let env = Env::default();
assert_eq!(
    map![&env, (1, 10), (2, 20)],
    map![&env, (2, 20), (1, 10)],
)

Implementations

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

pub fn env(&self) -> &Env

pub fn as_val(&self) -> &Val

pub fn to_val(&self) -> Val

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

pub fn new(env: &Env) -> Map<K, V>

Create an empty Map.

pub fn from_array<const N: usize>(env: &Env, items: [(K, V); N]) -> Map<K, V>

Create a Map from the key-value pairs in the array.

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

Returns true if a key-value pair exists in the map with the given key.

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

Returns the value corresponding to the key or None if the map does not contain a value with the specified key.

Panics

If the value corresponding to the key cannot be converted to type V.

pub fn try_get(&self, k: K) -> Result<Option<V>, V::Error>

Returns the value corresponding to the key or None if the map does not contain a value with the specified key.

Errors

If the value corresponding to the key cannot be converted to type V.

pub fn get_unchecked(&self, k: K) -> V

Returns the value corresponding to the key.

Panics

If the map does not contain a value with the specified key.

If the value corresponding to the key cannot be converted to type V.

pub fn try_get_unchecked(&self, k: K) -> Result<V, V::Error>

Returns the value corresponding to the key.

Errors

If the value corresponding to the key cannot be converted to type V.

Panics

If the map does not contain a value with the specified key.

pub fn set(&mut self, k: K, v: V)

Set the value for the specified key.

If the map contains a value corresponding to the key, the value is replaced with the given value.

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

Remove the value corresponding to the key.

Returns None if the map does not contain a value with the specified key.

pub fn remove_unchecked(&mut self, k: K)

Remove the value corresponding to the key.

Panics

If the map does not contain a value with the specified key.

pub fn keys(&self) -> Vec<K>

Returns a Vec of all keys in the map.

pub fn values(&self) -> Vec<V>

Returns a Vec of all values in the map.

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

pub fn is_empty(&self) -> bool

Returns true if the map is empty and contains no key-values.

pub fn len(&self) -> u32

Returns the number of key-value pairs in the map.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

pub fn iter(&self) -> UnwrappedIter<MapTryIter<K, V>, (K, V), ConversionError>

where K: Clone, V: Clone,

pub fn try_iter(&self) -> MapTryIter<K, V>

where K: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone, V: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,

pub fn into_try_iter(self) -> MapTryIter<K, V>

where K: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone, V: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,

Trait Implementations

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

fn clone(&self) -> Map<K, V>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val> + Debug + Clone, K::Error: Debug, V: IntoVal<Env, Val> + TryFromVal<Env, Val> + Debug + Clone, V::Error: Debug,

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

Formats the value using the given formatter.

impl<K, V> From<&Map<K, V>> for ScVal

fn from(v: &Map<K, V>) -> Self

Converts to this type from the input type.

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

fn from(v: Map<K, V>) -> Self

Converts to this type from the input type.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

fn from(m: Map<K, V>) -> Self

Converts to this type from the input type.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = UnwrappedIter<MapTryIter<K, V>, (K, V), ConversionError>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

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

where K: SorobanArbitrary, V: SorobanArbitrary,

Available on crate feature testutils only.

type Prototype = ArbitraryMap<<K as SorobanArbitrary>::Prototype, <V as SorobanArbitrary>::Prototype>

A type that implements Arbitrary and can be converted to this SorobanArbitrary type.

impl<K, V> TryFromVal<Env, Map<K, V>> for ScVal

type Error = ConversionError

fn try_from_val(_e: &Env, v: &Map<K, V>) -> Result<Self, ConversionError>

impl<K, V> TryFromVal<Env, Map<K, V>> for Val

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

type Error = Infallible

fn try_from_val(_env: &Env, v: &Map<K, V>) -> Result<Self, Self::Error>

impl<K, V> TryFromVal<Env, MapObject> for Map<K, V>

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

type Error = Infallible

fn try_from_val(env: &Env, obj: &MapObject) -> Result<Self, Self::Error>

impl<K, V> TryFromVal<Env, ScVal> for Map<K, V>

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

type Error = ConversionError

fn try_from_val(env: &Env, val: &ScVal) -> Result<Self, Self::Error>

impl<K, V> TryFromVal<Env, Val> for Map<K, V>

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,

type Error = ConversionError

fn try_from_val(env: &Env, val: &Val) -> Result<Self, Self::Error>

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

where K: IntoVal<Env, Val> + TryFromVal<Env, Val>, V: IntoVal<Env, Val> + TryFromVal<Env, Val>,