1Type 2 – Byte strings
2=============================
3
4CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a :doc:`tag <type_6>`). Byte string's length may or may not be known during encoding. These two kinds of byte strings can be distinguished using :func:`cbor_bytestring_is_definite` and :func:`cbor_bytestring_is_indefinite` respectively.
5
6In case a byte string is indefinite, it is encoded as a series of definite byte strings. These are called "chunks". For example, the encoded item
7
8::
9
10    0xf5	    Start indefinite byte string
11	0x41	    Byte string (1B long)
12	    0x00
13	0x41	    Byte string (1B long)
14	    0xff
15	0xff	    "Break" control token
16
17represents two bytes, ``0x00`` and ``0xff``. This on one hand enables streaming messages even before they are fully generated, but on the other hand it adds more complexity to the client code.
18
19
20==================================  ======================================================
21Corresponding :type:`cbor_type`     ``CBOR_TYPE_BYTESTRING``
22Number of allocations (definite)    One plus any manipulations with the data
23Number of allocations (indefinite)  One plus logarithmically many
24                                    reallocations relative  to chunk count
25Storage requirements (definite)     ``sizeof(cbor_item_t) + length(handle)``
26Storage requirements (indefinite)   ``sizeof(cbor_item_t) * (1 + chunk_count) + chunks``
27==================================  ======================================================
28
29
30Getting metadata
31~~~~~~~~~~~~~~~~~
32
33.. doxygenfunction:: cbor_bytestring_length
34.. doxygenfunction:: cbor_bytestring_is_definite
35.. doxygenfunction:: cbor_bytestring_is_indefinite
36.. doxygenfunction:: cbor_bytestring_chunk_count
37
38Reading data
39~~~~~~~~~~~~~
40
41.. doxygenfunction:: cbor_bytestring_handle
42.. doxygenfunction:: cbor_bytestring_chunks_handle
43
44Creating new items
45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
47.. doxygenfunction:: cbor_new_definite_bytestring
48.. doxygenfunction:: cbor_new_indefinite_bytestring
49
50
51Building items
52~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53.. doxygenfunction:: cbor_build_bytestring
54
55
56Manipulating existing items
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59.. doxygenfunction:: cbor_bytestring_set_handle
60.. doxygenfunction:: cbor_bytestring_add_chunk
61
62