1Type 4 – Arrays
2=============================
3
4CBOR arrays, just like :doc:`byte strings <type_2>` and :doc:`strings <type_3>`, can be encoded either as definite, or as indefinite.
5Definite 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.
6
7Arrays 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.
8
9.. note:: Indefinite arrays can be conveniently used with streaming :doc:`decoding <streaming_decoding>` and :doc:`encoding <streaming_encoding>`.
10
11==================================  =====================================================================================
12Corresponding :type:`cbor_type`     ``CBOR_TYPE_ARRAY``
13Number of allocations (definite)    Two plus any manipulations with the data
14Number of allocations (indefinite)  Two plus logarithmically many
15                                    reallocations relative to additions
16Storage requirements (definite)     ``(sizeof(cbor_item_t) + 1) * size``
17Storage requirements (indefinite)   ``<= sizeof(cbor_item_t) + sizeof(cbor_item_t) * size * BUFFER_GROWTH``
18==================================  =====================================================================================
19
20
21Examples
22~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23
24::
25
26    0x9f        Start indefinite array
27        0x01        Unsigned integer 1
28        0xff        "Break" control token
29
30::
31
32    0x9f        Start array, 1B length follows
33    0x20        Unsigned integer 32
34        ...        32 items follow
35
36
37Getting metadata
38~~~~~~~~~~~~~~~~~
39
40.. doxygenfunction:: cbor_array_size
41.. doxygenfunction:: cbor_array_allocated
42.. doxygenfunction:: cbor_array_is_definite
43.. doxygenfunction:: cbor_array_is_indefinite
44
45Reading data
46~~~~~~~~~~~~~
47
48.. doxygenfunction:: cbor_array_handle
49.. doxygenfunction:: cbor_array_get
50
51Creating new items
52~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53
54.. doxygenfunction:: cbor_new_definite_array
55.. doxygenfunction:: cbor_new_indefinite_array
56
57
58Modifying items
59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60
61.. doxygenfunction:: cbor_array_push
62.. doxygenfunction:: cbor_array_replace
63.. doxygenfunction:: cbor_array_set
64