:orphan: .. index:: pair: group; Tree routines. .. _doxid-group__te__tools__te__tree: Tree routines. ============== .. toctree:: :hidden: Overview ~~~~~~~~ Trees are recursive objects which have an attached list of named attributes. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`te_tree` :ref:`te_tree`; typedef :ref:`te_errno` :ref:`te_tree_traverse_fn`( const te_tree *tree, void *data ); typedef :ref:`te_errno` :ref:`te_tree_map_fn`( const te_kvpair_h *src, te_kvpair_h *dst, void *data ); // global functions :ref:`te_errno` :ref:`te_tree_get_int_attr`(const :ref:`te_tree`* tree, const char* attr, intmax_t* result); :ref:`te_errno` :ref:`te_tree_get_float_attr`(const :ref:`te_tree`* tree, const char* attr, double* result); :ref:`te_errno` :ref:`te_tree_get_bool_attr`(const :ref:`te_tree`* tree, const char* attr, bool* result); :ref:`te_tree`* :ref:`te_tree_alloc`(void); void :ref:`te_tree_free`(:ref:`te_tree`* tree); :ref:`te_errno` :ref:`te_tree_add_attr_va`(:ref:`te_tree`* tree, const char* attr, const char* value_fmt, va_list va); :ref:`te_errno` :ref:`te_tree_add_attr`(:ref:`te_tree`* tree, const char* attr, const char* value_fmt, ...); :ref:`te_errno` :ref:`te_tree_add_attrs`(:ref:`te_tree`* tree, const te_kvpair_h* attrs); void :ref:`te_tree_add_child`(:ref:`te_tree`* tree, :ref:`te_tree`* child); void :ref:`te_tree_add_kvpair_children`(:ref:`te_tree`* tree, const te_kvpair_h* kvpair); :ref:`te_tree`* :ref:`te_tree_make_typed`(const char* name, const char* type, ...); const char* :ref:`te_tree_get_attr`(const :ref:`te_tree`* tree, const char* attr); const char* :ref:`te_tree_get_type`(const :ref:`te_tree`* tree); bool :ref:`te_tree_has_attr`(const :ref:`te_tree`* tree, const char* attr, const char* value); bool :ref:`te_tree_has_attrs`(const :ref:`te_tree`* tree, const te_kvpair_h* attrs); const te_kvpair_h* :ref:`te_tree_attrs`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_parent`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_root`(const :ref:`te_tree`* tree); unsigned int :ref:`te_tree_level`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_first_child`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_last_child`(const :ref:`te_tree`* tree); unsigned int :ref:`te_tree_count_children`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_next`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_prev`(const :ref:`te_tree`* tree); unsigned int :ref:`te_tree_position`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_leftmost_leaf`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_rightmost_leaf`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_left`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_right`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_left_leaf`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_right_leaf`(const :ref:`te_tree`* tree); const :ref:`te_tree`* :ref:`te_tree_nth_child`(const :ref:`te_tree`* tree, unsigned int nth); const :ref:`te_tree`* :ref:`te_tree_child_by_attr`(const :ref:`te_tree`* tree, const char* attr, const char* value); const :ref:`te_tree`* :ref:`te_tree_child_by_attrs`(const :ref:`te_tree`* tree, const te_kvpair_h* attrs); :ref:`te_errno` :ref:`te_tree_traverse`(const :ref:`te_tree`* tree, unsigned int minlevel, unsigned int maxlevel, :ref:`te_tree_traverse_fn`* pre_cb, :ref:`te_tree_traverse_fn`* post_cb, void* data); :ref:`te_tree`* :ref:`te_tree_map`(const :ref:`te_tree`* tree, :ref:`te_tree_map_fn`* fn, void* data); bool :ref:`te_tree_validate_types`(const :ref:`te_tree`* tree, bool allow_unknown, const :ref:`te_tree`** bad_node); // macros #define :ref:`TE_TREE_ATTR_NAME` #define :ref:`TE_TREE_ATTR_TYPE` #define :ref:`TE_TREE_ATTR_TYPE_ANNOTATION` #define :ref:`TE_TREE_ATTR_TYPE_ARRAY` #define :ref:`TE_TREE_ATTR_TYPE_AUTO` #define :ref:`TE_TREE_ATTR_TYPE_BOOL` #define :ref:`TE_TREE_ATTR_TYPE_DICT` #define :ref:`TE_TREE_ATTR_TYPE_FLOAT` #define :ref:`TE_TREE_ATTR_TYPE_INT` #define :ref:`TE_TREE_ATTR_TYPE_NULL` #define :ref:`TE_TREE_ATTR_TYPE_STRING` #define :ref:`TE_TREE_ATTR_VALUE` .. _details-group__te__tools__te__tree: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Trees are recursive objects which have an attached list of named attributes. Attributes are just strings, but some attributes may have special meaning for various functions, in particular defining * the name of a given subtree; * its textual value; * its type. Trees are mostly immutable: there are functions to build them incrementally, but once a tree is complete, it is not meant to change. Trees cannot be shared: if a tree is added as a child of some other tree, it cannot be later added as a child of yet another tree. The linear ordering of nodes is defined as follows: * all children follow their parent; * siblings follow each other. This means that if a node has children, its immediate successor will be its first child, otherwise its next sibling if there is one, otherwise the next sibling of its parent and so on. In the same way, the immediate predecessor of a node will be the rightmost leaf node of its previous sibling, if any, otherwise its parent. Typedefs -------- .. index:: pair: typedef; te_tree .. _doxid-group__te__tools__te__tree_1ga2b84e4e8f1d0bed07c2284b551a59ec3: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_tree` te_tree An opaque object representing trees. .. index:: pair: typedef; te_tree_traverse_fn .. _doxid-group__te__tools__te__tree_1ga31e559205db7924f9e107135620778be: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` te_tree_traverse_fn( const te_tree *tree, void *data ) Function type for tree traversal. If the function returns non-zero, the traversal stops immediately, but a value of TE_EOK is returned as zero from :ref:`te_tree_traverse() `. In a pre-callback TE_ESKIP may be returned to prevent descending into the tree children. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - current (sub)tree * - data - user data * - TE_EOK - Stop traversing and report success to the caller. * - TE_ESKIP - Do not descend into the children. .. rubric:: Returns: status code .. index:: pair: typedef; te_tree_map_fn .. _doxid-group__te__tools__te__tree_1gaee884c0c20ac5060480ebcd6c7362e02: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` te_tree_map_fn( const te_kvpair_h *src, te_kvpair_h *dst, void *data ) Attribute mapping function type. ``dst`` is empty upon entry to this function, so it must do copying itself, if needed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - src - source mapping * - dst - destination mapping * - data - user data .. rubric:: Returns: status code Global Functions ---------------- .. index:: pair: function; te_tree_get_int_attr .. _doxid-group__te__tools__te__tree_1ga2dd81f4fa266b482301e50b83281206f: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_get_int_attr(const :ref:`te_tree`* tree, const char* attr, intmax_t* result) Get an integral value of an attribute of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name * - result - resulting value * - TE_ENOENT - No attribute ``attr`` in ``tree``. * - TE_ERANGE - The value does not fit into ``intmax_t``. * - TE_EINVAL - The value is not a valid integer in any base. .. rubric:: Returns: status code .. index:: pair: function; te_tree_get_float_attr .. _doxid-group__te__tools__te__tree_1ga3fa3cae5fe91f1c3a3ccb32cb611c555: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_get_float_attr(const :ref:`te_tree`* tree, const char* attr, double* result) Get a floating-point value of an attribute of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name * - result - resulting value * - TE_ENOENT - No attribute ``attr`` in ``tree``. * - TE_ERANGE - The value does not fit into ``double`` * - TE_EINVAL - The value is not a valid floating-point representation. .. rubric:: Returns: status code .. index:: pair: function; te_tree_get_bool_attr .. _doxid-group__te__tools__te__tree_1ga13bf6cfe09916aa4ea8abb412cd5702f: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_get_bool_attr(const :ref:`te_tree`* tree, const char* attr, bool* result) Get a boolean value of an attribute of a tree. All "natural" way of representing booleans are supported: * ``true``, ``true``, ``True``, ``T``, ``t``, ``YES``, ``yes``, ``Yes``, ``Y``, ``y``, ``1`` all map to ``true`` * ``false``, ``false``, ``False``, ``F``, ``f``, ``NO``, ``no``, * ``No``, ``N``, @xc n, ``0`` and empty string all map to ``false``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name * - result - resulting value * - TE_ENOENT - No attribute ``attr`` in ``tree``. * - TE_EINVAL - The value is not a valid boolean representation. .. rubric:: Returns: status code .. index:: pair: function; te_tree_alloc .. _doxid-group__te__tools__te__tree_1ga40ddb071611c4222e4e19bacf3a04636: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_tree`* te_tree_alloc(void) Allocate an empty tree object. .. rubric:: Returns: a dynamically allocated empty tree (should be freed with :ref:`te_tree_free() `) .. index:: pair: function; te_tree_free .. _doxid-group__te__tools__te__tree_1ga0d40c12e7fd75cdf16f1cffdc9c3da4e: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_tree_free(:ref:`te_tree`* tree) Deallocate ``tree`` and all its subtrees. The function must only be called on a root tree, i.e. the one that is not attached to any parent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - root tree to deallocate .. index:: pair: function; te_tree_add_attr_va .. _doxid-group__te__tools__te__tree_1ga4ec72071756e3f89a2ece80f41cb0271: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_add_attr_va(:ref:`te_tree`* tree, const char* attr, const char* value_fmt, va_list va) Add an attribute to a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to modify * - attr - attribute name * - value_fmt - attribute value format @oaram va variadic list * - TE_EEXIST - ``attr`` already exists in ``tree`` .. rubric:: Returns: status code .. index:: pair: function; te_tree_add_attr .. _doxid-group__te__tools__te__tree_1ga49eb746674ccb620c4f513fdf3512602: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_add_attr(:ref:`te_tree`* tree, const char* attr, const char* value_fmt, ...) Add an attribute to a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to modify * - attr - attribute name * - value_fmt - attribute value format @oaram ... variadic arguments * - TE_EEXIST - ``attr`` already exists in ``tree`` .. rubric:: Returns: status code .. index:: pair: function; te_tree_add_attrs .. _doxid-group__te__tools__te__tree_1ga488504c47553bc5d883acdb7273be8a2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_add_attrs(:ref:`te_tree`* tree, const te_kvpair_h* attrs) Add attributes from the kvpair ``attrs``. If the function returns TE_EEXIST code, all attributes from ``attrs`` that were not in ``tree``, are still added to it. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to modify * - attrs - list of attributes * - TE_EEXIST - some attributes from ``attrs`` were already in ``tree`` .. rubric:: Returns: status code .. index:: pair: function; te_tree_add_child .. _doxid-group__te__tools__te__tree_1ga594076b5acb80ece96b79b1646cb5124: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_tree_add_child(:ref:`te_tree`* tree, :ref:`te_tree`* child) Add a child to a tree. ``child`` becomes the last child of ``tree``. ``child`` must not be already added to any other tree and it must not be deallocated by the caller after it has been added. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to modify * - child - child to add .. index:: pair: function; te_tree_add_kvpair_children .. _doxid-group__te__tools__te__tree_1ga6c22004a65deeff6412ea2f99f440276: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_tree_add_kvpair_children(:ref:`te_tree`* tree, const te_kvpair_h* kvpair) Convert a key-value mapping to children of ``tree``. All key-value pairs from ``kvpair`` are converted to elementary trees each having two attributes: TE_TREE_ATTR_NAME holding the key and TE_TREE_ATTR_VALUE holding the value. These trees are appended as children to ``tree`` in the order of keys in ``kvpair``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to modify * - kvpair - list of child descriptions .. index:: pair: function; te_tree_make_typed .. _doxid-group__te__tools__te__tree_1ga77ae2727e619a5517b65f26c8cf11a6e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_tree`* te_tree_make_typed(const char* name, const char* type, ...) Create a tree with a name and a typed value. ``name`` becomes TE_TREE_ATTR_NAME, ``type`` become TE_TREE_ATTR_TYPE, and the value is determined from the type and variadic arguments: * TE_TREE_ATTR_TYPE_AUTO is not supported; * TE_TREE_ATTR_TYPE_NULL accepts no additional arguments; * TE_TREE_ATTR_TYPE_STRING should have a single string argument; * TE_TREE_ATTR_TYPE_INT should have a single int argument; * TE_TREE_ATTR_TYPE_FLOAT should have a single double argument; * TE_TREE_ATTR_TYPE_BOOL should have a single int argument treated as boolean; * TE_TREE_ATTR_TYPE_ARRAY should have a ``NULL-terminated`` sequence of subtrees, none of which must have a TE_TREE_ATTR_NAME; * TE_TREE_ATTR_TYPE_DICT should have a ``NULL-terminated`` sequence of pairs - name/subtree. Names will be added to subtrees as TE_TREE_ATTR_NAME attributes; * TE_TREE_ATTR_TYPE_ANNOTATION is not supported. If ``name`` is ``NULL``, the resulting tree is unnamed. In most other places TE_TREE_ATTR_TYPE_INT values are represented by ``intmax_t``. However, here a plain int argument is expected, since it should be a more common usecase. .. ref-code-block:: cpp te_tree_make_typed("node0", TE_TREE_ATTR_TYPE_NULL); te_tree_make_typed("node1", TE_TREE_ATTR_TYPE_STRING, "string value"); te_tree_make_typed("node2", TE_TREE_ATTR_TYPE_INT, 42); te_tree_make_typed("node3", TE_TREE_ATTR_TYPE_FLOAT, 42.0); te_tree_make_typed("node4", TE_TREE_ATTR_TYPE_BOOL, true); te_tree_make_typed("node6", TE_TREE_ATTR_TYPE_ARRAY, item1, item2, item3, NULL); te_tree_make_typed("node7", TE_TREE_ATTR_TYPE_DICT, "subnode1", subnode1, "subnode2", subnode2, NULL); .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - name - name of a tree (may be ``NULL``) * - type - type of its value * - ... - variadic arguments defining value .. rubric:: Returns: a fresh tree or ``NULL`` if there are any inconsistencies .. index:: pair: function; te_tree_get_attr .. _doxid-group__te__tools__te__tree_1ga812f9babd773f926fe72d0f317b77c90: .. ref-code-block:: cpp :class: doxyrest-title-code-block const char* te_tree_get_attr(const :ref:`te_tree`* tree, const char* attr) Get a value of an attribute of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name .. rubric:: Returns: attribute value or ``NULL`` if no such attribute .. index:: pair: function; te_tree_get_type .. _doxid-group__te__tools__te__tree_1gab5d3aa15c896ab35353d03e7a5caf0cc: .. ref-code-block:: cpp :class: doxyrest-title-code-block const char* te_tree_get_type(const :ref:`te_tree`* tree) Get the type of a tree. If the tree has TE_TREE_ATTR_TYPE attribute and its value is not TE_TREE_ATTR_TYPE_AUTO, it is returned. Otherwise: * if it has TE_TREE_ATTR_VALUE and no children, the type is assumed to be TE_TREE_ATTR_TYPE_STRING; * otherwise if if has at least one child with a TE_TREE_ATTR_NAME which is not of TE_TREE_ATTR_TYPE_ANNOTATION type, the type is TE_TREE_ATTR_TYPE_DICT; * otherwise the type is TE_TREE_ATTR_TYPE_ARRAY; in particular, if a node has no TE_TREE_ATTR_VALUE and no children, it is assumed to represent an empty array. All scalar nodes without explicit type are detected as TE_TREE_ATTR_TYPE_STRING, even if the value matches some more specific type such as an integer. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to inspect .. rubric:: Returns: type label of ``tree`` (never ``NULL``) .. index:: pair: function; te_tree_has_attr .. _doxid-group__te__tools__te__tree_1ga60e41ed5cb6e0f3da75783bc5c120945: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_tree_has_attr(const :ref:`te_tree`* tree, const char* attr, const char* value) Test whether a tree has an attribute with a given name and value. The presence of the attribute is checked by :ref:`te_kvpairs_has_kv() `, so both ``key`` and ``value`` may be ``NULL``, meaning "any string". .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name (may be ``NULL``) * - value - attribute value (may be ``NULL``) .. rubric:: Returns: ``true`` if there is an attribute with a given name and value .. index:: pair: function; te_tree_has_attrs .. _doxid-group__te__tools__te__tree_1gac21af3238d9a79eab34f76904532d334: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_tree_has_attrs(const :ref:`te_tree`* tree, const te_kvpair_h* attrs) Test whether a tree has all attributes specified by ``attrs``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attrs - list of name-value pairs .. rubric:: Returns: ``true`` if all attributes from ``attrs`` have matching values in ``tree`` .. index:: pair: function; te_tree_attrs .. _doxid-group__te__tools__te__tree_1ga166b22c666e462c9731387edd5884b6c: .. ref-code-block:: cpp :class: doxyrest-title-code-block const te_kvpair_h* te_tree_attrs(const :ref:`te_tree`* tree) Get an immutable attribute list. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: a list of attribute name-value pairs .. index:: pair: function; te_tree_parent .. _doxid-group__te__tools__te__tree_1gac6000568145c90e4dbe2340b41e3f914: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_parent(const :ref:`te_tree`* tree) Get the parent of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the parent of ``tree`` or ``NULL`` .. index:: pair: function; te_tree_root .. _doxid-group__te__tools__te__tree_1ga920babb1160f03a724bb7064d3fc26b6: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_root(const :ref:`te_tree`* tree) Get the root of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the root of ``tree`` (never ``NULL``) .. index:: pair: function; te_tree_level .. _doxid-group__te__tools__te__tree_1ga8b5c7bc4ad424b1655163cb6a0d9b08c: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int te_tree_level(const :ref:`te_tree`* tree) Get the level of a tree. The level is the length of a path from the root to a given subtree. If the tree is the root, the level is 0. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the level of ``tree`` .. index:: pair: function; te_tree_first_child .. _doxid-group__te__tools__te__tree_1gae745257834440a02f610ed00634c5fcc: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_first_child(const :ref:`te_tree`* tree) Get the first (leftmost) child of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the first child of ``tree`` (``NULL`` if none) .. index:: pair: function; te_tree_last_child .. _doxid-group__te__tools__te__tree_1ga1b9c3a9496666dd484b76cf54e8f63be: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_last_child(const :ref:`te_tree`* tree) Get the last (rightmost) child of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the first child of ``tree`` (``NULL`` if none) .. index:: pair: function; te_tree_count_children .. _doxid-group__te__tools__te__tree_1ga61a3689e92b018c37293b3169a6a141f: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int te_tree_count_children(const :ref:`te_tree`* tree) Count the number of children of a tree. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the number of children of ``tree`` .. index:: pair: function; te_tree_next .. _doxid-group__te__tools__te__tree_1ga04be268d5fd4fc7564f1f666f4f180b3: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_next(const :ref:`te_tree`* tree) Get the next sibling of ``tree``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the next sibling of ``tree`` or ``NULL`` .. index:: pair: function; te_tree_prev .. _doxid-group__te__tools__te__tree_1ga96b85e51275fd450976b2116d3aa8b9a: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_prev(const :ref:`te_tree`* tree) Get the previous sibling of ``tree``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the previous sibling of ``tree`` or ``NULL`` .. index:: pair: function; te_tree_position .. _doxid-group__te__tools__te__tree_1ga052362d18d7fbd2cd05612d53f5cb771: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int te_tree_position(const :ref:`te_tree`* tree) Get the position of a tree. The position is the ordinal number of a tree among its siblings. The first child of its parent has a position ``0``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the position of ``tree`` .. index:: pair: function; te_tree_leftmost_leaf .. _doxid-group__te__tools__te__tree_1gaa74e39b8abc1754016231f1db8089830: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_leftmost_leaf(const :ref:`te_tree`* tree) Get the leftmost leaf descendant of ``tree``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the leftmost leaf of ``tree`` (never ``NULL``) .. index:: pair: function; te_tree_rightmost_leaf .. _doxid-group__te__tools__te__tree_1ga87e7bc7212d21363d7d1f9a904325b90: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_rightmost_leaf(const :ref:`te_tree`* tree) Get the rightmost leaf descendant of ``tree``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the leftmost leaf of ``tree`` (never ``NULL``) .. index:: pair: function; te_tree_left .. _doxid-group__te__tools__te__tree_1ga2cd8aac91e2124aecf6baaff9bcbdcdf: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_left(const :ref:`te_tree`* tree) Get the tree immediately preceding ``tree`` in linear order. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the tree immediately preceding ``tree`` or ``NULL`` .. index:: pair: function; te_tree_right .. _doxid-group__te__tools__te__tree_1gabc67f5cf6a2bd40e0a3ab7f550972082: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_right(const :ref:`te_tree`* tree) Get the tree immediately following ``tree`` in linear order. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the tree immediately following ``tree`` or ``NULL`` .. index:: pair: function; te_tree_left_leaf .. _doxid-group__te__tools__te__tree_1ga90031ecb350c4e36d7d387e5c67c12c0: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_left_leaf(const :ref:`te_tree`* tree) Get the nearest leaf following ``tree`` in linear order. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the leaf following ``tree`` or ``NULL`` .. index:: pair: function; te_tree_right_leaf .. _doxid-group__te__tools__te__tree_1ga9739b2402c3b8896181d991e28044ee2: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_right_leaf(const :ref:`te_tree`* tree) Get the nearest leaf preceding ``tree`` in linear order. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree .. rubric:: Returns: the leaf preceding ``tree`` or ``NULL`` .. index:: pair: function; te_tree_nth_child .. _doxid-group__te__tools__te__tree_1ga4e9ee01a83094934d2aaa6fd978bd99a: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_nth_child(const :ref:`te_tree`* tree, unsigned int nth) Get the ``nth`` child of ``tree``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - nth - 0-based index .. rubric:: Returns: the ``nth`` child of ``tree`` or ``NULL`` .. index:: pair: function; te_tree_child_by_attr .. _doxid-group__te__tools__te__tree_1ga8932de79624ca927b601913e54de5e11: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_child_by_attr(const :ref:`te_tree`* tree, const char* attr, const char* value) Get the first child with a given attribute. The check is performed by :ref:`te_tree_has_attr() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name (may be ``NULL``) * - value - attribute name (may be ``NULL``) .. rubric:: Returns: the first matching child or ``NULL`` .. index:: pair: function; te_tree_child_by_attrs .. _doxid-group__te__tools__te__tree_1gadf18b60aef92cdd68914b369030079fc: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_tree`* te_tree_child_by_attrs(const :ref:`te_tree`* tree, const te_kvpair_h* attrs) Get the first child with given attributes. The check is performed by :ref:`te_tree_has_attrs() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree * - attr - attribute name (may be ``NULL``) * - value - attribute name (may be ``NULL``) .. rubric:: Returns: the first matching child or ``NULL`` .. index:: pair: function; te_tree_traverse .. _doxid-group__te__tools__te__tree_1gae02ae10d867dba11a0f92a8015c5bb2e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_tree_traverse(const :ref:`te_tree`* tree, unsigned int minlevel, unsigned int maxlevel, :ref:`te_tree_traverse_fn`* pre_cb, :ref:`te_tree_traverse_fn`* post_cb, void* data) Traverse the ``tree``. Callbacks are only called for subtrees that are at least ``minlevel`` below ``tree``, and the traversal does not go deeper than ``maxlevel`` below ``tree``. So for example to process only direct children of ``tree``, one may use: .. ref-code-block:: cpp te_tree_traverse(tree, 1, 1, child_cb, NULL, userdata); .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to traverse * - minlevel - minimum level to call callbacks on * - maxlevel - maximum level to descend * - pre_cb - preorder callback (may be ``NULL``) * - post_cb - postorder callback (may be ``NULL``) .. rubric:: Returns: status code .. index:: pair: function; te_tree_map .. _doxid-group__te__tools__te__tree_1ga07729a7eb720b68a63612ce3128fccc3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_tree`* te_tree_map(const :ref:`te_tree`* tree, :ref:`te_tree_map_fn`* fn, void* data) Construct a new tree from an old one converting attributes. If the conversion function ``fn`` ever returns non-zero, the new tree is destroyed and ``NULL`` is returned. No attributes of the tree are automatically copied, the mapping function should use :ref:`te_kvpairs_copy() ` or :ref:`te_kvpairs_copy_key() ` to copy the needed attributes. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - source tree * - fn - attribute translation function * - data - user data .. rubric:: Returns: a fresh translated tree or ``NULL`` .. index:: pair: function; te_tree_validate_types .. _doxid-group__te__tools__te__tree_1ga2b305de1667f5b845cd355c36a80a913: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool te_tree_validate_types(const :ref:`te_tree`* tree, bool allow_unknown, const :ref:`te_tree`** bad_node) Check that all subtrees have correct types and values. The type of each node is detected by :ref:`te_tree_get_type() ` and then the following constraints apply: * if the type is TE_TREE_ATTR_TYPE_NULL, the node must have no TE_TREE_ATTR_VALUE and no children; * if the type is scalar (one of TE_TREE_ATTR_TYPE_STRING, TE_TREE_ATTR_TYPE_BOOL, TE_TREE_ATTR_TYPE_INT, TE_TREE_ATTR_TYPE_FLOAT) it must have a TE_TREE_ATTR_VALUE and no children; * if the type is TE_TREE_ATTR_TYPE_BOOL, the value must be valid as per :ref:`te_tree_get_bool_attr() `; * if the type is TE_TREE_ATTR_TYPE_INT, the value must be valid as per :ref:`te_tree_get_int_attr() `; * if the type is TE_TREE_ATTR_TYPE_FLOAT, the value must be valid as per :ref:`te_tree_get_float_attr() `; * if the type is TE_TREE_ATTR_TYPE_ARRAY, all children that are not annotations must have no names; * if the type is TE_TREE_ATTR_TYPE_DICT, all children that are not annotations must have names; * if the type is unknown and ``allow_unknown`` is true, the node itself is always considered valid; children are recursively checked; otherwise the node is invalid; * if the type is TE_TREE_ATTR_TYPE_ANNOTATION, the node is considered valid and no children are further checked. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tree - tree to check * - allow_unknown - allow unknown types for tree nodes * - bad_node - location for a pointer to the first detected bad node .. rubric:: Returns: ``true`` if the tree is valid Macros ------ .. index:: pair: define; TE_TREE_ATTR_NAME .. _doxid-group__te__tools__te__tree_1gac2c8aa2ef3e2ee9ed69cbede1cbd5358: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_NAME Tree name. .. index:: pair: define; TE_TREE_ATTR_TYPE .. _doxid-group__te__tools__te__tree_1gaeed50f88360fdc3744b153b37491d1b7: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE Tree value type. .. index:: pair: define; TE_TREE_ATTR_TYPE_ANNOTATION .. _doxid-group__te__tools__te__tree_1gaf26399ecbc616a2f0ffe434593ea16a1: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_ANNOTATION A node with metadata that should not be serialized in-band. .. index:: pair: define; TE_TREE_ATTR_TYPE_ARRAY .. _doxid-group__te__tools__te__tree_1gaec46098c1c5b0d60d0fcac656ee2bf19: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_ARRAY Linear array. .. index:: pair: define; TE_TREE_ATTR_TYPE_AUTO .. _doxid-group__te__tools__te__tree_1ga9e71764fb324c8b4c484f79c1ed1e278: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_AUTO Auto-detect type (the default if no type attribute). .. index:: pair: define; TE_TREE_ATTR_TYPE_BOOL .. _doxid-group__te__tools__te__tree_1ga51d7769460225450d65c45480a44e439: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_BOOL Boolean type. .. index:: pair: define; TE_TREE_ATTR_TYPE_DICT .. _doxid-group__te__tools__te__tree_1gafb1bd472a22b48caf127e3714a6f89a5: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_DICT Dictionary (an associative array). .. index:: pair: define; TE_TREE_ATTR_TYPE_FLOAT .. _doxid-group__te__tools__te__tree_1gadb3f8e7ebbcf68e156f5256e8305a029: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_FLOAT Floating-point type. .. index:: pair: define; TE_TREE_ATTR_TYPE_INT .. _doxid-group__te__tools__te__tree_1ga05603e03157431ae6b575f533a467bfe: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_INT Integer type. .. index:: pair: define; TE_TREE_ATTR_TYPE_NULL .. _doxid-group__te__tools__te__tree_1gad632db16f4936497c636fc19869a2f80: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_NULL Null type. .. index:: pair: define; TE_TREE_ATTR_TYPE_STRING .. _doxid-group__te__tools__te__tree_1gaa4e094f91811487f3bd6f466591368ef: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_TYPE_STRING String type. .. index:: pair: define; TE_TREE_ATTR_VALUE .. _doxid-group__te__tools__te__tree_1ga59d79a654e9a793f77be4977c9887e25: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_TREE_ATTR_VALUE Tree value.