Key-value pairs

Overview

Definition of API for working with key-value pairs

// typedefs

typedef struct te_kvpair te_kvpair;

typedef te_errno te_kvpairs_iter_fn(
    const char *key,
    const char *value,
    void *user
    );

// structs

struct te_kvpair;

// global functions

typedef TAILQ_HEAD(te_kvpair_h, te_kvpair);
void te_kvpair_init(te_kvpair_h* head);
void te_kvpair_fini(te_kvpair_h* head);
void te_kvpair_push(te_kvpair_h* head, const char* key, const char* value_fmt, ...);
void void te_kvpair_push_va(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap);
te_errno te_kvpair_add(te_kvpair_h* head, const char* key, const char* value_fmt, ...);
te_errno te_errno te_kvpair_add_va(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap);
te_errno te_kvpairs_del(te_kvpair_h* head, const char* key);
te_errno te_kvpairs_del_all(te_kvpair_h* head, const char* key);
void te_kvpairs_copy(te_kvpair_h* dest, const te_kvpair_h* src);
void te_kvpairs_copy_key(te_kvpair_h* dest, const te_kvpair_h* src, const char* key);
const char* te_kvpairs_get_nth(const te_kvpair_h* head, const char* key, unsigned int index);
static const char* te_kvpairs_get(const te_kvpair_h* head, const char* key);
te_errno te_kvpairs_get_all(const te_kvpair_h* head, const char* key, te_vec* result);
unsigned int te_kvpairs_count(const te_kvpair_h* head, const char* key);
bool te_kvpairs_has_kv(const te_kvpair_h* head, const char* key, const char* value);
bool te_kvpairs_is_submap(const te_kvpair_h* submap, const te_kvpair_h* supermap);
te_errno te_kvpairs_foreach(const te_kvpair_h* head, te_kvpairs_iter_fn* callback, const char* key, void* user);
te_errno te_kvpair_to_str_gen(const te_kvpair_h* head, const char* delim, te_string* str);
te_errno te_kvpair_to_str(const te_kvpair_h* head, te_string* str);
void te_kvpair_keys_to_str(const te_kvpair_h* head, const char* delim, te_string* str);
void te_kvpair_to_uri_query(const te_kvpair_h* head, te_string* str);
te_errno te_kvpair_from_str(const char* str, te_kvpair_h* head);

// macros

#define TE_KVPAIR_STR_DELIMITER

Detailed Documentation

Definition of API for working with key-value pairs

Typedefs

typedef struct te_kvpair te_kvpair

Element of the list of key-value pair

typedef te_errno te_kvpairs_iter_fn(
    const char *key,
    const char *value,
    void *user
    )

Function type of callbacks used by te_kvpairs_foreach().

Parameters:

key	Current key.
value	Current value.
user	User data.
TE_EOK	te_kvpairs_foreach() will stop immediately and return success to the caller.

Returns:

Status code.

Global Functions

typedef TAILQ_HEAD(te_kvpair_h, te_kvpair)

Head of the list of key-value pair

void te_kvpair_init(te_kvpair_h* head)

Initializes empty key-value pairs list.

Parameters:

head	Head of the list.

void te_kvpair_fini(te_kvpair_h* head)

Free resources allocated for key-value pairs list.

Parameters:

head	Head of the list.

void te_kvpair_push(te_kvpair_h* head, const char* key, const char* value_fmt, ...)

Add a key-value pair.

If there are values bound to key, they are shadowed.

Parameters:

head	Head of the list.
key	Key of value.
value_fmt	Format (*printf-like) string for value string.
…	Respective parameters for format string.

void void te_kvpair_push_va(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap)

Add key-value pair using variadic list.

If there are values bound to key, they are shadowed.

Parameters:

head	Head of the list.
key	Key of value.
value_fmt	Format (*printf-like) string for value string.
ap	List of arguments.

te_errno te_kvpair_add(te_kvpair_h* head, const char* key, const char* value_fmt, ...)

Add a key-value pair.

Unlike te_kvpair_push(), the function will fail if there are existing bindings for key.

Parameters:

head	Head of the list.
key	Key of value.
value_fmt	Format (*printf-like) string for value string.
…	Respective parameters for format string.
TE_EEXIST	The key already exists

Returns:

Status code

te_errno te_errno te_kvpair_add_va(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap)

Add key-value pair using variadic list.

Unlike te_kvpair_push_va(), the function will fail if there are existing bindings for key.

Parameters:

head	Head of the list.
key	Key of value.
value_fmt	Format (*printf-like) string for value string.
ap	List of arguments.
TE_EEXIST	The key already exists

