Struct Map 

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

An ordered, deduplicated collection of key-value pairs.

Implementations

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

pub fn from_iter_dedup<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self

Creates a new Map from an iterator, removing duplicate keys.

Unlike FromIterator and From, this method tolerates duplicate keys by silently discarding them (keeping the first occurrence).

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

pub fn from_parts(keys: Set<K>, values: Vec<V>) -> Option<Self>

Creates a map from ordered keys and corresponding values, reusing both allocations.

Each value is paired with the key at the same index. Returns None if the lengths differ.

Examples

use commonware_utils::ordered::{Map, Set};

let keys = Set::try_from([3, 1, 2]).unwrap();
let map = Map::from_parts(keys, vec!["one", "two", "three"]).unwrap();
assert_eq!(map.get_value(&2), Some(&"two"));

pub const fn len(&self) -> usize

Returns the number of entries in the map.

pub const fn is_empty(&self) -> bool

Returns true if the map is empty.

pub fn get(&self, index: usize) -> Option<&K>

Returns a key by index, if it exists.

pub fn position(&self, key: &K) -> Option<usize>

where K: Ord,

Returns the position of the provided key, if it exists.

pub const fn keys(&self) -> &Set<K>

Returns the ordered keys as a Set reference.

pub fn into_keys(self) -> Set<K>

Consumes the map and returns the ordered keys.

pub fn value(&self, index: usize) -> Option<&V>

Returns the associated value at index, if it exists.

pub fn get_value(&self, key: &K) -> Option<&V>

where K: Ord,

Returns the associated value for key, if it exists.

pub fn get_value_mut(&mut self, key: &K) -> Option<&mut V>

where K: Ord,

Returns a mutable reference to the associated value for key, if it exists.

pub fn values(&self) -> &[V]

Returns the associated values.

pub fn values_mut(&mut self) -> &mut [V]

Returns a mutable reference to the associated values

pub fn map_values<'a, U, F>(&'a self, f: F) -> Map<K, U>

where K: Clone, F: FnMut(&'a K, &'a V) -> U,

Maps each value in key order, cloning the keys without sorting or validating them.

The closure receives references to the key and value. The new values may borrow from this map.

Examples

use commonware_utils::ordered::Map;

let map = Map::try_from([(4, "four"), (1, "one")]).unwrap();
let lengths = map.map_values(|_, value| value.len());
assert_eq!(lengths.keys(), map.keys());
assert_eq!(lengths.values(), &[3, 4]);

pub fn try_map_values<'a, U, E, F>(&'a self, f: F) -> Result<Map<K, U>, E>

where K: Clone, F: FnMut(&'a K, &'a V) -> Result<U, E>,

Fallible version of Self::map_values.

Returns the first error without calling the closure for subsequent entries. Clones the keys only on success.

Examples

use commonware_utils::ordered::Map;

let map = Map::try_from([(2, "invalid"), (1, "10")]).unwrap();
let result = map.try_map_values(|_, value| value.parse::<u32>());
assert!(result.is_err());
assert_eq!(map.values(), &["10", "invalid"]);

pub fn map_values_into<U, F>(self, f: F) -> Map<K, U>

where F: FnMut(&K, V) -> U,

Consumes the map and maps each value in key order, reusing the key allocation.

The closure receives a reference to the key and the owned value. Keys are not cloned, sorted, or validated.

Examples

use commonware_utils::ordered::Map;

let map = Map::try_from([(2, String::from("two")), (1, String::from("one"))]).unwrap();
let bytes = map.map_values_into(|_, value| value.into_bytes());
assert_eq!(bytes.keys().as_ref(), &[1, 2]);
assert_eq!(bytes.values(), &[b"one".to_vec(), b"two".to_vec()]);

pub fn try_map_values_into<U, E, F>(self, f: F) -> Result<Map<K, U>, E>

where F: FnMut(&K, V) -> Result<U, E>,

Fallible version of Self::map_values_into.

Returns the first error without calling the closure for subsequent entries.

Examples

use commonware_utils::ordered::Map;

let map = Map::try_from([(2, String::from("20")), (1, String::from("10"))]).unwrap();
let parsed = map.try_map_values_into(|_, value| value.parse::<u32>()).unwrap();
assert_eq!(parsed.keys().as_ref(), &[1, 2]);
assert_eq!(parsed.values(), &[10, 20]);

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

Truncates the map to at most len entries.

