Type 4 – Arrays¶
CBOR arrays, just like byte strings and strings, can be encoded either as definite, or as indefinite.
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) |
|
Examples¶
0x9f Start indefinite array
0x01 Unsigned integer 1
0xff "Break" control token
0x9f Start array, 1B length follows
0x20 Unsigned integer 32
... 32 items follow
Streaming indefinite arrays¶
Please refer to Streaming & indefinite items.
Getting metadata¶
-
size_t
cbor_array_size
(const cbor_item_t *item)¶ Get the number of members.
- Return
The number of members
- Parameters
item[borrow]
: An array
-
size_t
cbor_array_allocated
(const cbor_item_t *item)¶ Get the size of the allocated storage.
- Return
The size of the allocated storage (number of items)
- Parameters
item[borrow]
: An array
-
bool
cbor_array_is_definite
(const cbor_item_t *item)¶ Is the array definite?
- Return
Is the array definite?
- Parameters
item[borrow]
: An array
-
bool
cbor_array_is_indefinite
(const cbor_item_t *item)¶ Is the array indefinite?
- Return
Is the array indefinite?
- Parameters
item[borrow]
: An array
Reading data¶
-
cbor_item_t **
cbor_array_handle
(const cbor_item_t *item)¶ Get the array contents.
The items may be reordered and modified as long as references remain consistent.
- Return
cbor_array_size items
- Parameters
item[borrow]
: An array
-
cbor_item_t *
cbor_array_get
(const cbor_item_t *item, size_t index)¶ Get item by index.
- Return
incref The item, or
NULL
in case of boundary violation- Parameters
item[borrow]
: An arrayindex
: The index
Creating new items¶
-
cbor_item_t *
cbor_new_definite_array
(size_t size)¶ Create new definite array.
- Return
new array or
NULL
upon malloc failure- Parameters
size
: Number of slots to preallocate
-
cbor_item_t *
cbor_new_indefinite_array
()¶ Create new indefinite array.
- Return
new array or
NULL
upon malloc failure
Modifying items¶
-
bool
cbor_array_push
(cbor_item_t *array, cbor_item_t *pushee)¶ Append to the end.
For indefinite items, storage may be realloacted. For definite items, only the preallocated capacity is available.
- Return
true on success, false on failure
- Parameters
array[borrow]
: An arraypushee[incref]
: The item to push
-
bool
cbor_array_replace
(cbor_item_t *item, size_t index, cbor_item_t *value)¶ Replace item at an index.
The item being replace will be cbor_decref ‘ed.
- Return
true on success, false on allocation failure.
- Parameters
item[borrow]
: An arrayvalue[incref]
: The item to assignindex
: The index, first item is 0.
-
bool
cbor_array_set
(cbor_item_t *item, size_t index, cbor_item_t *value)¶ Set item by index.
Creating arrays with holes is not possible
- Return
true on success, false on allocation failure.
- Parameters
item[borrow]
: An arrayvalue[incref]
: The item to assignindex
: The index, first item is 0.