BRL-CAD
search.h
Go to the documentation of this file.
1 /* S E A R C H . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2008-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 /** @addtogroup librt */
21 /** @{ */
22 /** @file include/rt/search.h
23  *
24  * Functionality for searching .g files
25  */
26 
27 #ifndef RT_SEARCH_H
28 #define RT_SEARCH_H
29 
30 #include "common.h"
31 
32 #include "bu/list.h"
33 #include "bu/ptbl.h"
34 
35 #include "rt/defines.h"
36 
37 
38 /**
39  * @brief Search for objects in a geometry database using filters
40  *
41  * The db_search function is a programmatic find-style interface that
42  * lets you search for objects in a geometry database. This function
43  * searches the database using a supplied list of filter criteria.
44  *
45  * The function returns a count of objects matching the filter
46  * criteria and can provide the resulting matches in binary format as
47  * either db_full_path or directory objects depending on the flags
48  * (i.e., depending on whether this is a flat or hierarchical search).
49  *
50  * There are a LOT of filter possibilities. See the search(n) manual
51  * page for details.
52  *
53  * @param[out] results is a bu_ptbl holding either db_full_path or
54  * directory pointers.
55  *
56  * @param flags is a bit field for setting various search options.
57  *
58  * @param filter is a string defining search filters to be used.
59  *
60  * @param path_c is the count of directory paths to be searched.
61  *
62  * @param path_v is one or more directory paths to be searched. If
63  * path_v itself is NULL, all top-level objects are searched
64  *
65  * @param dbip The database instance pointer corresponding to the
66  * current geometry database.
67  *
68  * @return Negative return values indicate a problem with the search,
69  * and non-negative values indicate a successful search. Non-negative
70  * values correspond with the number of objects found.
71  *
72  * @retval -2 Return code when db_search is called with a NULL dbip.
73  * @retval -1 Return code when the plan search string is invalid.
74  * @retval 0 Return code when the search completed successfully but no matches were found.
75  * @retval >0 Return code when the search completed successfully and matched one or more objects.
76  *
77  * The following example assumes a database instance pointer (dbip) is
78  * available and ready to use.
79  *
80  @code
81  size_t i = 0;
82  struct bu_ptbl results = BU_PTBL_INIT_ZERO;
83  const char *plan = "-name *.s -or -below -type region";
84  int matches = db_search(&results, DB_SEARCH_HIDDEN | DB_SEARCH_QUIET , plan, 0, NULL, dbip);
85  for (i = 0; matches > 0 && i < BU_PTBL_LEN(&results); i++) {
86  char *path_str = db_path_to_string((struct db_full_path *)BU_PTBL_GET(&results, i));
87  bu_log("%s\n", path_str);
88  bu_free(path_str, "free db_fullpath_to_string allocation");
89  }
90  db_search_free(&results);
91  @endcode
92  *
93  * Note:
94  * Be aware that if you are using db_search to filter pre-built lists of paths,
95  * you need to check that your generated path list is NOT empty before calling
96  * db_search. If you accidentally send an empty path list into db_search,
97  * it will assume you wanted a tops list, which has a good chance of returning
98  * unwanted results.
99  *
100  */
101 RT_EXPORT extern int db_search(struct bu_ptbl *results,
102  int flags,
103  const char *filter,
104  int path_c,
105  struct directory **path_v,
106  struct db_i *dbip
107 );
108 
109 /* These are the possible search flags. */
110 #define DB_SEARCH_TREE 0x0 /**< @brief Do a hierarchy-aware search. This is the default. */
111 #define DB_SEARCH_FLAT 0x1 /**< @brief Do a flat search without hierarchy */
112 #define DB_SEARCH_HIDDEN 0x2 /**< @brief Search using hidden objects */
113 #define DB_SEARCH_RETURN_UNIQ_DP 0x4 /**< @brief Return the set of unique directory pointers instead of full paths */
114 #define DB_SEARCH_QUIET 0x8 /**< @brief Silence all warnings */
115 
116 /**
117  * Properly free the table contents returned by db_search. The bu_ptbl
118  * itself, if not put on the stack, will need to be freed by the same
119  * calling function that allocated it.
120  */
121 RT_EXPORT extern void db_search_free(struct bu_ptbl *search_results);
122 
123 
124 
125 /***************************************************************
126  * DEPRECATED - all structures and functions below this notice
127  * are replaced by functionality above. Remove after 7.27.0
128  * development starts.
129  ***************************************************************/
130 
132  struct bu_list l;
134  int local;
135 };
136 DEPRECATED RT_EXPORT extern int db_full_path_list_add(const char *path, int local, struct db_i *dbip, struct db_full_path_list *path_list);
137 DEPRECATED RT_EXPORT extern void db_free_full_path_list(struct db_full_path_list *path_list);
138 DEPRECATED RT_EXPORT extern void *db_search_formplan(char **argv,
139  struct db_i *dbip);
140 DEPRECATED RT_EXPORT extern void db_search_freeplan(void **plan);
141 DEPRECATED RT_EXPORT extern struct db_full_path_list *db_search_full_paths(void *searchplan,
142  struct db_full_path_list *path_list,
143  struct db_i *dbip);
144 DEPRECATED RT_EXPORT extern struct bu_ptbl *db_search_unique_objects(void *searchplan,
145  struct db_full_path_list *path_list,
146  struct db_i *dbip);
147 
148 
149 #endif /* RT_SEARCH_H*/
150 /** @} */
151 /*
152  * Local Variables:
153  * mode: C
154  * tab-width: 8
155  * indent-tabs-mode: t
156  * c-file-style: "stroustrup"
157  * End:
158  * ex: shiftwidth=4 tabstop=8
159  */
Definition: raytrace.h:800
DEPRECATED void db_search_freeplan(void **plan)
Definition: search.c:2083
void db_search_free(struct bu_ptbl *search_results)
Definition: search.c:2089
Definition: list.h:118
DEPRECATED void * db_search_formplan(char **argv, struct db_i *dbip)
Definition: search.c:2224
Header file for the BRL-CAD common definitions.
Definition: ptbl.h:62
#define DEPRECATED
Definition: common.h:303
struct db_full_path * path
Definition: search.h:133
DEPRECATED void db_free_full_path_list(struct db_full_path_list *path_list)
Definition: search.c:2076
struct bu_list l
Definition: search.h:132
DEPRECATED struct db_full_path_list * db_search_full_paths(void *searchplan, struct db_full_path_list *path_list, struct db_i *dbip)
Definition: search.c:2193
DEPRECATED struct bu_ptbl * db_search_unique_objects(void *searchplan, struct db_full_path_list *path_list, struct db_i *dbip)
Definition: search.c:2202
DEPRECATED int db_full_path_list_add(const char *path, int local, struct db_i *dbip, struct db_full_path_list *path_list)
Definition: search.c:2031
int db_search(struct bu_ptbl *results, int flags, const char *filter, int path_c, struct directory **path_v, struct db_i *dbip)
Search for objects in a geometry database using filters.
Definition: search.c:2232