Type 4 – Arrays¶
CBOR arrays, just like byte strings and strings, can be encoded either as definite, or as indefinite. Definite arrays have a fixed size which is stored in the header, whereas indefinite arrays do not and are terminated by a special “break” byte instead.
Arrays 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.
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
Getting metadata¶
-
size_t cbor_array_size(const cbor_item_t *item)¶
Get the number of members.
- param item
An array
- return
The number of members
-
size_t cbor_array_allocated(const cbor_item_t *item)¶
Get the size of the allocated storage.
- param item
An array
- return
The size of the allocated storage (number of items)
-
bool cbor_array_is_definite(const cbor_item_t *item)¶
Is the array definite?
- param item
An array
- return
Is the array definite?
-
bool cbor_array_is_indefinite(const cbor_item_t *item)¶
Is the array indefinite?
- param item
An array
- return
Is the array indefinite?
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.
- param item
An array item
- return
An array of cbor_item_t pointers of size cbor_array_size.
-
cbor_item_t *cbor_array_get(const cbor_item_t *item, size_t index)¶
Get item by index.
Increases the reference count of the underlying item. The returned reference must be released using cbor_decref.
- param item
An array
- param index
The index (zero-based)
- return
Reference to the item, or
NULL
in case of boundary violation.
Creating new items¶
-
cbor_item_t *cbor_new_definite_array(size_t size)¶
Create new definite array.
- param size
Number of slots to preallocate
- return
Reference to the new array item. The item’s reference count is initialized to one.
- return
NULL
if memory allocation fails
-
cbor_item_t *cbor_new_indefinite_array(void)¶
Create new indefinite array.
- return
Reference to the new array item. The item’s reference count is initialized to one.
- return
NULL
if memory allocation fails
Modifying items¶
-
bool cbor_array_push(cbor_item_t *array, cbor_item_t *pushee)¶
Append to the end.
For indefinite items, storage may be reallocated. For definite items, only the preallocated capacity is available.
- param array
An array
- param pushee
The item to push. Its reference count will be increased by one.
- return
true
on success,false
on failure
-
bool cbor_array_replace(cbor_item_t *item, size_t index, cbor_item_t *value)¶
Replace item at an index.
The reference to the item being replaced will be released using cbor_decref.
- param item
An array
- param value
The item to assign. Its reference count will be increased by one.
- param index
The index (zero-based)
- return
true on success, false on allocation failure.
-
bool cbor_array_set(cbor_item_t *item, size_t index, cbor_item_t *value)¶
Set item by index.
If the index is out of bounds, the array is not modified and false is returned. Creating arrays with holes is not possible.
- param item
An array
- param value
The item to assign
- param index
The index (zero-based)
- return
true
on success,false
on allocation failure.