Type 5 – Maps

CBOR maps are the plain old associative maps similar JSON objects or Python dictionaries.

Definite maps have a fixed size which is stored in the header, whereas indefinite maps do not and are terminated by a special “break” byte instead.

Map are explicitly created or decoded as definite or indefinite and will be encoded using the corresponding wire representation, regardless of whether the actual size is known at the time of encoding.

Note

Indefinite maps can be conveniently used with streaming decoding and encoding. Keys and values can simply be output one by one, alternating keys and values.

Warning

Any CBOR data item is a legal map key (not just strings).

Corresponding cbor_type

CBOR_TYPE_MAP

Number of allocations (definite)

Two plus any manipulations with the data

Number of allocations (indefinite)

Two plus logarithmically many reallocations relative to additions

Storage requirements (definite)

sizeof(cbor_pair) * size + sizeof(cbor_item_t)

Storage requirements (indefinite)

<= sizeof(cbor_item_t) + sizeof(cbor_pair) * size * BUFFER_GROWTH

Examples

0xbf        Start indefinite map (represents {1: 2})
    0x01        Unsigned integer 1 (key)
    0x02        Unsigned integer 2 (value)
    0xff        "Break" control token
0xa0        Map of size 0

Getting metadata

size_t cbor_map_size(const cbor_item_t *item)

Get the number of pairs.

Return

The number of pairs

Parameters
  • item[borrow]: A map

size_t cbor_map_allocated(const cbor_item_t *item)

Get the size of the allocated storage.

Return

Allocated storage size (as the number of cbor_pair items)

Parameters
  • item[borrow]: A map

bool cbor_map_is_definite(const cbor_item_t *item)

Is this map definite?

Return

Is this map definite?

Parameters
  • item[borrow]: A map

bool cbor_map_is_indefinite(const cbor_item_t *item)

Is this map indefinite?

Return

Is this map indefinite?

Parameters
  • item[borrow]: A map

Reading data

struct cbor_pair *cbor_map_handle(const cbor_item_t *item)

Get the pairs storage.

Return

Array of cbor_map_size pairs. Manipulation is possible as long as references remain valid.

Parameters
  • item[borrow]: A map

Creating new items

cbor_item_t *cbor_new_definite_map(size_t size)

Create a new definite map.

Return

new definite map. NULL on malloc failure.

Parameters
  • size: The number of slots to preallocate

cbor_item_t *cbor_new_indefinite_map()

Create a new indefinite map.

Return

new definite map. NULL on malloc failure.

Parameters
  • size: The number of slots to preallocate

Modifying items

bool cbor_map_add(cbor_item_t *item, struct cbor_pair pair)

Add a pair to the map.

For definite maps, items can only be added to the preallocated space. For indefinite maps, the storage will be expanded as needed

Return

true on success, false if either reallocation failed or the preallcoated storage is full

Parameters
  • item[borrow]: A map

  • pair[incref]: The key-value pair to add (incref is member-wise)