# Type 2 – Byte strings

CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a tag). Byte string’s length may or may not be known during encoding. These two kinds of byte strings can be distinguished using `cbor_bytestring_is_definite()` and `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 `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`

## Getting metadata

size_t cbor_bytestring_length(const cbor_item_t *item)

  Returns the length of the binary data.

  For definite byte strings only

  param item:

    a definite bytestring

  return:

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

bool cbor_bytestring_is_definite(const cbor_item_t *item)

  Is the byte string definite?

  param item:

    a byte string

  return:

    Is the byte string definite?

bool cbor_bytestring_is_indefinite(const cbor_item_t *item)

  Is the byte string indefinite?

  param item:

    a byte string

  return:

    Is the byte string indefinite?

size_t cbor_bytestring_chunk_count(const cbor_item_t *item)

  Get the number of chunks this string consist of.

  param item:

    A indefinite bytestring

  return:

    The chunk count. 0 for freshly created items.

## Reading data

cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item)

  Get the handle to the binary data.

  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

  param item:

    A definite byte string

  return:

    The address of the underlying binary data

  return:

    `NULL` if no data have been assigned yet.

cbor_item_t **cbor_bytestring_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.

  param item:

    A indefinite byte string

  return:

    array of cbor_bytestring_chunk_count definite bytestrings

## Creating new items

cbor_item_t *cbor_new_definite_bytestring(void)

  Creates a new definite byte string.

  The handle is initialized to `NULL` and length to 0

  return:

    Reference to the new bytestring item. The item’s reference count is initialized to one.

  return:

    `NULL` if memory allocation fails

cbor_item_t *cbor_new_indefinite_bytestring(void)

  Creates a new indefinite byte string.

  The chunks array is initialized to `NULL` and chunk count to 0

  return:

    Reference to the new bytestring item. The item’s reference count is initialized to one.

  return:

    `NULL` if memory allocation fails

## Building items

cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length)

  Creates a new byte string and initializes it.

  The `handle` will be copied to a newly allocated block

  param handle:

    Block of binary data

  param length:

    Length of `data`

  return:

    Reference to the new bytestring item. The item’s reference count is initialized to one.

  return:

    `NULL` if memory allocation fails

## Manipulating existing items

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

  Set the handle to the binary data.

  param item:

    A definite byte string

  param data:

    The memory block. The caller gives up the ownership of the block. libcbor will deallocate it when appropriate using the `free` implementation configured using cbor_set_allocs

  param length:

    Length of the data block

bool cbor_bytestring_add_chunk(cbor_item_t *item, cbor_item_t *chunk)

  Appends a chunk to the bytestring.

  Indefinite byte strings only.

  May realloc the chunk storage.

  param item:

    An indefinite byte string

  param chunk:

    A definite byte string. Its reference count will be be increased by one.

  return:

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