Type 3 – UTF-8 strings

CBOR strings have the same structure as Type 2 – Byte strings.

Corresponding cbor_type

CBOR_TYPE_STRING

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

UTF-8 encoding validation

libcbor considers UTF-8 encoding validity to be a part of the well-formedness notion of CBOR and therefore invalid UTF-8 strings will be rejected by the parser. Strings created by the user are not checked.

Getting metadata

size_t cbor_string_length(const cbor_item_t *item)

Returns the length of the underlying string.

For definite strings only

Return

length of the string. Zero if no chunk has been attached yet

Parameters

  • item[borrow]: a definite string

bool cbor_string_is_definite(const cbor_item_t *item)

Is the string definite?

Return

Is the string definite?

Parameters

  • item[borrow]: a string

bool cbor_string_is_indefinite(const cbor_item_t *item)

Is the string indefinite?

Return

Is the string indefinite?

Parameters

  • item[borrow]: a string

size_t cbor_string_chunk_count(const cbor_item_t *item)

Get the number of chunks this string consist of.

Return

The chunk count. 0 for freshly created items.

Parameters

  • item[borrow]: A indefinite string

Reading data

cbor_mutable_data cbor_string_handle(const cbor_item_t *item)

Get the handle to the underlying string.

Definite items only. Modifying the data is allowed. In that case, the caller takes responsibility for the effect on items this item might be a part of

Return

The address of the underlying string. NULL if no data have been assigned yet.

Parameters

  • item[borrow]: A definite string

cbor_item_t **cbor_string_chunks_handle(const cbor_item_t *item)

Get the handle to the array of chunks.

Manipulations with the memory block (e.g. sorting it) are allowed, but the validity and the number of chunks must be retained.

Return

array of cbor_string_chunk_count definite strings

Parameters

  • item[borrow]: A indefinite string

Creating new items

cbor_item_t *cbor_new_definite_string()

Creates a new definite string.

The handle is initialized to NULL and length to 0

Return

new definite string. NULL on malloc failure.

cbor_item_t *cbor_new_indefinite_string()

Creates a new indefinite string.

The chunks array is initialized to NULL and chunkcount to 0

Return

new indefinite string. NULL on malloc failure.

Building items

cbor_item_t *cbor_build_string(const char *val)

Creates a new string and initializes it.

The val will be copied to a newly allocated block

Return

A new string with content handle. NULL on malloc failure.

Parameters

  • val: A null-terminated UTF-8 string

Manipulating existing items

void cbor_string_set_handle(cbor_item_t *item, cbor_mutable_data data, size_t length)

Set the handle to the underlying string.

Warning

Using a pointer to a stack allocated constant is a common mistake. Lifetime of the string will expire when it goes out of scope and the CBOR item will be left inconsistent.

Parameters

  • item[borrow]: A definite string

  • data: The memory block. The caller gives up the ownership of the block. libcbor will deallocate it when appropriate using its free function

  • length: Length of the data block

bool cbor_string_add_chunk(cbor_item_t *item, cbor_item_t *chunk)

Appends a chunk to the string.

Indefinite strings only.

May realloc the chunk storage.

Return

true on success. false on realloc failure. In that case, the refcount of chunk is not increased and the item is left intact.

Parameters

  • item[borrow]: An indefinite string

  • item[incref]: A definite string