#include "cs_defs.h"
#include "cs_base.h"
#include "cs_log.h"

Include dependency graph for cs_tree.h:

Data Structures
struct	cs_tree_node_t

Macros
#define	CS_TREE_NODE_CHAR (1 << 0) /* 1: value is a character string */

#define	CS_TREE_NODE_INT (1 << 1) /* 2: value is an integer */

#define	CS_TREE_NODE_REAL (1 << 2) /* 4: value is a cs_real_t */

#define	CS_TREE_NODE_BOOL (1 << 3) /* 8: value is a bool */

#define	CS_TREE_NODE_TAG

Functions
cs_tree_node_t *	cs_tree_node_create (const char *name)
	Create an empty node. More...

void	cs_tree_node_free (cs_tree_node_t **pnode)
	Free a branch in a tree starting from a node. More...

void	cs_tree_node_set_name (cs_tree_node_t node, const char name)
	Name or rename a node. More...

cs_tree_node_t *	cs_tree_node_get_child (cs_tree_node_t node, const char name)
	Return a child node with a given name. More...

cs_tree_node_t *	cs_tree_node_get_next_of_name (cs_tree_node_t *node)
	Return the next sibling node with the same name (type) as a given node. More...

const char *	cs_tree_node_get_tag (cs_tree_node_t node, const char tag)
	Search for a child node (used as a tag) with a given name, and return its associated string value. More...

void	cs_tree_node_set_tag (cs_tree_node_t node, const char tag, const char *tag_str)
	Assign a tag to a given node. More...

const char *	cs_tree_node_get_value_str (cs_tree_node_t *node)
	Return a character string value associated to a node if present. More...

void	cs_tree_node_set_value_str (cs_tree_node_t node, const char val)
	Assign a character string value to a node. More...

const bool *	cs_tree_node_get_values_bool (cs_tree_node_t *node)
	Return array of boolean values associated to a node if present. More...

void	cs_tree_node_set_values_bool (cs_tree_node_t node, int n, const bool val)
	Assign an array of boolean values to node. More...

const int *	cs_tree_node_get_values_int (cs_tree_node_t *node)
	Return an array of integer values associated to a node if present. More...

void	cs_tree_node_set_values_int (cs_tree_node_t node, int n, const int val)
	Assign an array of integer values to a node. More...

const cs_real_t *	cs_tree_node_get_values_real (cs_tree_node_t *node)
	Return an array of real values associated to a node if present. More...

void	cs_tree_node_set_values_real (cs_tree_node_t node, int n, const cs_real_t val)
	Assign an array of real values to a node. More...

const char *	cs_tree_node_get_child_value_str (cs_tree_node_t node, const char child_name)
	Return a string value associated to a child node if present. More...

const bool *	cs_tree_node_get_child_values_bool (cs_tree_node_t node, const char child_name)
	Return array of boolean values associated to a child node if present. More...

const int *	cs_tree_node_get_child_values_int (cs_tree_node_t node, const char child_name)
	Return an array of integer values associated to a child node if present. More...

const cs_real_t *	cs_tree_node_get_child_values_real (cs_tree_node_t node, const char child_name)
	Return an array of real values associated to a child node if present. More...

cs_tree_node_t *	cs_tree_node_get_sibling_with_tag (cs_tree_node_t node, const char tag, const char *tag_value)
	Retrieve the pointer to a node with a child having a given (character string) tag value. More...

void	cs_tree_node_dump (cs_log_t log, int depth, const cs_tree_node_t *node)
	Dump a cs_tree_node_t structure. More...

cs_tree_node_t *	cs_tree_add_node (cs_tree_node_t node, const char path)
	Add a node to a tree. More...

cs_tree_node_t *	cs_tree_get_node (cs_tree_node_t node, const char path)
	Retrieve the pointer to a node matching a given path. More...

int	cs_tree_get_node_count (cs_tree_node_t node, const char path)
	Count number of nodes sharing a given path. More...

