Struct Map

pub struct Map(/* private fields */);

Map Support in dCBOR

A deterministic CBOR map implementation that ensures maps with the same content always produce identical binary encodings, regardless of insertion order.

Deterministic Map Representation

The Map type follows strict deterministic encoding rules as specified by dCBOR:

• Map keys are always sorted in lexicographic order of their encoded CBOR bytes
• Duplicate keys are not allowed (enforced by the implementation)
• Keys and values can be any type that implements Into<CBOR>
• Numeric reduction is applied (e.g., 3.0 is stored as integer 3)

This deterministic encoding ensures that equivalent maps always produce identical byte representations, which is crucial for applications that rely on consistent hashing, digital signatures, or other cryptographic operations.

Features

The Map type provides:

• Built-in conversions from standard Rust collections like HashMap and BTreeMap
• Type-safe conversions when extracting values with get<K, V>() and extract<K, V>()
• Automatic deterministic ordering of keys
• Prevention of duplicate keys
• Support for heterogeneous key and value types

Examples

Creating and using maps

use dcbor::prelude::*;
use std::collections::HashMap;

// Create a new Map directly
let mut map = Map::new();
map.insert(1, "one");                // Integer key
map.insert("two", 2);                // String key
map.insert([1, 2, 3], "array key");  // Array key
map.insert(3.0, "numeric reduction"); // Float key (stored as integer 3)

// Check the map size
assert_eq!(map.len(), 4);

// Create a CBOR value from the map
let cbor_map: CBOR = map.into();

// Round-trip through binary encoding
let encoded = cbor_map.to_cbor_data();
let decoded = CBOR::try_from_data(&encoded).unwrap();

// View the diagnostic representation
assert!(decoded.diagnostic_flat().contains(r#""two": 2"#));

Converting from standard Rust collections

use dcbor::prelude::*;
use std::collections::{HashMap, BTreeMap};

// Convert HashMap to CBOR Map
let mut hash_map = HashMap::new();
hash_map.insert("a", 1);
hash_map.insert("b", 2);
let cbor_from_hashmap: CBOR = hash_map.into();

// Convert BTreeMap to CBOR Map
let mut btree_map = BTreeMap::new();
btree_map.insert("x", "value1");
btree_map.insert("y", "value2");
let cbor_from_btree: CBOR = btree_map.into();

Type-safe extraction of values

use dcbor::prelude::*;

// Create a map with various types
let mut typed_map = Map::new();
typed_map.insert("number", 42);
typed_map.insert("text", "hello");
typed_map.insert("array", vec![1, 2, 3]);

// Type-safe extraction
let number: i32 = typed_map.extract("number").unwrap();
let text: String = typed_map.extract("text").unwrap();
let array: Vec<i32> = typed_map.extract("array").unwrap();

assert_eq!(number, 42);
assert_eq!(text, "hello");
assert_eq!(array, vec![1, 2, 3]);

// Using get() for optional extraction
let present: Option<i32> = typed_map.get("number");
let absent: Option<i32> = typed_map.get("missing");

assert_eq!(present, Some(42));
assert_eq!(absent, None);

Implementation Details

The Map implementation:

• Uses a BTreeMap internally to maintain the sorted order of keys
• Encodes keys with their CBOR representation for lexicographic sorting
• Applies all dCBOR deterministic encoding rules automatically

Implementations

impl Map

pub fn new() -> Self

Makes a new, empty CBOR Map.

pub fn len(&self) -> usize

Returns the number of entries in the map.

pub fn is_empty(&self) -> bool

Checks if the map is empty.

pub fn iter(&self) -> MapIter<'_>

Gets an iterator over the entries of the CBOR map, sorted by key.

Key sorting order is lexicographic by the key’s binary-encoded CBOR.

pub fn insert(&mut self, key: impl Into<CBOR>, value: impl Into<CBOR>)

Inserts a key-value pair into the map.

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

where K: Into<CBOR>, V: TryFrom<CBOR>,

Get a value from the map, given a key.

Returns Some if the key is present in the map, None otherwise.

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

where K: Into<CBOR>,

Tests if the map contains a key.

pub fn extract<K, V>(&self, key: K) -> Result<V>

where K: Into<CBOR>, V: TryFrom<CBOR>,

Get a value from the map, given a key.

Returns Ok if the key is present in the map, Err otherwise.

impl Map

pub fn cbor_data(&self) -> Vec<u8>

Trait Implementations

impl Clone for Map

fn clone(&self) -> Map

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Map

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

Formats the value using the given formatter.

impl Default for Map

fn default() -> Self

Returns the “default value” for a type.

impl From<Map> for CBOR

fn from(value: Map) -> Self

Converts to this type from the input type.

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

where T: IntoIterator<Item = (K, V)>, K: Into<CBOR>, V: Into<CBOR>,

Convert a container to a CBOR Map where the container’s items are pairs of CBOREncodable values.

fn from(container: T) -> Self

Converts to this type from the input type.

impl Hash for Map

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 PartialEq for Map

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 Eq for Map