1Types 0 & 1 – Positive and negative integers
2===============================================
3
4*CBOR* has two types of integers – positive (which may be effectively regarded as unsigned), and negative. There are four possible widths for an integer – 1, 2, 4, or 8 bytes. These are represented by
5
6.. doxygenenum:: cbor_int_width
7
8
9Type 0 - positive integers
10--------------------------
11==================================  =========================================
12Corresponding :type:`cbor_type`     ``CBOR_TYPE_UINT``
13Number of allocations               One per lifetime
14Storage requirements                ``sizeof(cbor_item_t) + sizeof(uint*_t)``
15==================================  =========================================
16
17**Note:** once a positive integer has been created, its width *cannot* be changed.
18
19Type 1 - negative integers
20--------------------------
21==================================  =========================================
22Corresponding :type:`cbor_type`     ``CBOR_TYPE_NEGINT``
23Number of allocations               One per lifetime
24Storage requirements                ``sizeof(cbor_item_t) + sizeof(uint*_t)``
25==================================  =========================================
26
27**Note:** once a positive integer has been created, its width *cannot* be changed.
28
29Type 0 & 1
30-------------
31Due to their largely similar semantics, the following functions can be used for both Type 0 and Type 1 items. One can convert between them freely using `the conversion functions <#dealing-with-signedness>`_.
32
33Actual Type of the integer can be checked using :doc:`item types API <item_types>`.
34
35
36
37An integer item is created with one of the four widths. Because integers' `storage is bundled together with the handle </internal#c.cbor_item_t.data>`_, the width cannot be changed over its lifetime.
38
39.. warning::
40
41    Due to the fact that CBOR negative integers represent integers in the range :math:`[-1, -2^N]`, ``cbor_set_uint`` API is somewhat counter-intuitive as the resulting logical value is 1 less. This behavior is necessary in order to permit uniform manipulation with the full range of permitted values. For example, the following snippet
42
43    .. code-block:: c
44
45        cbor_item_t * item = cbor_new_int8();
46        cbor_mark_negint(item);
47        cbor_set_uint8(0);
48
49    will produce an item with the logical value of :math:`-1`. There is, however, an upside to this as well: There is only one representation of zero.
50
51
52Building new items
53------------------------
54.. doxygenfunction:: cbor_build_uint8
55.. doxygenfunction:: cbor_build_uint16
56.. doxygenfunction:: cbor_build_uint32
57.. doxygenfunction:: cbor_build_uint64
58
59
60Retrieving values
61------------------------
62.. doxygenfunction:: cbor_get_uint8
63.. doxygenfunction:: cbor_get_uint16
64.. doxygenfunction:: cbor_get_uint32
65.. doxygenfunction:: cbor_get_uint64
66
67Setting values
68------------------------
69
70.. doxygenfunction:: cbor_set_uint8
71.. doxygenfunction:: cbor_set_uint16
72.. doxygenfunction:: cbor_set_uint32
73.. doxygenfunction:: cbor_set_uint64
74
75Dealing with width
76---------------------
77.. doxygenfunction:: cbor_int_get_width
78
79Dealing with signedness
80--------------------------
81
82.. doxygenfunction:: cbor_mark_uint
83.. doxygenfunction:: cbor_mark_negint
84
85Creating new items
86------------------------
87
88.. doxygenfunction:: cbor_new_int8
89.. doxygenfunction:: cbor_new_int16
90.. doxygenfunction:: cbor_new_int32
91.. doxygenfunction:: cbor_new_int64
92