Types 0 & 1 – Positive and negative integers

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

enum cbor_int_width

Possible widths of CBOR_TYPE_UINT items.

Values:

enumerator CBOR_INT_8

enumerator CBOR_INT_16

enumerator CBOR_INT_32

enumerator CBOR_INT_64

Type 0 - positive integers

Corresponding cbor_type	CBOR_TYPE_UINT
Number of allocations	One per lifetime
Storage requirements	sizeof(cbor_item_t) + sizeof(uint*_t)

Note: once a positive integer has been created, its width cannot be changed.

Type 1 - negative integers

Corresponding cbor_type	CBOR_TYPE_NEGINT
Number of allocations	One per lifetime
Storage requirements	sizeof(cbor_item_t) + sizeof(uint*_t)

Note: once a positive integer has been created, its width cannot be changed.

Type 0 & 1

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

Actual Type of the integer can be checked using item types API.

An integer item is created with one of the four widths. Because integers’ storage is bundled together with the handle, the width cannot be changed over its lifetime.

Warning

Due to the fact that CBOR negative integers represent integers in the range \([-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

cbor_item_t * item = cbor_new_int8();
cbor_mark_negint(item);
cbor_set_uint8(0);

will produce an item with the logical value of \(-1\). There is, however, an upside to this as well: There is only one representation of zero.

Building new items

cbor_item_t *cbor_build_uint8(uint8_t value)

Constructs a new positive integer.

param value:

the value to use

return:

new positive integer or NULL on memory allocation failure

cbor_item_t *cbor_build_uint16(uint16_t value)

Constructs a new positive integer.

param value:

the value to use

return:

new positive integer or NULL on memory allocation failure

cbor_item_t *cbor_build_uint32(uint32_t value)

Constructs a new positive integer.

param value:

the value to use

return:

new positive integer or NULL on memory allocation failure

cbor_item_t *cbor_build_uint64(uint64_t value)

Constructs a new positive integer.

param value:

the value to use

return:

new positive integer or NULL on memory allocation failure

Retrieving values

uint8_t cbor_get_uint8(const cbor_item_t *item)

Extracts the integer value.

param item:

positive or negative integer

return:

the value

uint16_t cbor_get_uint16(const cbor_item_t *item)

Extracts the integer value.

param item:

positive or negative integer

return:

the value

uint32_t cbor_get_uint32(const cbor_item_t *item)

Extracts the integer value.

param item:

positive or negative integer

return:

the value

uint64_t cbor_get_uint64(const cbor_item_t *item)

Extracts the integer value.

param item:

positive or negative integer

return:

the value

Setting values

void cbor_set_uint8(cbor_item_t *item, uint8_t value)

Assigns the integer value.

param item:

positive or negative integer item

param value:

the value to assign. For negative integer, the logical value is -value - 1

void cbor_set_uint16(cbor_item_t *item, uint16_t value)

Assigns the integer value.

param item:

positive or negative integer item

param value:

the value to assign. For negative integer, the logical value is -value - 1

void cbor_set_uint32(cbor_item_t *item, uint32_t value)

Assigns the integer value.

param item:

positive or negative integer item

param value:

the value to assign. For negative integer, the logical value is -value - 1

void cbor_set_uint64(cbor_item_t *item, uint64_t value)

Assigns the integer value.

param item:

positive or negative integer item

param value:

the value to assign. For negative integer, the logical value is -value - 1

Dealing with width

cbor_int_width cbor_int_get_width(const cbor_item_t *item)

Queries the integer width.

param item:

positive or negative integer item

return:

the width

Dealing with signedness

void cbor_mark_uint(cbor_item_t *item)

Marks the integer item as a positive integer.

The data value is not changed

param item:

positive or negative integer item

void cbor_mark_negint(cbor_item_t *item)

Marks the integer item as a negative integer.

The data value is not changed

param item:

positive or negative integer item

Creating new items

cbor_item_t *cbor_new_int8(void)

Allocates new integer with 1B width.

The width cannot be changed once allocated

return:

new positive integer or NULL on memory allocation failure. The value is not initialized

cbor_item_t *cbor_new_int16(void)

Allocates new integer with 2B width.

The width cannot be changed once allocated

return:

new positive integer or NULL on memory allocation failure. The value is not initialized

cbor_item_t *cbor_new_int32(void)

Allocates new integer with 4B width.

The width cannot be changed once allocated

return:

new positive integer or NULL on memory allocation failure. The value is not initialized

cbor_item_t *cbor_new_int64(void)

Allocates new integer with 8B width.

The width cannot be changed once allocated

return:

new positive integer or NULL on memory allocation failure. The value is not initialized