type_2.rst

Type 2 – Byte strings

CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a 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 cbor_bytestring_is_definite and cbor_bytestring_is_indefinite respectively.

In 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

0xf5        Start indefinite byte string
0x41        Byte string (1B long)
    0x00
0x41        Byte string (1B long)
    0xff
0xff        "Break" control token

represents 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.

Corresponding cbor_type	CBOR_TYPE_BYTESTRING
Number of allocations (definite)	One plus any manipulations with the data
Number of allocations (indefinite)	One plus logarithmically many reallocations relative to chunk count
Storage requirements (definite)	sizeof(cbor_item_t) + length(handle)
Storage requirements (indefinite)	sizeof(cbor_item_t) * (1 + chunk_count) + chunks

Streaming indefinite byte strings

Please refer to /streaming.

Getting metadata

cbor_bytestring_length

cbor_bytestring_is_definite

cbor_bytestring_is_indefinite

cbor_bytestring_chunk_count

Reading data

cbor_bytestring_handle

cbor_bytestring_chunks_handle

Creating new items

cbor_new_definite_bytestring

cbor_new_indefinite_bytestring

Building items

cbor_build_bytestring

Manipulating existing items

cbor_bytestring_set_handle

cbor_bytestring_add_chunk