Struct soroban_sdk::Map

#[repr(transparent)]
pub struct Map<K, V>(_, _, _);

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 RawVals, and when retrieved from the Map are transmitted back and converted from RawVal back into their type.

The 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.

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 Data, 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(Ok((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>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

pub fn env(&self) -> &Env

pub fn as_raw(&self) -> &RawVal

pub fn to_raw(&self) -> RawVal

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

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

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

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

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

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

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

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

pub fn is_empty(&self) -> bool

pub fn len(&self) -> u32

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

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

pub fn iter(&self) -> MapIter<K, V>where
    K: Clone,
    V: Clone,

pub fn iter_unchecked(
    &self
) -> UncheckedIter<MapIter<K, V>, (K, V), ConversionError>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal> + Clone,
    K::Error: Debug,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal> + Clone,
    V::Error: Debug,

pub fn into_iter_unchecked(
    self
) -> UncheckedIter<MapIter<K, V>, (K, V), ConversionError>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal> + Clone,
    K::Error: Debug,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal> + Clone,
    V::Error: Debug,

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, RawVal> + TryFromVal<Env, RawVal> + Debug + Clone,
    K::Error: Debug,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal> + 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 EnvVal<Env, Object>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

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

Converts to this type from the input type.

impl<K, V> From<Map<K, V>> for RawValwhere
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

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, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Item = Result<(K, V), ConversionError>

The type of the elements being iterated over.

type IntoIter = MapIter<K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V> IntoVal<Env, RawVal> for &Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

fn into_val(self, _env: &Env) -> RawVal

fn into_env_val(self, env: &E) -> EnvVal<E, V>

impl<K, V> IntoVal<Env, RawVal> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

fn into_val(self, _env: &Env) -> RawVal

fn into_env_val(self, env: &E) -> EnvVal<E, V>

impl<K, V> Ord for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl<K, V> PartialEq<Map<K, V>> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<K, V> PartialOrd<Map<K, V>> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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

type Error = ConversionError

The type returned in the event of a conversion error.

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

Performs the conversion.

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

type Error = ConversionError

The type returned in the event of a conversion error.

fn try_from(v: Map<K, V>) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V> TryFromVal<Env, Object> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = ConversionError

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

impl<K, V> TryFromVal<Env, RawVal> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = <Map<K, V> as TryFromVal<Env, Object>>::Error

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

impl<K, V> TryFromVal<Env, ScVal> for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = ConversionError

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

impl<K, V> TryIntoVal<Env, Map<K, V>> for Objectwhere
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = ConversionError

fn try_into_val(self, env: &Env) -> Result<Map<K, V>, Self::Error>

fn try_into_env_val(self, env: &E) -> Result<EnvVal<E, V>, Self::Error>

impl<K, V> TryIntoVal<Env, Map<K, V>> for RawValwhere
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = ConversionError

fn try_into_val(self, env: &Env) -> Result<Map<K, V>, Self::Error>

fn try_into_env_val(self, env: &E) -> Result<EnvVal<E, V>, Self::Error>

impl<K, V> TryIntoVal<Env, Map<K, V>> for ScValwhere
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,

type Error = ConversionError

fn try_into_val(self, env: &Env) -> Result<Map<K, V>, Self::Error>

fn try_into_env_val(self, env: &E) -> Result<EnvVal<E, V>, Self::Error>

impl<K, V> Eq for Map<K, V>where
    K: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,
    V: IntoVal<Env, RawVal> + TryFromVal<Env, RawVal>,