Returns:

Status code.

te_errno te_kvpairs_del(te_kvpair_h* head, const char* key)

Remove the most recently added key-value pair with a given key.

Parameters:

head	Head of the list.
key	Key of value.
TE_ENOENT	No entry with such key.
0	Pair removed successfully.

Returns:

Status code.

te_errno te_kvpairs_del_all(te_kvpair_h* head, const char* key)

Remove all key-value pairs with a given key.

Parameters:

head	Head of the list.
key	Key to delete (may be `NULL` in which case all pairs are deleted).
TE_ENOENT	No entries with a given key.
0	Pair removed successfully.

Returns:

Status code.

void te_kvpairs_copy(te_kvpair_h* dest, const te_kvpair_h* src)

Copy all key-values pairs from src to dest.

All existing key-value pairs in dest are retained, so there are overlapping keys, the bindings from dest will be shadowed by the bindings from src.

Parameters:

dest	Destination key-value pairs.
src	Source key-value pairs.

void te_kvpairs_copy_key(te_kvpair_h* dest, const te_kvpair_h* src, const char* key)

Copy all values bound to key in src to dest.

If key is NULL, the function behaves as te_kvpairs_copy(), i.e. all keys are copied.

If there are bindings in dest for key, they will be shadowed.

If there are no bindings for key in src, dest is unchanged.

Parameters:

dest	Destination key-value pairs.
src	Source key-value pairs.
key	Key to copy.

const char* te_kvpairs_get_nth(const te_kvpair_h* head, const char* key, unsigned int index)

Get the index'th value associated with the key.

The most recently added value has the index 0.

Parameters:

head	Head of the list.
key	Key of required value.
index	Ordinal index of a value to fetch.

Returns:

Requested key value or NULL if there is no such key.

static const char* te_kvpairs_get(const te_kvpair_h* head, const char* key)

Get the most recent value associated with the key.

Parameters:

head	Head of the list.
key	Key of required value.

Returns:

Requested key value or NULL if there is no such key.

te_errno te_kvpairs_get_all(const te_kvpair_h* head, const char* key, te_vec* result)

Get all the values associated with key.

The values are appended to the vector result.

The values are not strduped, so result must not be freed with te_vec_deep_free().

Parameters:

head	Head of the list.
key	Key (may be `NULL`, in which case all values are returned).
result	The output vector.
TE_ENOENT	No value with a given key exists in `head`.

Returns:

Status code.

unsigned int te_kvpairs_count(const te_kvpair_h* head, const char* key)

Count the number of values associated with key.

Parameters:

head	Head of the list.
key	Key (may be `NULL` in which case all values are counted).

Returns:

The number of values associated with key.

bool te_kvpairs_has_kv(const te_kvpair_h* head, const char* key, const char* value)

Test whether heads contains a pair of key and value.

Parameters:

head	Head of the list.
key	Key to check (if `NULL`, any key will suit).
value	Value to check (if `NULL`, any value will suit).

Returns:

true if the kvpairs contain a given key-value pair.

bool te_kvpairs_is_submap(const te_kvpair_h* submap, const te_kvpair_h* supermap)

Test whether submap is a submap of supermap.

A supermap contains all the key-value pairs of the submap. Order and cardinality are not checked, so if supermap contains less identical key-value pairs as submap, it is still considered a supermap.

Parameters:

submap	Submap.
supermap	Supermap.

Returns:

true if submap is a submap of supermap.

te_errno te_kvpairs_foreach(const te_kvpair_h* head, te_kvpairs_iter_fn* callback, const char* key, void* user)

Call callback for all values bound to key.

If callback returns non-zero status, the function returns immediately, but TE_EOK status is treated as success.

Parameters:

head	Head of the list.
callback	Callback function.
key	Key to scan (may be `NULL`, in which case all key-value pairs are scanned).
user	User data for `callback`.
TE_ENOENT	No values have been processed.

Returns:

Status code.

te_errno te_kvpair_to_str_gen(const te_kvpair_h* head, const char* delim, te_string* str)

Convert list of kv_pairs to string representation with delimiter (i.e. key1=val1<delim>key2=val2).

If there are multiple values for the same key, they all be represented as separate key=value pairs.

Parameters:

head	head of the list
delim	delimiter to use
str	pointer to string

Returns:

status code

te_errno te_kvpair_to_str(const te_kvpair_h* head, te_string* str)

Convert list of kv_pairs to string representation (i.e. key1=val1:key2=val2).

If there are multiple values for the same key, they all be represented as separate key=value pairs.

Parameters:

head	Head of the list.
str	Pointer to string.

Returns:

Status code.