cs_tree_node_t *	cs_tree_add_child (cs_tree_node_t parent, const char name)
	Create and add a node in a tree below the given node. More...

cs_tree_node_t *	cs_tree_add_sibling (cs_tree_node_t sibling, const char name)
	Create and add a node in a tree at the right of the given node. More...

cs_tree_node_t *	cs_tree_find_node (cs_tree_node_t root, const char sub_path)
	Retrieve the pointer to a node matching a given sub-path. More...

cs_tree_node_t *	cs_tree_find_node_next (cs_tree_node_t root, cs_tree_node_t current, const char *sub_path)
	Retrieve the pointer to the next node matching a given sub-path and following a given node in a depth-first order. More...

cs_tree_node_t *	cs_tree_find_node_simple (cs_tree_node_t root, const char name)
	Retrieve the pointer to a node's descendants matching a given name. More...

cs_tree_node_t *	cs_tree_find_node_next_simple (cs_tree_node_t root, cs_tree_node_t current, const char *name)
	Retrieve the pointer to the next node with a given name and following a given node in a depth-first order. More...

int	cs_tree_get_sub_node_count (cs_tree_node_t root, const char sub_path)
	Count a node's descendants matching a given sub-path. More...

int	cs_tree_get_sub_node_count_simple (cs_tree_node_t root, const char name)
	Count a node's descendants with a given name. More...

void	cs_tree_dump (cs_log_t log, int depth, const cs_tree_node_t *node)
	Dump a cs_tree_node_t structure starting from a given node. More...

Macro Definition Documentation

◆ CS_TREE_NODE_BOOL

#define CS_TREE_NODE_BOOL (1 << 3) /* 8: value is a bool */

◆ CS_TREE_NODE_CHAR

#define CS_TREE_NODE_CHAR (1 << 0) /* 1: value is a character string */

◆ CS_TREE_NODE_INT

#define CS_TREE_NODE_INT (1 << 1) /* 2: value is an integer */

◆ CS_TREE_NODE_REAL

#define CS_TREE_NODE_REAL (1 << 2) /* 4: value is a cs_real_t */

◆ CS_TREE_NODE_TAG

#define CS_TREE_NODE_TAG

Value:

(1 << 4) /* 16: node is a tag

(metadata for XML conversion) */

Function Documentation

◆ cs_tree_add_child()

cs_tree_node_t* cs_tree_add_child	(	cs_tree_node_t *	parent,
		const char *	name
	)

Create and add a node in a tree below the given node.

Parameters

[in,out]	parent	pointer to the parent node
[in]	name	name of the node to add

Returns: pointer to the new node in the tree structure

Create and add a node in a tree below the given node.

Parameters

[in,out]	parent	pointer to the parent node to handle.
[in]	name	name of the node to add

Returns: pointer to the new node in the tree structure

◆ cs_tree_add_node()

cs_tree_node_t* cs_tree_add_node	(	cs_tree_node_t *	node,
		const char *	path
	)

Add a node to a tree.

This node is located at "path" from the given node, with the path separator indicated by a "/".

Exits on error if a node already exists on this path.

Parameters

[in,out]	node	pointer to the node where we start searching
[in]	path	string describing the path access

Returns: pointer to the new node

◆ cs_tree_add_sibling()

cs_tree_node_t* cs_tree_add_sibling	(	cs_tree_node_t *	sibling,
		const char *	name
	)

Create and add a node in a tree at the right of the given node.

Parameters

[in,out]	sibling	pointer to the sibling node to handle
[in]	name	name of the node to add

Returns: pointer to the new node in the tree structure

◆ cs_tree_dump()

void cs_tree_dump	(	cs_log_t	log,
		int	depth,
		const cs_tree_node_t *	node
	)

Dump a cs_tree_node_t structure starting from a given node.

Parameters

