Type 5 – Maps¶
CBOR maps are the plain old associate hash maps known from JSON and many other formats and languages, with one exception: any CBOR data item can be a key, not just strings. This is somewhat unusual and you, as an application developer, should keep that in mind.
Maps can be either definite or indefinite, in much the same way as Type 4 – Arrays.
Corresponding |
|
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) |
|
Storage requirements (indefinite) |
|
Streaming maps¶
Please refer to Streaming & indefinite items.
Getting metadata¶
-
size_t cbor_map_size(const cbor_item_t *item)¶
Get the number of pairs.
- param item[borrow]:
A map
- return:
The number of pairs
-
size_t cbor_map_allocated(const cbor_item_t *item)¶
Get the size of the allocated storage.
- param item[borrow]:
A map
- return:
Allocated storage size (as the number of cbor_pair items)
-
bool cbor_map_is_definite(const cbor_item_t *item)¶
Is this map definite?
- param item[borrow]:
A map
- return:
Is this map definite?
-
bool cbor_map_is_indefinite(const cbor_item_t *item)¶
Is this map indefinite?
- param item[borrow]:
A map
- return:
Is this map indefinite?
Reading data¶
-
struct cbor_pair *cbor_map_handle(const cbor_item_t *item)¶
Get the pairs storage.
- param item[borrow]:
A map
- return:
Array of cbor_map_size pairs. Manipulation is possible as long as references remain valid.
Creating new items¶
-
cbor_item_t *cbor_new_definite_map(size_t size)¶
Create a new definite map.
- param size:
The number of slots to preallocate
- return:
new definite map.
NULL
on malloc failure.
-
cbor_item_t *cbor_new_indefinite_map()¶
Create a new indefinite map.
- param size:
The number of slots to preallocate
- return:
new definite map.
NULL
on malloc failure.
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
- param item[borrow]:
A map
- param pair[incref]:
The key-value pair to add (incref is member-wise)
- return:
true
on success,false
if either reallocation failed or the preallcoated storage is full