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.

Note

Indefinite arrays can be conveniently used with streaming decoding and encoding.

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

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(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, 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 array

  • value[incref]: The item to assign

  • index: The index, first item is 0.