[in]	log	indicate which log file to use
[in]	depth	starting depth in the tree
[in]	node	pointer to a cs_tree_node_t to dump

Dump a cs_tree_node_t structure starting from a given node.

Parameters

[in]	log	indicate which log file to use
[in]	depth	starting depth in the tree
[in]	node	pointer to a cs_tree_node_t to dump

◆ cs_tree_find_node()

cs_tree_node_t* cs_tree_find_node	(	cs_tree_node_t *	root,
		const char *	sub_path
	)

Retrieve the pointer to a node matching a given sub-path.

This node is located at "path" from the given node or one of its descendants, with the path separator indicated by a "/".

In case of multiple nodes sharing the given path, the first such node is returned, using a depth-first search.

Parameters

[in]	root	pointer to the root node where we start searching
[in]	sub_path	string describing the path access

Returns: pointer to the first matching node, or NULL if not found

◆ cs_tree_find_node_next()

cs_tree_node_t* cs_tree_find_node_next	(	cs_tree_node_t *	root,
		cs_tree_node_t *	current,
		const char *	sub_path
	)

Retrieve the pointer to the next node matching a given sub-path and following a given node in a depth-first order.

This node is located at "path" from the given node or one of its descendants, with the path separator indicated by a "/".

If current is NULL, this function behaves as cs_tree_find_node.

Parameters

[in]	root	pointer to the root node where we start searching
[in]	current	pointer to the current node
[in]	sub_path	string describing the path access

Returns: pointer to the next matching node, or NULL if not found

◆ cs_tree_find_node_next_simple()

cs_tree_node_t* cs_tree_find_node_next_simple	(	cs_tree_node_t *	root,
		cs_tree_node_t *	current,
		const char *	name
	)

Retrieve the pointer to the next node with a given name and following a given node in a depth-first order.

This function is similar to cs_tree_find_node_next, but is simpler (as it assumes a simple name instead of a more general path) and should thus be faster.

If current is NULL, this function behaves as cs_tree_find_node.

Parameters

[in]	root	pointer to the root node where we start searching
[in]	current	pointer to the current node
[in]	name	node name searched for

Returns: pointer to the next matching node, or NULL if not found

◆ cs_tree_find_node_simple()

cs_tree_node_t* cs_tree_find_node_simple	(	cs_tree_node_t *	root,
		const char *	name
	)

Retrieve the pointer to a node's descendants matching a given name.

This function is similar to cs_tree_find_node, but is simpler (as it assumes a simple name instead of a more general path) and should thus be faster.

In case of multiple nodes sharing the given path, the first such node is returned, using a depth-first search.

Parameters

[in]	root	pointer to the root node where we start searching
[in]	name	node name searched for

Returns: pointer to the first matching node, or NULL if not found

◆ cs_tree_get_node()

cs_tree_node_t* cs_tree_get_node	(	cs_tree_node_t *	node,
		const char *	path
	)

Retrieve the pointer to a node matching a given path.

This node is located at "path" from the given node, with the path separator indicated by a "/".

In case of multiple nodes sharing the given path, the first such node is returned.

Parameters

[in]	node	pointer to the node where we start searching
[in]	path	string describing the path access

Returns: pointer to the node, or NULL if not found

◆ cs_tree_get_node_count()

int cs_tree_get_node_count	(	cs_tree_node_t *	node,
		const char *	path
	)

Count number of nodes sharing a given path.

Parameters

[in]	node	pointer to the node where we start searching
[in]	path	string describing the path access

Returns: number of nodes sharing path

◆ cs_tree_get_sub_node_count()

int cs_tree_get_sub_node_count	(	cs_tree_node_t *	root,
		const char *	sub_path
	)

Count a node's descendants matching a given sub-path.

These nodes are located at "path" from the given node or one of its descendants, with the path separator indicated by a "/".

Parameters

[in]	root	pointer to the root node where we start searching
[in]	sub_path	string describing the path access

Returns: number of matching nodes

