libcbor 0.12.0
libcbor is a C library for parsing and generating CBOR, the general-purpose schema-less binary data format.
Loading...
Searching...
No Matches
strings.c File Reference
#include "strings.h"
#include <string.h>
#include "internal/memory_utils.h"
#include "internal/unicode.h"

Go to the source code of this file.

Functions

cbor_item_tcbor_new_definite_string (void)
 Creates a new definite string.
 
cbor_item_tcbor_new_indefinite_string (void)
 Creates a new indefinite string.
 
cbor_item_tcbor_build_string (const char *val)
 Creates a new string and initializes it.
 
cbor_item_tcbor_build_stringn (const char *val, size_t length)
 Creates a new string and initializes it.
 
void cbor_string_set_handle (cbor_item_t *item, cbor_mutable_data data, size_t length)
 Set the handle to the underlying string.
 
cbor_item_t ** cbor_string_chunks_handle (const cbor_item_t *item)
 Get the handle to the array of chunks.
 
size_t cbor_string_chunk_count (const cbor_item_t *item)
 Get the number of chunks this string consist of.
 
bool cbor_string_add_chunk (cbor_item_t *item, cbor_item_t *chunk)
 Appends a chunk to the string.
 
size_t cbor_string_length (const cbor_item_t *item)
 Returns the length of the underlying string in bytes.
 
unsigned char * cbor_string_handle (const cbor_item_t *item)
 Get the handle to the underlying string.
 
size_t cbor_string_codepoint_count (const cbor_item_t *item)
 The number of codepoints in this string.
 
bool cbor_string_is_definite (const cbor_item_t *item)
 Is the string definite?
 
bool cbor_string_is_indefinite (const cbor_item_t *item)
 Is the string indefinite?
 

Function Documentation

◆ cbor_build_string()

cbor_item_t * cbor_build_string ( const char * val)

Creates a new string and initializes it.

The data from val will be copied to a newly allocated memory block.

Note that valid UTF-8 strings do not contain null bytes, so this routine is correct for all valid inputs. If the input is not guaranteed to be valid, use cbor_build_stringn instead.

Parameters
valA null-terminated UTF-8 string
Returns
Reference to the new string item. The item's reference count is initialized to one.
NULL if memory allocation fails

Definition at line 44 of file strings.c.

◆ cbor_build_stringn()

cbor_item_t * cbor_build_stringn ( const char * val,
size_t length )

Creates a new string and initializes it.

The data from handle will be copied to a newly allocated memory block.

All `length` bytes will be stored in the string, even if there are null bytes or invalid UTF-8 sequences.

Parameters
valA UTF-8 string, at least `length` bytes long
lengthLength (in bytes) of the string passed in `val`.
Returns
Reference to the new string item. The item's reference count is initialized to one.
NULL if memory allocation fails

Definition at line 55 of file strings.c.

◆ cbor_new_definite_string()

cbor_item_t * cbor_new_definite_string ( void )

Creates a new definite string.

The handle is initialized to NULL and length to 0

Returns
Reference to the new string item. The item's reference count is initialized to one.
NULL if memory allocation fails

Definition at line 13 of file strings.c.

◆ cbor_new_indefinite_string()

cbor_item_t * cbor_new_indefinite_string ( void )

Creates a new indefinite string.

The chunks array is initialized to NULL and chunkcount to 0

Returns
Reference to the new string item. The item's reference count is initialized to one.
NULL if memory allocation fails

Definition at line 25 of file strings.c.

◆ cbor_string_add_chunk()

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.

Parameters
itemAn indefinite string
chunkA definite string item. Its reference count will be increased by one.
Returns
true on success. false on memory allocation failure. In that case, the refcount of `chunk` is not increased and the `item` is left intact.

Definition at line 95 of file strings.c.

◆ cbor_string_chunk_count()

size_t cbor_string_chunk_count ( const cbor_item_t * item)

Get the number of chunks this string consist of.

Parameters
itemA indefinite string
Returns
The chunk count. 0 for freshly created items.

Definition at line 89 of file strings.c.

◆ cbor_string_chunks_handle()

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.

Parameters
itemA indefinite string
Returns
array of cbor_string_chunk_count definite strings

Definition at line 83 of file strings.c.

◆ cbor_string_codepoint_count()

size_t cbor_string_codepoint_count ( const cbor_item_t * item)

The number of codepoints in this string.

Might differ from cbor_string_length if there are multibyte codepoints. If the string data is not valid UTF-8, returns 0.

Parameters
itemA string
Returns
The number of codepoints in this string

Definition at line 132 of file strings.c.

◆ cbor_string_handle()

unsigned char * 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

Parameters
itemA definite string
Returns
The address of the underlying string.
NULL if no data have been assigned yet.

Definition at line 127 of file strings.c.

◆ cbor_string_is_definite()

bool cbor_string_is_definite ( const cbor_item_t * item)

Is the string definite?

Parameters
itema string
Returns
Is the string definite?

Definition at line 137 of file strings.c.

◆ cbor_string_is_indefinite()

bool cbor_string_is_indefinite ( const cbor_item_t * item)

Is the string indefinite?

Parameters
itema string
Returns
Is the string indefinite?

Definition at line 142 of file strings.c.

◆ cbor_string_length()

size_t cbor_string_length ( const cbor_item_t * item)

Returns the length of the underlying string in bytes.

There can be fewer unicode character than bytes (see cbor_string_codepoint_count). For definite strings only.

Parameters
itema definite string
Returns
length of the string. Zero if no chunk has been attached yet

Definition at line 122 of file strings.c.

◆ cbor_string_set_handle()

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

Set the handle to the underlying string.

The data is assumed to be a valid UTF-8 string. If the string is non-empty and invalid, cbor_string_codepoint_count will return 0.

embed:rst:leading-asterisk 
* .. 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
itemA definite string
dataThe memory block. The caller gives up the ownership of the block. libcbor will deallocate it when appropriate using its free function
lengthLength of the data block

Definition at line 65 of file strings.c.