pub fn iter_pairs( &self, ) -> impl ExactSizeIterator<Item = (&K, &V)> + DoubleEndedIterator

Returns a zipped iterator over keys and values.

pub fn iter_pairs_mut( &mut self, ) -> impl ExactSizeIterator<Item = (&K, &mut V)> + DoubleEndedIterator

Returns a zipped iterator over keys and mutable references to values.

This is provided because the borrow checker does not let you combine the other functions yourself.

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

Returns an iterator over the ordered keys.

impl<K: MaxEncodeSize, V> Map<K, V>

pub fn max_encode_size(len: usize, value: usize) -> usize

Returns an upper bound on the encoded size of a map of at most len entries whose values encode to at most value bytes each.

Methods from Deref<Target = Set<K>>

pub fn len(&self) -> usize

Returns the size of the ordered collection.

pub fn is_empty(&self) -> bool

Returns true if the collection is empty.

pub fn get(&self, index: usize) -> Option<&T>

Returns an item by index, if it exists.

pub fn position(&self, item: &T) -> Option<usize>

where T: Ord,

Returns the position of a given item in the collection, if it exists.

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

Returns an iterator over the items in the collection.

Trait Implementations

impl<K, V> AsRef<Set<K>> for Map<K, V>

fn as_ref(&self) -> &Set<K>

Converts this type into a shared reference of the (usually inferred) input type.

impl<K, V> AsRef<[K]> for Map<K, V>

fn as_ref(&self) -> &[K]

Converts this type into a shared reference of the (usually inferred) input type.

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

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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> Default for Map<K, V>

fn default() -> Self

Returns the “default value” for a type.

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

type Target = Set<K>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

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

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

Formats the value using the given formatter.

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

fn encode_size(&self) -> usize

Returns the encoded size of this value (in bytes).

fn encode_inline_size(&self) -> usize

Returns the encoded size excluding bytes passed to BufsMut::push during Write::write_bufs. Used to size the fixed working buffer for inline writes, so it must not be less than the bytes written inline. Override alongside Write::write_bufs for types where large byte fields go via push, or the working buffer will over-allocate.

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

impl<K, V> From<Map<K, V>> for Vec<(K, V)>

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

Converts to this type from the input type.

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

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = MapIntoIter<K, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V> IntoIterator for &'a Map<K, V>

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = Zip<Iter<'a, K>, Iter<'a, V>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

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

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

Equality operator ==.

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

Inequality operator !=.

impl<K: Read + Ord, V: Read> Read for Map<K, V>

type Cfg = (RangeCfg<usize>, <K as Read>::Cfg, <V as Read>::Cfg)

The Cfg type parameter allows passing configuration during the read process. This is crucial for safely decoding untrusted data, for example, by providing size limits for collections or strings.

fn read_cfg(buf: &mut impl Buf, cfg: &Self::Cfg) -> Result<Self, Error>

Reads a value from the buffer using the provided configuration cfg.

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

impl<K: Ord + Clone, V: Clone, const N: usize> TryFrom<&[(K, V); N]> for Map<K, V>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(items: &[(K, V); N]) -> Result<Self, Self::Error>

Performs the conversion.

impl<K: Ord + Clone, V: Clone> TryFrom<&[(K, V)]> for Map<K, V>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(items: &[(K, V)]) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V: Eq + Hash> TryFrom<Map<K, V>> for BiMap<K, V>

type Error = Error

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<K: Ord, V> TryFrom<Vec<(K, V)>> for Map<K, V>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(items: Vec<(K, V)>) -> Result<Self, Self::Error>

Performs the conversion.

impl<K: Ord, V, const N: usize> TryFrom<[(K, V); N]> for Map<K, V>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(items: [(K, V); N]) -> Result<Self, Self::Error>

Performs the conversion.

impl<K: Ord, V> TryFromIterator<(K, V)> for Map<K, V>

fn try_from_iter<I: IntoIterator<Item = (K, V)>>( iter: I, ) -> Result<Self, Self::Error>

Attempts to create a Map from an iterator.

Returns an error if there are duplicate keys.

type Error = Error

The error type returned when construction fails.

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

fn write(&self, buf: &mut impl BufMut)

Writes the binary representation of self to the provided buffer buf.

fn write_bufs(&self, buf: &mut impl BufsMut)

Writes to a BufsMut, allowing existing byte chunks to be appended via BufsMut::push instead of written inline. Must encode to the same format as Write::write. Defaults to Write::write.