Skip to content

dtkvp

Resizable key-value list with pack and text output.

This group of functions provides a key-value pair list, similar to a dictionary or map. It is intended for callers that need mutable string key-value storage with optional serialization. It is designed to support set, lookup, and encoding and dynamic growth.

Mini-guide

  • Initialize a list before use by calling the init function to allocate internal storage.
  • Set or update an entry by calling the set function.
  • Remove an entry by calling the set function with a null value.
  • Read a value by calling the get function, which returns a stored pointer or a null pointer when the key is absent.
  • Serialize or deserialize list contents by calling the pack and unpack functions.
  • Release all resources by calling the dispose function.

Example

#include <dtcore/dtkvp.h>
#include <dtcore/dtstr.h>

static void demo(void)
{
    dtkvp_list_t list;
    const char* v = NULL;
    char* text = NULL;

    dtkvp_list_init(&list);

    dtkvp_list_set(&list, "mode", "demo");
    dtkvp_list_set(&list, "count", "1");

    dtkvp_list_get(&list, "mode", &v);

    dtkvp_list_compose_plain_text(&list, &text, "\n");

    dtstr_dispose(text);
    dtkvp_list_dispose(&list);
}

Data structures

dtkvp_list_t

This type tracks a resizable list of key-value pairs with internal string storage.

Members:

dtkvp_t* items Pointer to the current item array.
int32_t count Number of allocated slots in the item array.
dtbuffer_t* storage Buffer that owns the item array allocation.

dtkvp_t

This type tracks a single key and value string pair.

Members:

const char* key Pointer to the stored key string.
const char* value Pointer to the stored value string.

Functions

dtkvp_list_compose_plain_text

This function appends entries to a caller-managed string buffer as key and value text.

Params:

dtkvp_list_t* self List instance to read from.
char** s Pointer to a mutable string pointer that is extended by the function.
const char* separator String inserted between composed entries.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_dispose

This function releases list storage and any duplicated strings.

Params:

dtkvp_list_t* self List instance to dispose, or null.

Return: void No return value.

dtkvp_list_get

This function looks up a value pointer for a key in the list.

Params:

dtkvp_list_t* self List instance to query.
const char* key Key string to match.
const char** value Output pointer that receives the stored value pointer or null.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_init

This function initializes a list instance and allocates its internal storage.

Params:

dtkvp_list_t* self List instance to initialize.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_packx

This function packs list contents into a caller-provided buffer in packx format.

Params:

dtkvp_list_t* self List instance to pack.
DTPACKABLE_PACKX_ARGS Pack arguments as required by the packx interface.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_packx_length

This function computes the length required to pack list contents in packx format.

Params:

dtkvp_list_t* self List instance to measure.
DTPACKABLE_PACKX_LENGTH_ARGS Length arguments as required by the packx length interface.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_set

This function inserts, updates, or removes a key-value entry in the list.

Params:

dtkvp_list_t* self List instance to modify.
const char* key Key string to match or insert.
const char* value Value string to store, or null to remove the key.

Return: dterr_t* Error object on failure, or null on success.

dtkvp_list_unpackx

This function unpacks list contents from a caller-provided buffer in packx format.

Params:

dtkvp_list_t* self List instance to receive entries.
DTPACKABLE_UNPACKX_ARGS Unpack arguments as required by the unpackx interface.

Return: dterr_t* Error object on failure, or null on success.