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 std::collections::HashMap;

use dcbor::prelude::*;

// 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 std::collections::{BTreeMap, HashMap};

use dcbor::prelude::*;

// 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() -> Map

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, Error>

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 duplicate 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<(), Error>

Formats the value using the given formatter.

impl Default for Map

fn default() -> Map

Returns the “default value” for a type.

impl EnvelopeEncodable for Map

fn into_envelope(self) -> Envelope

Converts this value into a Gordian Envelope.

fn to_envelope(&self) -> Envelope

where Self: Clone,

Converts a reference to this value into a Gordian Envelope.

impl From<&Map> for CBOR

fn from(value: &Map) -> CBOR

Converts to this type from the input type.

impl From<Map> for CBOR

fn from(value: Map) -> CBOR

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) -> Map

Converts to this type from the input type.

impl Hash for Map

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

where H: Hasher,

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: &Map) -> 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 TryFrom<Map> for Assertion

Attempts to convert a CBOR map to an assertion.

The map must have exactly one entry, where the key represents the predicate and the value represents the object. This is used in the deserialization process.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(map: Map) -> Result<Self>

Performs the conversion.

impl Eq for Map