◆ cs_tree_get_sub_node_count_simple()

int cs_tree_get_sub_node_count_simple	(	cs_tree_node_t *	root,
		const char *	name
	)

Count a node's descendants with a given name.

This function is similar to cs_tree_get_sub_node_count, but is simpler (as it assumes a simple name instead of a more general path) and should thus be faster.

Parameters

[in]	root	pointer to the root node where we start searching
[in]	name	node name searched for

Returns: number of matching nodes

◆ cs_tree_node_create()

cs_tree_node_t* cs_tree_node_create ( const char * name )

Create an empty node.

Only the name is assigned if given

Parameters

[in] name name of the node, or NULL

Returns: pointer to a new allocated cs_tree_node_t structure

◆ cs_tree_node_dump()

void cs_tree_node_dump	(	cs_log_t	log,
		int	depth,
		const cs_tree_node_t *	node
	)

Dump a cs_tree_node_t structure.

Parameters

[in]	log	indicate which log file to use
[in]	depth	shift to apply when printing
[in]	node	pointer to a cs_tree_node_t to dump

◆ cs_tree_node_free()

void cs_tree_node_free ( cs_tree_node_t ** pnode )

Free a branch in a tree starting from a node.

If the node is the root of the tree, the whole tree is freed.

Parameters

[in,out] pnode pointer to a pointer to a cs_tree_node_t to free

◆ cs_tree_node_get_child()

cs_tree_node_t* cs_tree_node_get_child	(	cs_tree_node_t *	node,
		const char *	name
	)

Return a child node with a given name.

The child node must be located directly under the given node (i.e. it is a child, not a grand-child or beyond).

This function is similar to cs_tree_get_node, but is simpler (albeit more restricted in scope) and may be faster in cases where one level of the tree is searched at a time.

In case of multiple children sharing the given name, the first such node is returned.

Parameters

[in]	node	pointer to the given node
[in]	name	name of child node

Returns: string value associated to tag if found, or NULL

◆ cs_tree_node_get_child_value_str()

const char* cs_tree_node_get_child_value_str	(	cs_tree_node_t *	node,
		const char *	child_name
	)

Return a string value associated to a child node if present.

The behavior is similar to that of cs_tree_node_get_value_str.

Parameters

[in]	node	pointer to a cs_tree_node_t to access, or NULL
[in]	child_name	name of child node

Returns: pointer to associated values, or NULL

◆ cs_tree_node_get_child_values_bool()

const bool* cs_tree_node_get_child_values_bool	(	cs_tree_node_t *	node,
		const char *	child_name
	)

Return array of boolean values associated to a child node if present.

The behavior is similar to that of cs_tree_node_get_values_bool.

Parameters

[in]	node	pointer to a cs_tree_node_t to access, or NULL
[in]	child_name	name of child node

Returns: pointer to associated values, or NULL

◆ cs_tree_node_get_child_values_int()

const int* cs_tree_node_get_child_values_int	(	cs_tree_node_t *	node,
		const char *	child_name
	)

Return an array of integer values associated to a child node if present.

The behavior is similar to that of cs_tree_node_get_values_int.

Parameters

[in]	node	pointer to a cs_tree_node_t to access, or NULL
[in]	child_name	name of child node

Returns: pointer to associated array, or NULL

◆ cs_tree_node_get_child_values_real()

const cs_real_t* cs_tree_node_get_child_values_real	(	cs_tree_node_t *	node,
		const char *	child_name
	)

Return an array of real values associated to a child node if present.

The behavior is similar to that of cs_tree_node_get_values_real.

Parameters

[in]	node	pointer to a cs_tree_node_t to access, or NULL
[in]	child_name	name of child node

Returns: pointer to associated array, or NULL

◆ cs_tree_node_get_next_of_name()

cs_tree_node_t* cs_tree_node_get_next_of_name ( cs_tree_node_t * node )

Return the next sibling node with the same name (type) as a given node.

