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 30Streaming indefinite byte strings 31~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32 33Please refer to :doc:`/streaming`. 34 35Getting metadata 36~~~~~~~~~~~~~~~~~ 37 38.. doxygenfunction:: cbor_bytestring_length 39.. doxygenfunction:: cbor_bytestring_is_definite 40.. doxygenfunction:: cbor_bytestring_is_indefinite 41.. doxygenfunction:: cbor_bytestring_chunk_count 42 43Reading data 44~~~~~~~~~~~~~ 45 46.. doxygenfunction:: cbor_bytestring_handle 47.. doxygenfunction:: cbor_bytestring_chunks_handle 48 49Creating new items 50~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 51 52.. doxygenfunction:: cbor_new_definite_bytestring 53.. doxygenfunction:: cbor_new_indefinite_bytestring 54 55 56Building items 57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58.. doxygenfunction:: cbor_build_bytestring 59 60 61Manipulating existing items 62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 63 64.. doxygenfunction:: cbor_bytestring_set_handle 65.. doxygenfunction:: cbor_bytestring_add_chunk 66 67