blob: 17df5716ccc24098a2a6ee614e30d1ba92e83228 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
Type 2 – Byte strings
=============================
CBOR 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.
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 :type:`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 :doc:`/streaming`.
Getting metadata
~~~~~~~~~~~~~~~~~
.. doxygenfunction:: cbor_bytestring_length
.. doxygenfunction:: cbor_bytestring_is_definite
.. doxygenfunction:: cbor_bytestring_is_indefinite
.. doxygenfunction:: cbor_bytestring_chunk_count
Reading data
~~~~~~~~~~~~~
.. doxygenfunction:: cbor_bytestring_handle
.. doxygenfunction:: cbor_bytestring_chunks_handle
Creating new items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygenfunction:: cbor_new_definite_bytestring
.. doxygenfunction:: cbor_new_indefinite_bytestring
Building items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygenfunction:: cbor_build_bytestring
Manipulating existing items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. doxygenfunction:: cbor_bytestring_set_handle
.. doxygenfunction:: cbor_bytestring_add_chunk
|