The first node of a series is obtained using cs_tree_get_node.

Parameters

[in] node pointer to the starting node

Returns: pointer to next sibling node with same name, or NULL

◆ cs_tree_node_get_sibling_with_tag()

cs_tree_node_t* cs_tree_node_get_sibling_with_tag	(	cs_tree_node_t *	node,
		const char *	tag,
		const char *	tag_value
	)

Retrieve the pointer to a node with a child having a given (character string) tag value.

This node is searched for among siblings of a given node sharing the same path (i.e. the same name).

Using the following example tree:

/ section1 section2 entry label (value = a) entry label (value = b)

Using cs_tree_get_node(node, "section2/entry") will return the first node with path "section2/entry" (which has a child named "label" with value a).

Using cs_tree_node_get_sibling_with_tag(node, "label", "a") from that node will return the same node, while cs_tree_node_get_sibling_with_tag(node, "label", "b") will return the second "section2/entry" node.

This function can be called from any sibling (not necessarily the first).

Parameters

[in]	node	pointer to the starting node
[in]	tag	name of the required "tag" child
[in]	tag_value	value of the required "tag" child

Returns: pointer to the node, or NULL if not found

◆ cs_tree_node_get_tag()

const char* cs_tree_node_get_tag	(	cs_tree_node_t *	node,
		const char *	tag
	)

Search for a child node (used as a tag) with a given name, and return its associated string value.

The child node must be located directly under the given node (i.e. it is a child, not a grand-child or beyond).

If the child "tag" node does not exist, NULL is returned.

The CS_TREE_NODE_TAG flag is set for child nodes accessed by this function. It is currently only relevant for possible mapping to XML.

Parameters

[in]	node	pointer to the given node
[in]	tag	name of child node used as tag

Returns: string value associated to tag if found, or NULL

◆ cs_tree_node_get_value_str()

const char* cs_tree_node_get_value_str ( cs_tree_node_t * node )

Return a character string value associated to a node if present.

If the node was never accessed before and the value type was not defined, it is set to CS_TREE_NODE_CHAR. If it was previously converted to a different type, an error is returned.

Parameters

[in] node pointer to a cs_tree_node_t to access, or NULL

Returns: associated string, or NULL

◆ cs_tree_node_get_values_bool()

const bool* cs_tree_node_get_values_bool ( cs_tree_node_t * node )

Return array of boolean values associated to a node if present.

If the value type was not defined, or defined as a string, values are converted and the type flag set to CS_TREE_NODE_BOOL. If it was previously accessed (and converted) using a different type, an error is returned.

The following strings (case-independent) are converted to "true": "true", "yes", "on", "1". All other strings are converted to "false".

Parameters

[in] node pointer to a cs_tree_node_t to access, or NULL

Returns: pointer to associated values, or NULL

If the value type was not defined, or defined as a string, values are converted and the type flag set to CS_TREE_NODE_BOOL. If it was previously accessed (and converted) using a different type, an error is returned.

The following strings (case-independent) are converted to "true": "true", "yes", "on", "1". All other strings are converted to "false".

Parameters

[in] node pointer to a cs_tree_node_t to access, or NULL

Returns: pointer to associated array, or NULL

◆ cs_tree_node_get_values_int()

const int* cs_tree_node_get_values_int ( cs_tree_node_t * node )

Return an array of integer values associated to a node if present.

If the value type was not defined, or defined as a string, values are converted and the type flag set to CS_TREE_NODE_INT. If it was previously accessed (and converted) using a different type, an error is returned.

Parameters

[in] node pointer to a cs_tree_node_t to access, or NULL

Returns: pointer to associated array, or NULL

◆ cs_tree_node_get_values_real()

const cs_real_t* cs_tree_node_get_values_real ( cs_tree_node_t * node )

Return an array of real values associated to a node if present.

If the value type was not defined, or defined as a string, values are converted and the type flag set to CS_TREE_NODE_REAL. If it was previously accessed (and converted) using a different type, an error is returned.

