BRL-CAD
db_fullpath.h
Go to the documentation of this file.
1 /* D B _ F U L L P A T H . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 /** @file db_fullpath.h
21  *
22  * librt functions related to fullpaths.
23  */
24 
25 #ifndef RT_DB_FULLPATH_H
26 #define RT_DB_FULLPATH_H
27 
28 /* struct resource requires db_fullpath as part of its definition -
29  * so long as that is true, typedef to avoid circular definition
30  * problem */
31 typedef struct resource struct_resource;
32 
33 /**
34  * For collecting paths through the database tree.
35  * The fp_bool array can optionally hold a boolean flag
36  * associated with each corresponding dp in fp_names. This
37  * array must be manually maintained by the client code in
38  * order for it to have valid data - many functions using
39  * full paths (for example, conversion from strings) don't
40  * have knowledge of a specific boolean tree.
41  */
42 struct db_full_path {
43  uint32_t magic;
44  size_t fp_len;
45  size_t fp_maxlen;
46  struct directory ** fp_names; /**< @brief array of dir pointers */
47  int * fp_bool; /**< @brief array of boolean flags */
48 };
49 #define DB_FULL_PATH_POP(_pp) ((_pp)->fp_len > 0) ? (_pp)->fp_len-- : (_pp)->fp_len
50 
51 #define DB_FULL_PATH_CUR_DIR(_pp) ((_pp)->fp_names[(_pp)->fp_len-1])
52 #define DB_FULL_PATH_CUR_BOOL(_pp) ((_pp)->fp_bool[(_pp)->fp_len-1])
53 #define DB_FULL_PATH_SET_CUR_BOOL(_pp, _i) ((_pp)->fp_bool[(_pp)->fp_len-1] = _i)
54 #define DB_FULL_PATH_ROOT_DIR(_pp) ((_pp)->fp_names[0])
55 #define DB_FULL_PATH_GET(_pp, _i) ((_pp)->fp_names[(_i)])
56 #define DB_FULL_PATH_GET_BOOL(_pp, _i) ((_pp)->fp_bool[(_i)])
57 #define DB_FULL_PATH_SET_BOOL(_pp, _i, _j) ((_pp)->fp_bool[(_i)] = _j)
58 
59 #define RT_CK_FULL_PATH(_p) BU_CKMAG(_p, DB_FULL_PATH_MAGIC, "db_full_path")
60 
61 
62 /* db_fullpath.c */
63 RT_EXPORT extern void db_full_path_init(struct db_full_path *pathp);
64 
65 RT_EXPORT extern void db_add_node_to_full_path(struct db_full_path *pp,
66  struct directory *dp);
67 
68 RT_EXPORT extern void db_dup_full_path(struct db_full_path *newp,
69  const struct db_full_path *oldp);
70 
71 /**
72  * Extend "pathp" so that it can grow from current fp_len by incr more names.
73  *
74  * This is intended primarily as an internal method.
75  */
76 RT_EXPORT extern void db_extend_full_path(struct db_full_path *pathp,
77  size_t incr);
78 
79 RT_EXPORT extern void db_append_full_path(struct db_full_path *dest,
80  const struct db_full_path *src);
81 
82 /**
83  * Dup old path from starting index to end.
84  */
85 RT_EXPORT extern void db_dup_path_tail(struct db_full_path *newp,
86  const struct db_full_path *oldp,
87  off_t start);
88 
89 
90 /**
91  * Unlike rt_path_str(), this version can be used in parallel.
92  * Caller is responsible for freeing the returned buffer.
93  */
94 RT_EXPORT extern char *db_path_to_string(const struct db_full_path *pp);
95 
96 /**
97  * Append a string representation of the path onto the vls. Must have
98  * exactly the same formatting conventions as db_path_to_string().
99  */
100 RT_EXPORT extern void db_path_to_vls(struct bu_vls *str,
101  const struct db_full_path *pp);
102 
103 /**
104  * Append a string representation of the path onto the vls, with
105  * options to decorate nodes with additional information.
106  */
107 #define DB_FP_PRINT_BOOL 0x1 /* print boolean operations */
108 #define DB_FP_PRINT_TYPE 0x2 /* print object types */
109 #define DB_FP_PRINT_MATRIX 0x4 /* print notice that a matrix is present */
110 RT_EXPORT extern void db_fullpath_to_vls(struct bu_vls *vls,
111  const struct db_full_path *full_path,
112  const struct db_i *dbip, /* needed for type determination */
113  int fp_flags);
114 
115 
116 RT_EXPORT extern void db_pr_full_path(const char *msg,
117  const struct db_full_path *pathp);
118 
119 
120 /**
121  * Reverse the effects of db_path_to_string().
122  *
123  * The db_full_path structure will be initialized. If it was already
124  * in use, user should call db_free_full_path() first.
125  *
126  * Returns -
127  * -1 One or more components of path did not exist in the directory.
128  * 0 OK
129  */
130 RT_EXPORT extern int db_string_to_path(struct db_full_path *pp,
131  const struct db_i *dbip,
132  const char *str);
133 
134 
135 /**
136  * Treat elements from argv[0] to argv[argc-1] as a path specification.
137  *
138  * The path structure will be fully initialized. If it was already in
139  * use, user should call db_free_full_path() first.
140  *
141  * Returns -
142  * -1 One or more components of path did not exist in the directory.
143  * 0 OK
144  */
145 RT_EXPORT extern int db_argv_to_path(struct db_full_path *pp,
146  struct db_i *dbip,
147  int argc,
148  const char *const*argv);
149 
150 
151 /**
152  * Free the contents of the db_full_path structure, but not the
153  * structure itself, which might be automatic.
154  */
155 RT_EXPORT extern void db_free_full_path(struct db_full_path *pp);
156 
157 
158 /**
159  * Returns -
160  * 1 match
161  * 0 different
162  */
163 RT_EXPORT extern int db_identical_full_paths(const struct db_full_path *a,
164  const struct db_full_path *b);
165 
166 
167 /**
168  * Returns -
169  * 1 if 'b' is a proper subset of 'a'
170  * 0 if not.
171  */
172 RT_EXPORT extern int db_full_path_subset(const struct db_full_path *a,
173  const struct db_full_path *b,
174  const int skip_first);
175 
176 /**
177  * Returns -
178  * 1 if 'a' matches the top part of 'b'
179  * 0 if not.
180  *
181  * For example, /a/b matches both the top part of /a/b/c and /a/b.
182  */
183 RT_EXPORT extern int db_full_path_match_top(const struct db_full_path *a,
184  const struct db_full_path *b);
185 
186 
187 /**
188  * Returns -
189  * 1 'dp' is found on this path
190  * 0 not found
191  */
192 RT_EXPORT extern int db_full_path_search(const struct db_full_path *a,
193  const struct directory *dp);
194 
195 /**
196  * Build the transformation matrix obtained when traversing the path
197  * to the specified depth.
198  *
199  * Returns -
200  * 1 OK, path matrix written into 'mat'.
201  * 0 FAIL
202  *
203  * Called in librt/db_tree.c, mged/dodraw.c, and mged/animedit.c
204  */
205 RT_EXPORT extern int db_path_to_mat(struct db_i *dbip,
206  struct db_full_path *pathp,
207  mat_t mat, /* result */
208  int depth, /* number of arcs */
209  struct resource *resp);
210 
211 
212 #endif /*RT_DB_FULLPATH_H*/
213 
214 /*
215  * Local Variables:
216  * tab-width: 8
217  * mode: C
218  * indent-tabs-mode: t
219  * c-file-style: "stroustrup"
220  * End:
221  * ex: shiftwidth=4 tabstop=8
222  */
Definition: raytrace.h:800
void db_add_node_to_full_path(struct db_full_path *pp, struct directory *dp)
Definition: db_fullpath.c:54
void db_extend_full_path(struct db_full_path *pathp, size_t incr)
Definition: db_fullpath.c:111
int db_argv_to_path(struct db_full_path *pp, struct db_i *dbip, int argc, const char *const *argv)
Definition: db_fullpath.c:438
size_t fp_len
Definition: db_fullpath.h:44
int db_full_path_search(const struct db_full_path *a, const struct directory *dp)
Definition: db_fullpath.c:579
void db_dup_full_path(struct db_full_path *newp, const struct db_full_path *oldp)
Definition: db_fullpath.c:87
void db_dup_path_tail(struct db_full_path *newp, const struct db_full_path *oldp, off_t start)
Definition: db_fullpath.c:165
void db_fullpath_to_vls(struct bu_vls *vls, const struct db_full_path *full_path, const struct db_i *dbip, int fp_flags)
Definition: db_fullpath.c:254
void db_full_path_init(struct db_full_path *pathp)
Definition: db_fullpath.c:40
int db_full_path_match_top(const struct db_full_path *a, const struct db_full_path *b)
Definition: db_fullpath.c:559
int db_full_path_subset(const struct db_full_path *a, const struct db_full_path *b, const int skip_first)
Definition: db_fullpath.c:515
int * fp_bool
array of boolean flags
Definition: db_fullpath.h:47
int db_identical_full_paths(const struct db_full_path *a, const struct db_full_path *b)
Definition: db_fullpath.c:492
size_t fp_maxlen
Definition: db_fullpath.h:45
int db_string_to_path(struct db_full_path *pp, const struct db_i *dbip, const char *str)
Definition: db_fullpath.c:361
void db_free_full_path(struct db_full_path *pp)
Definition: db_fullpath.c:473
uint32_t magic
Definition: db_fullpath.h:43
struct directory ** fp_names
array of dir pointers
Definition: db_fullpath.h:46
char * db_path_to_string(const struct db_full_path *pp)
Definition: db_fullpath.c:191
void db_path_to_vls(struct bu_vls *str, const struct db_full_path *pp)
Definition: db_fullpath.c:233
void db_pr_full_path(const char *msg, const struct db_full_path *pathp)
Definition: db_fullpath.c:342
Definition: vls.h:56
void db_append_full_path(struct db_full_path *dest, const struct db_full_path *src)
Definition: db_fullpath.c:145
int db_path_to_mat(struct db_i *dbip, struct db_full_path *pathp, mat_t mat, int depth, struct resource *resp)
Definition: db_fullpath.c:630