7.2
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-2022 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 
41 BEGIN_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 
63 typedef struct _cs_tree_node_t cs_tree_node_t;
64 
65 struct _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 
101 cs_tree_node_t *
102 cs_tree_node_create(const char *name);
103 
104 /*----------------------------------------------------------------------------*/
112 /*----------------------------------------------------------------------------*/
113 
114 void
115 cs_tree_node_free(cs_tree_node_t **pnode);
116 
117 /*----------------------------------------------------------------------------*/
124 /*----------------------------------------------------------------------------*/
125 
126 void
127 cs_tree_node_set_name(cs_tree_node_t *node,
128  const char *name);
129 
130 /*----------------------------------------------------------------------------*/
149 /*----------------------------------------------------------------------------*/
150 
151 cs_tree_node_t *
152 cs_tree_node_get_child(cs_tree_node_t *node,
153  const char *name);
154 
155 /*----------------------------------------------------------------------------*/
166 /*----------------------------------------------------------------------------*/
167 
168 cs_tree_node_t *
169 cs_tree_node_get_next_of_name(cs_tree_node_t *node);
170 
171 /*----------------------------------------------------------------------------*/
189 /*----------------------------------------------------------------------------*/
190 
191 const char *
192 cs_tree_node_get_tag(cs_tree_node_t *node,
193  const char *tag);
194 
195 /*----------------------------------------------------------------------------*/
208 /*----------------------------------------------------------------------------*/
209 
210 void
211 cs_tree_node_set_tag(cs_tree_node_t *node,
212  const char *tag,
213  const char *tag_str);
214 
215 /*----------------------------------------------------------------------------*/
227 /*----------------------------------------------------------------------------*/
228 
229 const char *
230 cs_tree_node_get_value_str(cs_tree_node_t *node);
231 
232 /*----------------------------------------------------------------------------*/
241 /*----------------------------------------------------------------------------*/
242 
243 void
244 cs_tree_node_set_value_str(cs_tree_node_t *node,
245  const char *val);
246 
247 /*----------------------------------------------------------------------------*/
263 /*----------------------------------------------------------------------------*/
264 
265 const bool *
266 cs_tree_node_get_values_bool(cs_tree_node_t *node);
267 
268 /*----------------------------------------------------------------------------*/
278 /*----------------------------------------------------------------------------*/
279 
280 void
281 cs_tree_node_set_values_bool(cs_tree_node_t *node,
282  int n,
283  const bool *val);
284 
285 /*----------------------------------------------------------------------------*/
292 /*----------------------------------------------------------------------------*/
293 
294 static inline void
295 cs_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 
315 const int *
316 cs_tree_node_get_values_int(cs_tree_node_t *node);
317 
318 /*----------------------------------------------------------------------------*/
328 /*----------------------------------------------------------------------------*/
329 
330 void
331 cs_tree_node_set_values_int(cs_tree_node_t *node,
332  int n,
333  const int *val);
334 
335 /*----------------------------------------------------------------------------*/
342 /*----------------------------------------------------------------------------*/
343 
344 static inline void
345 cs_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 
365 const cs_real_t *
366 cs_tree_node_get_values_real(cs_tree_node_t *node);
367 
368 /*----------------------------------------------------------------------------*/
378 /*----------------------------------------------------------------------------*/
379 
380 void
381 cs_tree_node_set_values_real(cs_tree_node_t *node,
382  int n,
383  const cs_real_t *val);
384 
385 /*----------------------------------------------------------------------------*/
392 /*----------------------------------------------------------------------------*/
393 
394 static inline void
395 cs_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 
414 const char *
415 cs_tree_node_get_child_value_str(cs_tree_node_t *node,
416  const char *child_name);
417 
418 /*----------------------------------------------------------------------------*/
429 /*----------------------------------------------------------------------------*/
430 
431 const bool *
432 cs_tree_node_get_child_values_bool(cs_tree_node_t *node,
433  const char *child_name);
434 
435 /*----------------------------------------------------------------------------*/
447 /*----------------------------------------------------------------------------*/
448 
449 const int *
450 cs_tree_node_get_child_values_int(cs_tree_node_t *node,
451  const char *child_name);
452 
453 /*----------------------------------------------------------------------------*/
464 /*----------------------------------------------------------------------------*/
465 
466 const cs_real_t *
467 cs_tree_node_get_child_values_real(cs_tree_node_t *node,
468  const char *child_name);
469 
470 /*----------------------------------------------------------------------------*/
508 /*----------------------------------------------------------------------------*/
509 
510 cs_tree_node_t *
511 cs_tree_node_get_sibling_with_tag(cs_tree_node_t *node,
512  const char *tag,
513  const char *tag_value);
514 
515 /*----------------------------------------------------------------------------*/
523 /*----------------------------------------------------------------------------*/
524 
525 void
526 cs_tree_node_dump(cs_log_t log,
527  int depth,
528  const cs_tree_node_t *node);
529 
530 /*----------------------------------------------------------------------------*/
544 /*----------------------------------------------------------------------------*/
545 
546 cs_tree_node_t *
547 cs_tree_add_node(cs_tree_node_t *node,
548  const char *path);
549 
550 /*----------------------------------------------------------------------------*/
565 /*----------------------------------------------------------------------------*/
566 
567 cs_tree_node_t *
568 cs_tree_get_node(cs_tree_node_t *node,
569  const char *path);
570 
571 /*----------------------------------------------------------------------------*/
580 /*----------------------------------------------------------------------------*/
581 
582 int
583 cs_tree_get_node_count(cs_tree_node_t *node,
584  const char *path);
585 
586 /*----------------------------------------------------------------------------*/
601 /*----------------------------------------------------------------------------*/
602 
603 static inline cs_tree_node_t *
604 cs_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 
633 static inline cs_tree_node_t *
634 cs_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 
655 cs_tree_node_t *
656 cs_tree_add_child(cs_tree_node_t *parent,
657  const char *name);
658 
659 /*----------------------------------------------------------------------------*/
671 /*----------------------------------------------------------------------------*/
672 
673 static inline cs_tree_node_t *
674 cs_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 
696 static inline cs_tree_node_t *
697 cs_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 
719 static inline cs_tree_node_t *
720 cs_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 
742 static inline cs_tree_node_t *
743 cs_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 
764 cs_tree_node_t *
765 cs_tree_add_sibling(cs_tree_node_t *sibling,
766  const char *name);
767 
768 /*----------------------------------------------------------------------------*/
783 /*----------------------------------------------------------------------------*/
784 
785 cs_tree_node_t *
786 cs_tree_find_node(cs_tree_node_t *root,
787  const char *sub_path);
788 
789 /*----------------------------------------------------------------------------*/
805 /*----------------------------------------------------------------------------*/
806 
807 cs_tree_node_t *
808 cs_tree_find_node_next(cs_tree_node_t *root,
809  cs_tree_node_t *current,
810  const char *sub_path);
811 
812 /*----------------------------------------------------------------------------*/
828 /*----------------------------------------------------------------------------*/
829 
830 cs_tree_node_t *
831 cs_tree_find_node_simple(cs_tree_node_t *root,
832  const char *name);
833 
834 /*----------------------------------------------------------------------------*/
851 /*----------------------------------------------------------------------------*/
852 
853 cs_tree_node_t *
854 cs_tree_find_node_next_simple(cs_tree_node_t *root,
855  cs_tree_node_t *current,
856  const char *name);
857 
858 /*----------------------------------------------------------------------------*/
870 /*----------------------------------------------------------------------------*/
871 
872 int
873 cs_tree_get_sub_node_count(cs_tree_node_t *root,
874  const char *sub_path);
875 
876 /*----------------------------------------------------------------------------*/
889 /*----------------------------------------------------------------------------*/
890 
891 int
892 cs_tree_get_sub_node_count_simple(cs_tree_node_t *root,
893  const char *name);
894 
895 /*----------------------------------------------------------------------------*/
903 /*----------------------------------------------------------------------------*/
904 
905 void
906 cs_tree_dump(cs_log_t log,
907  int depth,
908  const cs_tree_node_t *node);
909 
910 /*----------------------------------------------------------------------------*/
911 
912 END_C_DECLS
913 
914 #endif /* __CS_TREE_H__ */
_cs_tree_node_t::name
char * name
Definition: cs_tree.h:67
cs_log.h
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.c:976
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&#39;s descendants matching a given name.
Definition: cs_tree.c:1615
_cs_tree_node_t
Definition: cs_tree.h:65
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:743
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:720
cs_base.h
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:697
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.c:1060
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.c:1648
cs_defs.h
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.c:506
BEGIN_C_DECLS
#define BEGIN_C_DECLS
Definition: cs_defs.h:510
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:295
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.c:1768
_cs_tree_node_t::size
int size
Definition: cs_tree.h:72
_cs_tree_node_t::prev
cs_tree_node_t * prev
Definition: cs_tree.h:78
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.c:474
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.c:1033
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&#39;s descendants with a given name.
Definition: cs_tree.c:1743
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.c:1499
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.c:1183
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.c:626
cs_real_t
double cs_real_t
Floating-point value.
Definition: cs_defs.h:322
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:634
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.c:802
_cs_tree_node_t::next
cs_tree_node_t * next
Definition: cs_tree.h:80
_cs_tree_node_t::flag
int flag
Definition: cs_tree.h:69
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.c:873
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.c:599
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:604
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.c:440
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.c: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:395
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.c:1139
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.c:770
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.c:905
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:674
_cs_tree_node_t::desc
char * desc
Definition: cs_tree.h:68
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:345
cs_log_t
cs_log_t
Definition: cs_log.h:48
_cs_tree_node_t::children
cs_tree_node_t * children
Definition: cs_tree.h:77
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.c:1328
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.c:544
_cs_tree_node_t::value
void * value
Definition: cs_tree.h:71
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&#39;s descendants matching a given sub-path.
Definition: cs_tree.c:1713
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.c:1460
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.c:699
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.c:1086
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.c:1416
cs_tree_node_create
cs_tree_node_t * cs_tree_node_create(const char *name)
Create an empty node.
Definition: cs_tree.c:373
END_C_DECLS
#define END_C_DECLS
Definition: cs_defs.h:511
_cs_tree_node_t::parent
cs_tree_node_t * parent
Definition: cs_tree.h:76
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.c:663
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.c:408
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.c: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.c:1358
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.c:1383