Parameters

[in] node pointer to a cs_tree_node_t to access, or NULL

Returns: pointer to associated array, or NULL

◆ cs_tree_node_set_name()

void cs_tree_node_set_name	(	cs_tree_node_t *	node,
		const char *	name
	)

Name or rename a node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	name	name to set

◆ cs_tree_node_set_tag()

void cs_tree_node_set_tag	(	cs_tree_node_t *	node,
		const char *	tag,
		const char *	tag_str
	)

Assign a tag to a given node.

A tag is simply a string-valued child node.

The CS_TREE_NODE_TAG flag is also set for this child. It is currently only relevant for possible mapping to XML.

Parameters

[in,out]	node	pointer to the given node
[in]	tag	name of child node used as tag
[in]	tag_str	character string to be copied to tag

◆ cs_tree_node_set_value_str()

void cs_tree_node_set_value_str	(	cs_tree_node_t *	node,
		const char *	val
	)

Assign a character string value to a node.

The assigned value is copied to the node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	val	pointer to character string

The assigned string is copied to the node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	val	pointer to character string

◆ cs_tree_node_set_values_bool()

void cs_tree_node_set_values_bool	(	cs_tree_node_t *	node,
		int	n,
		const bool *	val
	)

Assign an array of boolean values to node.

The assigned array is copied to the node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	n	number of elements in val
[in]	val	array of boolean
[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	n	number of elements in val
[in]	val	array of boolean

◆ cs_tree_node_set_values_int()

void cs_tree_node_set_values_int	(	cs_tree_node_t *	node,
		int	n,
		const int *	val
	)

Assign an array of integer values to a node.

The array values are copied to the node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	n	number of elements in val
[in]	val	array of integers

◆ cs_tree_node_set_values_real()

void cs_tree_node_set_values_real	(	cs_tree_node_t *	node,
		int	n,
		const cs_real_t *	val
	)

Assign an array of real values to a node.

The array values are copied to the node.

Parameters

[in,out]	node	pointer to a cs_tree_node_t to modify
[in]	n	number of elements in val
[in]	val	array of real values

Data Structures

Macros

Functions

Macro Definition Documentation

◆ CS_TREE_NODE_BOOL

◆ CS_TREE_NODE_CHAR

◆ CS_TREE_NODE_INT

◆ CS_TREE_NODE_REAL

◆ CS_TREE_NODE_TAG

Function Documentation

◆ cs_tree_add_child()

◆ cs_tree_add_node()

◆ cs_tree_add_sibling()

◆ cs_tree_dump()

◆ cs_tree_find_node()

◆ cs_tree_find_node_next()

◆ cs_tree_find_node_next_simple()

◆ cs_tree_find_node_simple()

◆ cs_tree_get_node()

◆ cs_tree_get_node_count()

◆ cs_tree_get_sub_node_count()

◆ cs_tree_get_sub_node_count_simple()

◆ cs_tree_node_create()

◆ cs_tree_node_dump()

◆ cs_tree_node_free()

◆ cs_tree_node_get_child()

◆ cs_tree_node_get_child_value_str()

◆ cs_tree_node_get_child_values_bool()

◆ cs_tree_node_get_child_values_int()

◆ cs_tree_node_get_child_values_real()

◆ cs_tree_node_get_next_of_name()

◆ cs_tree_node_get_sibling_with_tag()

◆ cs_tree_node_get_tag()

◆ cs_tree_node_get_value_str()

◆ cs_tree_node_get_values_bool()

◆ cs_tree_node_get_values_int()

◆ cs_tree_node_get_values_real()

◆ cs_tree_node_set_name()

◆ cs_tree_node_set_tag()

◆ cs_tree_node_set_value_str()

◆ cs_tree_node_set_values_bool()

◆ cs_tree_node_set_values_int()

◆ cs_tree_node_set_values_real()