cs_tree.c File Reference

#include "cs_defs.h"
#include <assert.h>
#include <ctype.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "bft_mem.h"
#include "cs_tree.h"

Include dependency graph for cs_tree.c:

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 parent 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 the node "root". More...

Detailed Description

Tree structure used to store data and settings.

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 parent node.

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 the node "root".

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 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 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.

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

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