Type 4 – Arrays

CBOR arrays, just like byte strings and strings, can be encoded either as definite, or as indefinite.

Corresponding cbor_type CBOR_TYPE_ARRAY
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_item_t) + 1) * size
Storage requirements (indefinite) <= sizeof(cbor_item_t) + sizeof(cbor_item_t) * size * BUFFER_GROWTH

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 array

  • index -

    The index

Creating new items

cbor_item_t *cbor_new_definite_array(const 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 array

  • pushee[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 array

  • value[incref] -

    The item to assign

  • index -

    The index

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 array

  • value[incref] -

    The item to assign

  • index -

    The index