8.3
general documentation
cs_tree.h
Go to the documentation of this file.
1#ifndef __CS_TREE_H__
2#define __CS_TREE_H__
3
4/*============================================================================
5 * Tree structure used to store data and settings.
6 *============================================================================*/
7
8/*
9 This file is part of code_saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2024 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26*/
27
28/*----------------------------------------------------------------------------*/
29
30#include "cs_defs.h"
31
32/*----------------------------------------------------------------------------
33 * Local headers
34 *----------------------------------------------------------------------------*/
35
36#include "cs_base.h"
37#include "cs_log.h"
38
39/*----------------------------------------------------------------------------*/
40
41BEGIN_C_DECLS
42
43/*============================================================================
44 * Macro definitions
45 *============================================================================*/
46
47/* Set of bit masks to tune finely the behavior of a node.
48 By default node value is assumed to be a string.
49 */
50
51#define CS_TREE_NODE_CHAR (1 << 0) /* 1: value is a character string */
52#define CS_TREE_NODE_INT (1 << 1) /* 2: value is an integer */
53#define CS_TREE_NODE_REAL (1 << 2) /* 4: value is a cs_real_t */
54#define CS_TREE_NODE_BOOL (1 << 3) /* 8: value is a bool */
55
56#define CS_TREE_NODE_TAG (1 << 4) /* 16: node is a tag
57 (metadata for XML conversion) */
58
59/*============================================================================
60 * Type definitions
61 *============================================================================*/
62
63typedef struct _cs_tree_node_t cs_tree_node_t;
64
65struct _cs_tree_node_t {
66
67 char *name; /* name of the node */
68 char *desc; /* null or short description/help about this node */
69 int flag; /* metadata used to specify the node behavior */
70
71 void *value; /* value related to this node. Cast on-the-fly */
72 int size; /* size > 1 if it is an array */
73
74 /* Pointers to other nodes to allow an easy navigation among the tree */
75
76 cs_tree_node_t *parent; /* Pointer to the parent node or null if root */
77 cs_tree_node_t *children; /* Pointer to the first child or null */
78 cs_tree_node_t *prev; /* Pointer to a previous node sharing the same
79 parent or null if this is the first child */
80 cs_tree_node_t *next; /* Pointer to a next node sharing the same parent
81 or null if there is no next node */
82
83};
84
85/*============================================================================
86 * Public function prototypes
87 *============================================================================*/
88
89/*----------------------------------------------------------------------------*/
99/*----------------------------------------------------------------------------*/
100
101cs_tree_node_t *
102cs_tree_node_create(const char *name);
103
104/*----------------------------------------------------------------------------*/
112/*----------------------------------------------------------------------------*/
113
114void
115cs_tree_node_free(cs_tree_node_t **pnode);
116
117/*----------------------------------------------------------------------------*/
124/*----------------------------------------------------------------------------*/
125
126void
127cs_tree_node_set_name(cs_tree_node_t *node,
128 const char *name);
129
130/*----------------------------------------------------------------------------*/
149/*----------------------------------------------------------------------------*/
150
151cs_tree_node_t *
152cs_tree_node_get_child(cs_tree_node_t *node,
153 const char *name);
154
155/*----------------------------------------------------------------------------*/
166/*----------------------------------------------------------------------------*/
167
168cs_tree_node_t *
169cs_tree_node_get_next_of_name(cs_tree_node_t *node);
170
171/*----------------------------------------------------------------------------*/
189/*----------------------------------------------------------------------------*/
190
191const char *
192cs_tree_node_get_tag(cs_tree_node_t *node,
193 const char *tag);
194
195/*----------------------------------------------------------------------------*/
208/*----------------------------------------------------------------------------*/
209
210void
211cs_tree_node_set_tag(cs_tree_node_t *node,
212 const char *tag,
213 const char *tag_str);
214
215/*----------------------------------------------------------------------------*/
227/*----------------------------------------------------------------------------*/
228
229const char *
230cs_tree_node_get_value_str(cs_tree_node_t *node);
231
232/*----------------------------------------------------------------------------*/
241/*----------------------------------------------------------------------------*/
242
243void
244cs_tree_node_set_value_str(cs_tree_node_t *node,
245 const char *val);
246
247/*----------------------------------------------------------------------------*/
263/*----------------------------------------------------------------------------*/
264
265const bool *
266cs_tree_node_get_values_bool(cs_tree_node_t *node);
267
268/*----------------------------------------------------------------------------*/
278/*----------------------------------------------------------------------------*/
279
280void
281cs_tree_node_set_values_bool(cs_tree_node_t *node,
282 int n,
283 const bool *val);
284
285/*----------------------------------------------------------------------------*/
292/*----------------------------------------------------------------------------*/
293
294static inline void
295cs_tree_node_set_value_bool(cs_tree_node_t *node,
296 bool val)
297{
298 cs_tree_node_set_values_bool(node, 1, &val);
299}
300
301/*----------------------------------------------------------------------------*/
313/*----------------------------------------------------------------------------*/
314
315const int *
316cs_tree_node_get_values_int(cs_tree_node_t *node);
317
318/*----------------------------------------------------------------------------*/
328/*----------------------------------------------------------------------------*/
329
330void
331cs_tree_node_set_values_int(cs_tree_node_t *node,
332 int n,
333 const int *val);
334
335/*----------------------------------------------------------------------------*/
342/*----------------------------------------------------------------------------*/
343
344static inline void
345cs_tree_node_set_value_int(cs_tree_node_t *node,
346 int val)
347{
348 cs_tree_node_set_values_int(node, 1, &val);
349}
350
351/*----------------------------------------------------------------------------*/
363/*----------------------------------------------------------------------------*/
364
365const cs_real_t *
366cs_tree_node_get_values_real(cs_tree_node_t *node);
367
368/*----------------------------------------------------------------------------*/
378/*----------------------------------------------------------------------------*/
379
380void
381cs_tree_node_set_values_real(cs_tree_node_t *node,
382 int n,
383 const cs_real_t *val);
384
385/*----------------------------------------------------------------------------*/
392/*----------------------------------------------------------------------------*/
393
394static inline void
395cs_tree_node_set_value_real(cs_tree_node_t *node,
396 cs_real_t val)
397{
398 cs_tree_node_set_values_real(node, 1, &val);
399}
400
401/*----------------------------------------------------------------------------*/
412/*----------------------------------------------------------------------------*/
413
414const char *
415cs_tree_node_get_child_value_str(cs_tree_node_t *node,
416 const char *child_name);
417
418/*----------------------------------------------------------------------------*/
429/*----------------------------------------------------------------------------*/
430
431const bool *
432cs_tree_node_get_child_values_bool(cs_tree_node_t *node,
433 const char *child_name);
434
435/*----------------------------------------------------------------------------*/
447/*----------------------------------------------------------------------------*/
448
449const int *
450cs_tree_node_get_child_values_int(cs_tree_node_t *node,
451 const char *child_name);
452
453/*----------------------------------------------------------------------------*/
464/*----------------------------------------------------------------------------*/
465
466const cs_real_t *
467cs_tree_node_get_child_values_real(cs_tree_node_t *node,
468 const char *child_name);
469
470/*----------------------------------------------------------------------------*/
508/*----------------------------------------------------------------------------*/
509
510cs_tree_node_t *
511cs_tree_node_get_sibling_with_tag(cs_tree_node_t *node,
512 const char *tag,
513 const char *tag_value);
514
515/*----------------------------------------------------------------------------*/
523/*----------------------------------------------------------------------------*/
524
525void
526cs_tree_node_dump(cs_log_t log,
527 int depth,
528 const cs_tree_node_t *node);
529
530/*----------------------------------------------------------------------------*/
544/*----------------------------------------------------------------------------*/
545
546cs_tree_node_t *
547cs_tree_add_node(cs_tree_node_t *node,
548 const char *path);
549
550/*----------------------------------------------------------------------------*/
565/*----------------------------------------------------------------------------*/
566
567cs_tree_node_t *
568cs_tree_get_node(cs_tree_node_t *node,
569 const char *path);
570
571/*----------------------------------------------------------------------------*/
580/*----------------------------------------------------------------------------*/
581
582int
583cs_tree_get_node_count(cs_tree_node_t *node,
584 const char *path);
585
586/*----------------------------------------------------------------------------*/
601/*----------------------------------------------------------------------------*/
602
603static inline cs_tree_node_t *
604cs_tree_get_node_with_tag(cs_tree_node_t *node,
605 const char *path,
606 const char *tag,
607 const char *tag_value)
608{
609 cs_tree_node_t *_node = cs_tree_get_node(node, path);
610 if (_node != NULL)
611 _node = cs_tree_node_get_sibling_with_tag(_node, tag, tag_value);
612
613 return _node;
614}
615
616/*----------------------------------------------------------------------------*/
631/*----------------------------------------------------------------------------*/
632
633static inline cs_tree_node_t *
634cs_tree_get_or_add_node(cs_tree_node_t *node,
635 const char *path)
636{
637 cs_tree_node_t *_node = cs_tree_get_node(node, path);
638 if (_node == NULL)
639 node = cs_tree_add_node(_node, path);
640
641 return _node;
642}
643
644/*----------------------------------------------------------------------------*/
653/*----------------------------------------------------------------------------*/
654
655cs_tree_node_t *
656cs_tree_add_child(cs_tree_node_t *parent,
657 const char *name);
658
659/*----------------------------------------------------------------------------*/
671/*----------------------------------------------------------------------------*/
672
673static inline cs_tree_node_t *
674cs_tree_add_child_str(cs_tree_node_t *parent,
675 const char *name,
676 const char *val_str)
677{
678 cs_tree_node_t *child = cs_tree_add_child(parent, name);
679 cs_tree_node_set_value_str(child, val_str);
680
681 return child;
682}
683
684/*----------------------------------------------------------------------------*/
694/*----------------------------------------------------------------------------*/
695
696static inline cs_tree_node_t *
697cs_tree_add_child_bool(cs_tree_node_t *parent,
698 const char *name,
699 bool val)
700{
701 cs_tree_node_t *child = cs_tree_add_child(parent, name);
702 cs_tree_node_set_values_bool(child, 1, &val);
703
704 return child;
705}
706
707/*----------------------------------------------------------------------------*/
717/*----------------------------------------------------------------------------*/
718
719static inline cs_tree_node_t *
720cs_tree_add_child_int(cs_tree_node_t *parent,
721 const char *name,
722 int val)
723{
724 cs_tree_node_t *child = cs_tree_add_child(parent, name);
725 cs_tree_node_set_values_int(child, 1, &val);
726
727 return child;
728}
729
730/*----------------------------------------------------------------------------*/
740/*----------------------------------------------------------------------------*/
741
742static inline cs_tree_node_t *
743cs_tree_add_child_real(cs_tree_node_t *parent,
744 const char *name,
745 cs_real_t val)
746{
747 cs_tree_node_t *child = cs_tree_add_child(parent, name);
748 cs_tree_node_set_values_real(child, 1, &val);
749
750 return child;
751}
752
753/*----------------------------------------------------------------------------*/
762/*----------------------------------------------------------------------------*/
763
764cs_tree_node_t *
765cs_tree_add_sibling(cs_tree_node_t *sibling,
766 const char *name);
767
768/*----------------------------------------------------------------------------*/
783/*----------------------------------------------------------------------------*/
784
785cs_tree_node_t *
786cs_tree_find_node(cs_tree_node_t *root,
787 const char *sub_path);
788
789/*----------------------------------------------------------------------------*/
805/*----------------------------------------------------------------------------*/
806
807cs_tree_node_t *
808cs_tree_find_node_next(cs_tree_node_t *root,
809 cs_tree_node_t *current,
810 const char *sub_path);
811
812/*----------------------------------------------------------------------------*/
828/*----------------------------------------------------------------------------*/
829
830cs_tree_node_t *
831cs_tree_find_node_simple(cs_tree_node_t *root,
832 const char *name);
833
834/*----------------------------------------------------------------------------*/
851/*----------------------------------------------------------------------------*/
852
853cs_tree_node_t *
854cs_tree_find_node_next_simple(cs_tree_node_t *root,
855 cs_tree_node_t *current,
856 const char *name);
857
858/*----------------------------------------------------------------------------*/
870/*----------------------------------------------------------------------------*/
871
872int
873cs_tree_get_sub_node_count(cs_tree_node_t *root,
874 const char *sub_path);
875
876/*----------------------------------------------------------------------------*/
889/*----------------------------------------------------------------------------*/
890
891int
892cs_tree_get_sub_node_count_simple(cs_tree_node_t *root,
893 const char *name);
894
895/*----------------------------------------------------------------------------*/
903/*----------------------------------------------------------------------------*/
904
905void
906cs_tree_dump(cs_log_t log,
907 int depth,
908 const cs_tree_node_t *node);
909
910/*----------------------------------------------------------------------------*/
911
912END_C_DECLS
913
914#endif /* __CS_TREE_H__ */
cs_base.h
cs_defs.h
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
cs_real_t
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:543
cs_log.h
cs_log_t
cs_log_t
Definition: cs_log.h:48
cs_tree_get_or_add_node
static cs_tree_node_t * cs_tree_get_or_add_node(cs_tree_node_t *node, const char *path)
Retrieve the pointer to a node, adding it if not present.
Definition: cs_tree.h:633
cs_tree_node_set_value_bool
static void cs_tree_node_set_value_bool(cs_tree_node_t *node, bool val)
Assign a single boolean value to a node.
Definition: cs_tree.h:294
cs_tree_node_set_name
void cs_tree_node_set_name(cs_tree_node_t *node, const char *name)
Name or rename a node.
Definition: cs_tree.cpp:440
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.
Definition: cs_tree.cpp:1713
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.
Definition: cs_tree.cpp:544
cs_tree_add_child_bool
static cs_tree_node_t * cs_tree_add_child_bool(cs_tree_node_t *parent, const char *name, bool val)
Create and add a boolean-valued node in a tree below the given node.
Definition: cs_tree.h:696
cs_tree_add_child_real
static cs_tree_node_t * cs_tree_add_child_real(cs_tree_node_t *parent, const char *name, cs_real_t val)
Create and add an real-valued node in a tree below the given node.
Definition: cs_tree.h:742
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.
Definition: cs_tree.cpp:1416
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.
Definition: cs_tree.cpp:663
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.
Definition: cs_tree.cpp:1183
cs_tree_get_node_with_tag
static cs_tree_node_t * cs_tree_get_node_with_tag(cs_tree_node_t *node, const char *path, const char *tag, const char *tag_value)
Retrieve the pointer to a node with a child having a given (character string) tag value.
Definition: cs_tree.h:603
cs_tree_add_child_int
static cs_tree_node_t * cs_tree_add_child_int(cs_tree_node_t *parent, const char *name, int val)
Create and add an integer-valued node in a tree below the given node.
Definition: cs_tree.h:719
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.
Definition: cs_tree.cpp:1615
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.
Definition: cs_tree.cpp:1383
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.
Definition: cs_tree.cpp:1768
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.
Definition: cs_tree.cpp:905
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.
Definition: cs_tree.cpp:599
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.
Definition: cs_tree.cpp:626
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.
Definition: cs_tree.cpp:1060
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.
Definition: cs_tree.cpp:1743
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...
Definition: cs_tree.cpp:1531
cs_tree_node_set_value_real
static void cs_tree_node_set_value_real(cs_tree_node_t *node, cs_real_t val)
Assign a single real value to a node.
Definition: cs_tree.h:394
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.
Definition: cs_tree.cpp:770
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.
Definition: cs_tree.cpp:1139
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.
Definition: cs_tree.cpp:873
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.
Definition: cs_tree.cpp:1086
cs_tree_node_create
cs_tree_node_t * cs_tree_node_create(const char *name)
Create an empty node.
Definition: cs_tree.cpp:373
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.
Definition: cs_tree.cpp:1033
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.
Definition: cs_tree.cpp:1460
cs_tree_add_child_str
static cs_tree_node_t * cs_tree_add_child_str(cs_tree_node_t *parent, const char *name, const char *val_str)
Create and add a string-valued node in a tree below the given node.
Definition: cs_tree.h:673
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.
Definition: cs_tree.cpp:699
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.
Definition: cs_tree.cpp:474
cs_tree_node_set_value_int
static void cs_tree_node_set_value_int(cs_tree_node_t *node, int val)
Assign a single integer value to a node.
Definition: cs_tree.h:344
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.
Definition: cs_tree.cpp:1499
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.
Definition: cs_tree.cpp:976
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 o...
Definition: cs_tree.cpp:1648
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.
Definition: cs_tree.cpp:1007
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.
Definition: cs_tree.cpp:1358
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.
Definition: cs_tree.cpp:802
cs_tree_node_free
void cs_tree_node_free(cs_tree_node_t **pnode)
Free a branch in a tree starting from a node.
Definition: cs_tree.cpp:408
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.
Definition: cs_tree.cpp:1328
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.
Definition: cs_tree.cpp:506
_cs_tree_node_t
Definition: cs_tree.h:64
_cs_tree_node_t::value
void * value
Definition: cs_tree.h:70
_cs_tree_node_t::children
cs_tree_node_t * children
Definition: cs_tree.h:76
_cs_tree_node_t::desc
char * desc
Definition: cs_tree.h:67
_cs_tree_node_t::size
int size
Definition: cs_tree.h:71
_cs_tree_node_t::name
char * name
Definition: cs_tree.h:66
_cs_tree_node_t::parent
cs_tree_node_t * parent
Definition: cs_tree.h:75
_cs_tree_node_t::next
cs_tree_node_t * next
Definition: cs_tree.h:79
_cs_tree_node_t::flag
int flag
Definition: cs_tree.h:68
_cs_tree_node_t::prev
cs_tree_node_t * prev
Definition: cs_tree.h:77