programmer's 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-2018 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 
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_INTEGER (1 << 0) /* 1: value is an integer */
52 #define CS_TREE_NODE_REAL (1 << 1) /* 2: value is a cs_real_t */
53 #define CS_TREE_NODE_BOOL (1 << 2) /* 4: value is a bool */
54 
55 /*============================================================================
56  * Type definitions
57  *============================================================================*/
58 
59 typedef struct _cs_tree_node_t cs_tree_node_t;
60 
62 
63  char *name; /* name of the node */
64  char *desc; /* NULL or short description/help about this node */
65  int flag; /* metadata used to specified the node behavior */
66 
67  void *value; /* value related to this node. Cast on-the-fly */
68  int size; /* size > 1 if it is an array */
69 
70  /* Pointers to other nodes to allow an easy navigation among the tree */
71 
72  cs_tree_node_t *parent; /* Pointer to the parent node or NULL if root */
73  cs_tree_node_t *children; /* Pointer to the first child or NULL */
74  cs_tree_node_t *prev; /* Pointer to a previous node sharing the same
75  parent or NULL if this is the first child */
76  cs_tree_node_t *next; /* Pointer to a next node sharing the same parent
77  or NULL if there is no next node */
78 
79 };
80 
81 /*============================================================================
82  * Public function prototypes
83  *============================================================================*/
84 
85 /*----------------------------------------------------------------------------*/
95 /*----------------------------------------------------------------------------*/
96 
97 cs_tree_node_t *
98 cs_tree_node_create(const char *name);
99 
100 /*----------------------------------------------------------------------------*/
108 /*----------------------------------------------------------------------------*/
109 
110 void
111 cs_tree_node_free(cs_tree_node_t **pnode);
112 
113 /*----------------------------------------------------------------------------*/
120 /*----------------------------------------------------------------------------*/
121 
122 void
123 cs_tree_node_set_name(cs_tree_node_t *node,
124  const char *name);
125 
126 /*----------------------------------------------------------------------------*/
133 /*----------------------------------------------------------------------------*/
134 
135 void
136 cs_tree_node_set_val_string(cs_tree_node_t *node,
137  const char *val);
138 
139 /*----------------------------------------------------------------------------*/
148 /*----------------------------------------------------------------------------*/
149 
150 static inline void
151 cs_tree_node_set_string_val(cs_tree_node_t *node,
152  const char *val)
153 {
154  cs_tree_node_set_val_string(node, val);
155 }
156 
157 /*----------------------------------------------------------------------------*/
164 /*----------------------------------------------------------------------------*/
165 
166 void
167 cs_tree_node_set_bool(cs_tree_node_t *node,
168  bool val);
169 
170 /*----------------------------------------------------------------------------*/
178 /*----------------------------------------------------------------------------*/
179 
180 void
181 cs_tree_node_set_bool_val(cs_tree_node_t *node,
182  int size,
183  const bool *val);
184 
185 /*----------------------------------------------------------------------------*/
193 /*----------------------------------------------------------------------------*/
194 
195 void
196 cs_tree_node_set_int_val(cs_tree_node_t *node,
197  int size,
198  const int *val);
199 
200 /*----------------------------------------------------------------------------*/
209 /*----------------------------------------------------------------------------*/
210 
211 void
212 cs_tree_node_set_real_val(cs_tree_node_t *node,
213  int size,
214  const cs_real_t *val);
215 
216 /*----------------------------------------------------------------------------*/
224 /*----------------------------------------------------------------------------*/
225 
226 void
228  int depth,
229  const cs_tree_node_t *node);
230 
231 /*----------------------------------------------------------------------------*/
247 /*----------------------------------------------------------------------------*/
248 
249 cs_tree_node_t *
250 cs_tree_get_node_rw(cs_tree_node_t *root,
251  const char *path);
252 
253 /*----------------------------------------------------------------------------*/
267 /*----------------------------------------------------------------------------*/
268 
269 const cs_tree_node_t *
270 cs_tree_get_node(const cs_tree_node_t *root,
271  const char *path);
272 
273 /*----------------------------------------------------------------------------*/
286 /*----------------------------------------------------------------------------*/
287 
288 static inline const char *
289 cs_tree_get_node_string_val(const cs_tree_node_t *root,
290  const char *path)
291 {
292  const cs_tree_node_t *node = cs_tree_get_node(root, path);
293  return (const char *)(node->value);
294 }
295 
296 /*----------------------------------------------------------------------------*/
305 /*----------------------------------------------------------------------------*/
306 
307 cs_tree_node_t *
308 cs_tree_add_child(cs_tree_node_t *parent,
309  const char *name);
310 
311 /*----------------------------------------------------------------------------*/
323 /*----------------------------------------------------------------------------*/
324 
325 static inline cs_tree_node_t *
327  const char *name,
328  const char *val_str)
329 {
330  cs_tree_node_t *child = cs_tree_add_child(parent, name);
331  cs_tree_node_set_string_val(child, val_str);
332 
333  return child;
334 }
335 
336 /*----------------------------------------------------------------------------*/
350 /*----------------------------------------------------------------------------*/
351 
352 static inline cs_tree_node_t *
354  const char *name,
355  const char *val_str)
356 {
357  cs_tree_node_t *child = cs_tree_add_child(parent, name);
358  cs_tree_node_set_string_val(child, val_str);
359 
360  return child;
361 }
362 
363 /*----------------------------------------------------------------------------*/
372 /*----------------------------------------------------------------------------*/
373 
374 cs_tree_node_t *
375 cs_tree_add_sibling(cs_tree_node_t *sibling,
376  const char *name);
377 
378 /*----------------------------------------------------------------------------*/
389 /*----------------------------------------------------------------------------*/
390 
391 static inline cs_tree_node_t *
393  const char *name,
394  bool val)
395 {
396  cs_tree_node_t *child = cs_tree_add_child(parent, name);
397  cs_tree_node_set_bool_val(child, 1, &val);
398  return child;
399 }
400 
401 /*----------------------------------------------------------------------------*/
414 /*----------------------------------------------------------------------------*/
415 
416 static inline cs_tree_node_t *
418  const char *name,
419  bool val)
420 {
421  cs_tree_node_t *child = cs_tree_add_child(parent, name);
422  cs_tree_node_set_bool_val(child, 1, &val);
423  return child;
424 }
425 
426 /*----------------------------------------------------------------------------*/
437 /*----------------------------------------------------------------------------*/
438 
439 static inline cs_tree_node_t *
441  const char *name,
442  int val)
443 {
444  cs_tree_node_t *child = cs_tree_add_child(parent, name);
445  cs_tree_node_set_int_val(child, 1, &val);
446 
447  return child;
448 }
449 
450 /*----------------------------------------------------------------------------*/
463 /*----------------------------------------------------------------------------*/
464 
465 static inline cs_tree_node_t *
467  const char *name,
468  int val)
469 {
470  cs_tree_node_t *child = cs_tree_add_child(parent, name);
471  cs_tree_node_set_int_val(child, 1, &val);
472 
473  return child;
474 }
475 
476 /*----------------------------------------------------------------------------*/
487 /*----------------------------------------------------------------------------*/
488 
489 static inline cs_tree_node_t *
491  const char *name,
492  cs_real_t val)
493 {
494  cs_tree_node_t *child = cs_tree_add_child(parent, name);
495  cs_tree_node_set_real_val(child, 1, &val);
496 
497  return child;
498 }
499 
500 /*----------------------------------------------------------------------------*/
513 /*----------------------------------------------------------------------------*/
514 
515 static inline cs_tree_node_t *
517  const char *name,
518  cs_real_t val)
519 {
520  cs_tree_node_t *child = cs_tree_add_child(parent, name);
521  cs_tree_node_set_real_val(child, 1, &val);
522 
523  return child;
524 }
525 
526 /*----------------------------------------------------------------------------*/
534 /*----------------------------------------------------------------------------*/
535 
536 void
538  int depth,
539  const cs_tree_node_t *root);
540 
541 /*----------------------------------------------------------------------------*/
542 
544 
545 #endif /* __CS_TREE_H__ */
static cs_tree_node_t * cs_tree_add_int_child(cs_tree_node_t *parent, const char *name, int val)
Create and add an integer-valued node in a tree below the given parent node.
Definition: cs_tree.h:466
static void cs_tree_node_set_string_val(cs_tree_node_t *node, const char *val)
Allocate the value member of a node and assign to it a string.
Definition: cs_tree.h:151
char * name
Definition: cs_tree.h:63
void cs_tree_node_set_val_string(cs_tree_node_t *node, const char *val)
Allocate the value member of a node and assign to it a string.
Definition: cs_tree.c:358
Definition: cs_tree.h:61
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 a real-valued node in a tree below the given parent node.
Definition: cs_tree.h:490
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 parent node.
Definition: cs_tree.h:440
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 parent node.
Definition: cs_tree.h:392
static cs_tree_node_t * cs_tree_add_string_child(cs_tree_node_t *parent, const char *name, const char *val_str)
Create and add a node in a tree below the given parent node.
Definition: cs_tree.h:353
#define BEGIN_C_DECLS
Definition: cs_defs.h:461
cs_tree_node_t * cs_tree_get_node_rw(cs_tree_node_t *root, const char *path)
Retrieve the pointer to the value member of the node.
Definition: cs_tree.c:635
const cs_tree_node_t * cs_tree_get_node(const cs_tree_node_t *root, const char *path)
Retrieve the pointer to a node with read-only access.
Definition: cs_tree.c:665
void cs_tree_node_set_real_val(cs_tree_node_t *node, int size, const cs_real_t *val)
Allocate the value member of a node and assign to it an array of real values.
Definition: cs_tree.c:462
int size
Definition: cs_tree.h:68
cs_tree_node_t * prev
Definition: cs_tree.h:74
void cs_tree_dump(cs_log_t log, int depth, const cs_tree_node_t *root)
Dump a cs_tree_node_t structure starting from the node "root".
Definition: cs_tree.c:766
void cs_tree_node_set_int_val(cs_tree_node_t *node, int size, const int *val)
Allocate the value member of a node and assign to it an integer.
Definition: cs_tree.c:435
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:488
double cs_real_t
Floating-point value.
Definition: cs_defs.h:297
void cs_tree_node_set_bool_val(cs_tree_node_t *node, int size, const bool *val)
Allocate the value member of a node and assign to it a boolean.
Definition: cs_tree.c:409
cs_tree_node_t * next
Definition: cs_tree.h:76
int flag
Definition: cs_tree.h:65
void cs_tree_node_set_bool(cs_tree_node_t *node, bool val)
Allocate the value member of a node and assign to it a boolean.
Definition: cs_tree.c:386
void cs_tree_node_set_name(cs_tree_node_t *node, const char *name)
Name or rename a node.
Definition: cs_tree.c:336
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 node in a tree below the given parent node.
Definition: cs_tree.h:326
char * desc
Definition: cs_tree.h:64
cs_log_t
Definition: cs_log.h:48
cs_tree_node_t * children
Definition: cs_tree.h:73
void * value
Definition: cs_tree.h:67
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:734
static cs_tree_node_t * cs_tree_add_real_child(cs_tree_node_t *parent, const char *name, cs_real_t val)
Create and add a real-valued node in a tree below the given parent node.
Definition: cs_tree.h:516
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.
Definition: cs_tree.c:690
cs_tree_node_t * cs_tree_node_create(const char *name)
Create an empty node.
Definition: cs_tree.c:269
#define END_C_DECLS
Definition: cs_defs.h:462
static const char * cs_tree_get_node_string_val(const cs_tree_node_t *root, const char *path)
Retrieve a read-only pointer to the value member of the node in case of a string. ...
Definition: cs_tree.h:289
cs_tree_node_t * parent
Definition: cs_tree.h:72
static cs_tree_node_t * cs_tree_add_bool_child(cs_tree_node_t *parent, const char *name, bool val)
Create and add a boolean-valued node in a tree below the given parent node.
Definition: cs_tree.h:417
void cs_tree_node_free(cs_tree_node_t **pnode)
Free a branch in a tree starting from a node.
Definition: cs_tree.c:304