:orphan: .. index:: pair: group; Key-value pairs .. _doxid-group__te__tools__te__kvpair: Key-value pairs =============== .. toctree:: :hidden: struct_te_kvpair.rst Overview ~~~~~~~~ Definition of API for working with key-value pairs Copyright (C) 2004-2023 OKTET Labs Ltd. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`te_kvpair` :ref:`te_kvpair`; typedef :ref:`te_errno` :ref:`te_kvpairs_iter_fn`( const char *key, const char *value, void *user ); // structs struct :ref:`te_kvpair`; // global functions typedef :ref:`TAILQ_HEAD`(te_kvpair_h, :ref:`te_kvpair`); void :ref:`te_kvpair_init`(te_kvpair_h* head); void :ref:`te_kvpair_fini`(te_kvpair_h* head); void :ref:`te_kvpair_push`(te_kvpair_h* head, const char* key, const char* value_fmt, ...); void void :ref:`te_kvpair_push_va`(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap); :ref:`te_errno` :ref:`te_kvpair_add`(te_kvpair_h* head, const char* key, const char* value_fmt, ...); :ref:`te_errno` :ref:`te_errno` :ref:`te_kvpair_add_va`(te_kvpair_h* head, const char* key, const char* value_fmt, va_list ap); :ref:`te_errno` :ref:`te_kvpairs_del`(te_kvpair_h* head, const char* key); :ref:`te_errno` :ref:`te_kvpairs_del_all`(te_kvpair_h* head, const char* key); void :ref:`te_kvpairs_copy`(te_kvpair_h* dest, const te_kvpair_h* src); void :ref:`te_kvpairs_copy_key`(te_kvpair_h* dest, const te_kvpair_h* src, const char* key); const char* :ref:`te_kvpairs_get_nth`(const te_kvpair_h* head, const char* key, unsigned int index); static const char* :ref:`te_kvpairs_get`(const te_kvpair_h* head, const char* key); :ref:`te_errno` :ref:`te_kvpairs_get_all`(const te_kvpair_h* head, const char* key, :ref:`te_vec`* result); unsigned int :ref:`te_kvpairs_count`(const te_kvpair_h* head, const char* key); bool :ref:`te_kvpairs_has_kv`(const te_kvpair_h* head, const char* key, const char* value); bool :ref:`te_kvpairs_is_submap`(const te_kvpair_h* submap, const te_kvpair_h* supermap); :ref:`te_errno` :ref:`te_kvpairs_foreach`(const te_kvpair_h* head, :ref:`te_kvpairs_iter_fn`* callback, const char* key, void* user); :ref:`te_errno` :ref:`te_kvpair_to_str_gen`(const te_kvpair_h* head, const char* delim, :ref:`te_string`* str); :ref:`te_errno` :ref:`te_kvpair_to_str`(const te_kvpair_h* head, :ref:`te_string`* str); void :ref:`te_kvpair_keys_to_str`(const te_kvpair_h* head, const char* delim, :ref:`te_string`* str); void :ref:`te_kvpair_to_uri_query`(const te_kvpair_h* head, :ref:`te_string`* str); :ref:`te_errno` :ref:`te_kvpair_from_str`(const char* str, te_kvpair_h* head); // macros #define :target:`TE_KVPAIR_STR_DELIMITER` .. _details-group__te__tools__te__kvpair: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Definition of API for working with key-value pairs Copyright (C) 2004-2023 OKTET Labs Ltd. All rights reserved. Typedefs -------- .. index:: pair: typedef; te_kvpair .. _doxid-group__te__tools__te__kvpair_1ga9eb94a761d8ef95bae832f68cef7b239: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_kvpair` te_kvpair Element of the list of key-value pair .. index:: pair: typedef; te_kvpairs_iter_fn .. _doxid-group__te__tools__te__kvpair_1ga92251cdd2d38a1bcb570745d85716cb7: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` te_kvpairs_iter_fn( const char *key, const char *value, void *user ) Function type of callbacks used by :ref:`te_kvpairs_foreach() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - key - Current key. * - value - Current value. * - user - User data. * - TE_EOK - :ref:`te_kvpairs_foreach() ` will stop immediately and return success to the caller. .. rubric:: Returns: Status code. Global Functions ---------------- .. index:: pair: function; TAILQ_HEAD .. _doxid-group__te__tools__te__kvpair_1ga3da727682986809311508418ccfc6e85: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef TAILQ_HEAD(te_kvpair_h, :ref:`te_kvpair`) Head of the list of key-value pair .. index:: pair: function; te_kvpair_init .. _doxid-group__te__tools__te__kvpair_1ga78fb792bf77a95bed45306ae4be8b4bd: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_kvpair_init(te_kvpair_h* head) Initializes empty key-value pairs list. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. .. index:: pair: function; te_kvpair_fini .. _doxid-group__te__tools__te__kvpair_1ga43bdbaba7f58ac25b3a66f5e71dbc142: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_kvpair_fini(te_kvpair_h* head) Free resources allocated for key-value pairs list. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. .. index:: pair: function; te_kvpair_push .. _doxid-group__te__tools__te__kvpair_1ga69d8077de41dbac39fb0d62867097fed: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key of value. * - value_fmt - Format (\*printf-like) string for value string. * - ... - Respective parameters for format string. .. index:: pair: function; te_kvpair_push_va .. _doxid-group__te__tools__te__kvpair_1ga51e300492708da0333549f8580d14c49: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key of value. * - value_fmt - Format (\*printf-like) string for value string. * - ap - List of arguments. .. index:: pair: function; te_kvpair_add .. _doxid-group__te__tools__te__kvpair_1ga8ca548ccbe265be759971d1e1c68cfcc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpair_add(te_kvpair_h* head, const char* key, const char* value_fmt, ...) Add a key-value pair. Unlike :ref:`te_kvpair_push() `, the function will fail if there are existing bindings for ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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 .. rubric:: Returns: Status code .. index:: pair: function; te_kvpair_add_va .. _doxid-group__te__tools__te__kvpair_1ga90e7aa2af255b92482b5715427c6619c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` :ref:`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 :ref:`te_kvpair_push_va() `, the function will fail if there are existing bindings for ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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 .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpairs_del .. _doxid-group__te__tools__te__kvpair_1ga5ce2678cfa82a456cf7125697eae08d6: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpairs_del(te_kvpair_h* head, const char* key) Remove the most recently added key-value pair with a given ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key of value. * - TE_ENOENT - No entry with such key. * - 0 - Pair removed successfully. .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpairs_del_all .. _doxid-group__te__tools__te__kvpair_1gadc9de919cbb25ca7f893e3babc4d65b3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpairs_del_all(te_kvpair_h* head, const char* key) Remove all key-value pairs with a given ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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. .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpairs_copy .. _doxid-group__te__tools__te__kvpair_1ga6dc0bd791d6dd10742d4f9a905f1e34a: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dest - Destination key-value pairs. * - src - Source key-value pairs. .. index:: pair: function; te_kvpairs_copy_key .. _doxid-group__te__tools__te__kvpair_1ga1a62dd41a98f8f294c5a482474af3b2a: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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 :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dest - Destination key-value pairs. * - src - Source key-value pairs. * - key - Key to copy. .. index:: pair: function; te_kvpairs_get_nth .. _doxid-group__te__tools__te__kvpair_1gad27b6e75292e83e6b4001f8329e78780: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key of required value. * - index - Ordinal index of a value to fetch. .. rubric:: Returns: Requested ``key`` value or ``NULL`` if there is no such key. .. index:: pair: function; te_kvpairs_get .. _doxid-group__te__tools__te__kvpair_1ga4ac70c3b6abf5c1f30c40781a6484198: .. ref-code-block:: cpp :class: doxyrest-title-code-block static const char* te_kvpairs_get(const te_kvpair_h* head, const char* key) Get the most recent value associated with the ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key of required value. .. rubric:: Returns: Requested ``key`` value or ``NULL`` if there is no such key. .. index:: pair: function; te_kvpairs_get_all .. _doxid-group__te__tools__te__kvpair_1gaf3b81724b9256faa2af571b1f56ca2b5: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpairs_get_all(const te_kvpair_h* head, const char* key, :ref:`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 :ref:`te_vec_deep_free() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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``. .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpairs_count .. _doxid-group__te__tools__te__kvpair_1ga24230db6ffe89ad82739292938beafbd: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int te_kvpairs_count(const te_kvpair_h* head, const char* key) Count the number of values associated with ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - key - Key (may be ``NULL`` in which case all values are counted). .. rubric:: Returns: The number of values associated with ``key``. .. index:: pair: function; te_kvpairs_has_kv .. _doxid-group__te__tools__te__kvpair_1ga5ed09c9991fd2267c2ce8ad8546f28ef: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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). .. rubric:: Returns: ``true`` if the kvpairs contain a given key-value pair. .. index:: pair: function; te_kvpairs_is_submap .. _doxid-group__te__tools__te__kvpair_1gab8035a4a5e91588a916c7744a194cc29: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - submap - Submap. * - supermap - Supermap. .. rubric:: Returns: ``true`` if ``submap`` is a submap of ``supermap``. .. index:: pair: function; te_kvpairs_foreach .. _doxid-group__te__tools__te__kvpair_1ga5bf1d32041aff6a3bb6dc56480fe564b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpairs_foreach(const te_kvpair_h* head, :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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. .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpair_to_str_gen .. _doxid-group__te__tools__te__kvpair_1ga680d2b5b0d3ff967f936965614866b6b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpair_to_str_gen(const te_kvpair_h* head, const char* delim, :ref:`te_string`* str) Convert list of kv_pairs to string representation with delimiter (i.e. key1=val1key2=val2). If there are multiple values for the same key, they all be represented as separate ``key=value`` pairs. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - head of the list * - delim - delimiter to use * - str - pointer to string .. rubric:: Returns: status code .. index:: pair: function; te_kvpair_to_str .. _doxid-group__te__tools__te__kvpair_1ga9f62f40bc759f391f493359e87d95c2a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpair_to_str(const te_kvpair_h* head, :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list. * - str - Pointer to string. .. rubric:: Returns: Status code. .. rubric:: See also: TE_KVPAIR_STR_DELIMITER .. index:: pair: function; te_kvpair_keys_to_str .. _doxid-group__te__tools__te__kvpair_1ga407429354902407455367a421a090541: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_kvpair_keys_to_str(const te_kvpair_h* head, const char* delim, :ref:`te_string`* str) Convert a list of keys from kv_pairs to a string (i.e. key1key2). If there are multiple values for the same key, they all be represented as separate ``key``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - head of the list * - delim - delimiter to use (maybe ``NULL``) * - str - pointer to string .. rubric:: Returns: Status code. .. index:: pair: function; te_kvpair_to_uri_query .. _doxid-group__te__tools__te__kvpair_1gaaca5089216bd1cd83167ab859583ad75: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_kvpair_to_uri_query(const te_kvpair_h* head, :ref:`te_string`* str) Convert a list of kv pairs to a valid URI query string. If ``str`` is not empty, ``&`` separator is added, so that a query string may be assembled incrementally from several kvpairs. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - head - Head of the list * - str - TE string .. rubric:: See also: :ref:`TE_STRING_URI_ESCAPE_QUERY_VALUE ` .. index:: pair: function; te_kvpair_from_str .. _doxid-group__te__tools__te__kvpair_1ga690ad4257f560b5ec813847c2856ec4e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_kvpair_from_str(const char* str, te_kvpair_h* head) Convert string to list of kv_pairs, .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - str - Pointer to string * - head - Head of the kv_pair list * - Status - code .. rubric:: See also: TE_KVPAIR_STR_DELIMITER