Database Searching

Routines that find and report on the objects within BRL-CAD geometry databases. More...

Collaboration diagram for Database Searching:

Files
file	search.h

Data Structures
struct	db_search_context

Macros
#define	DB_SEARCH_TREE   0x0
	Do a hierarchy-aware search. This is the default.
#define	DB_SEARCH_FLAT   0x1
	Do a flat search without hierarchy.
#define	DB_SEARCH_HIDDEN   0x2
	Search using hidden objects.
#define	DB_SEARCH_RETURN_UNIQ_DP   0x4
	Return the set of unique directory pointers instead of full paths.
#define	DB_SEARCH_QUIET   0x8
	Silence all warnings.
#define	DB_SEARCH_PRINT_TOTAL   0x10
	Print total number of items found in search.
#define	DB_LS_PRIM   0x1
	filter for primitives (solids)
#define	DB_LS_COMB   0x2
	filter for combinations
#define	DB_LS_REGION   0x4
	filter for regions
#define	DB_LS_HIDDEN   0x8
	include hidden objects in results
#define	DB_LS_NON_GEOM   0x10
	filter for non-geometry objects
#define	DB_LS_TOPS   0x20
	filter for objects un-referenced by other objects
#define	DB_LS_CYCLIC   0x40
	filter for objects with a cyclic reference in subtrees
#define	DB_LS_PHONY   0x80
	enable and filter for objects such as the nirt display list entries

Typedefs
typedef int(*	db_search_callback_t) (int, const char *[], void *)

Functions
int	db_search (struct bu_ptbl *results, int flags, const char *filter, int path_c, struct directory **path_v, struct db_i *dbip, bu_clbk_t clbk, void *u1, void *u2)
	Search for objects in a geometry database using filters.
void	db_search_free (struct bu_ptbl *search_results)
size_t	db_ls (const struct db_i *dbip, int flags, const char *pattern, struct directory ***dpv)
int	db_cyclic_paths (struct bu_ptbl *cyclic_paths, const struct db_i *dbip, struct directory *sdp)
struct db_search_context *	db_search_context_create (void)
void	db_search_context_destroy (struct db_search_context *ctx)
void	db_search_register_exec (struct db_search_context *, db_search_callback_t)
void	db_search_register_data (struct db_search_context *, void *)
int	db_search_old (struct bu_ptbl *results, int flags, const char *filter, int path_c, struct directory **path_v, struct db_i *dbip, struct db_search_context *ctx)

Detailed Description

Routines that find and report on the objects within BRL-CAD geometry databases.

Functionality for searching .g files.

Macro Definition Documentation

DB_SEARCH_TREE

#define DB_SEARCH_TREE   0x0

Do a hierarchy-aware search. This is the default.

Definition at line 121 of file search.h.

DB_SEARCH_FLAT

#define DB_SEARCH_FLAT   0x1

Do a flat search without hierarchy.

Definition at line 122 of file search.h.

DB_SEARCH_HIDDEN

#define DB_SEARCH_HIDDEN   0x2

Search using hidden objects.

Definition at line 123 of file search.h.

DB_SEARCH_RETURN_UNIQ_DP

#define DB_SEARCH_RETURN_UNIQ_DP   0x4

Return the set of unique directory pointers instead of full paths.

Definition at line 124 of file search.h.

DB_SEARCH_QUIET

#define DB_SEARCH_QUIET   0x8

Silence all warnings.

Definition at line 125 of file search.h.

DB_SEARCH_PRINT_TOTAL

#define DB_SEARCH_PRINT_TOTAL   0x10

Print total number of items found in search.

Definition at line 126 of file search.h.

DB_LS_PRIM

#define DB_LS_PRIM   0x1

filter for primitives (solids)

Definition at line 157 of file search.h.

DB_LS_COMB

#define DB_LS_COMB   0x2

filter for combinations

Definition at line 158 of file search.h.

DB_LS_REGION

#define DB_LS_REGION   0x4

filter for regions

Definition at line 159 of file search.h.

DB_LS_HIDDEN

#define DB_LS_HIDDEN   0x8

include hidden objects in results

Definition at line 160 of file search.h.

DB_LS_NON_GEOM

#define DB_LS_NON_GEOM   0x10

filter for non-geometry objects

Definition at line 161 of file search.h.

DB_LS_TOPS

#define DB_LS_TOPS   0x20

filter for objects un-referenced by other objects

Definition at line 162 of file search.h.

DB_LS_CYCLIC

#define DB_LS_CYCLIC   0x40

filter for objects with a cyclic reference in subtrees

Definition at line 163 of file search.h.

DB_LS_PHONY

#define DB_LS_PHONY   0x80

enable and filter for objects such as the nirt display list entries

Definition at line 164 of file search.h.

Typedef Documentation

db_search_callback_t

typedef int(* db_search_callback_t) (int, const char *[], void *)

Definition at line 190 of file search.h.

Function Documentation

db_search()

int db_search ( struct bu_ptbl *  results, int  flags, const char *  filter, int  path_c, struct directory **  path_v, struct db_i *  dbip, bu_clbk_t  clbk, void *  u1, void *  u2  )

extern

Search for objects in a geometry database using filters.

The db_search function is a programmatic find-style interface that lets you search for objects in a geometry database. This function searches the database using a supplied list of filter criteria.

The function returns a count of objects matching the filter criteria and can provide the resulting matches in binary format as either db_full_path or directory objects depending on the flags (i.e., depending on whether this is a flat or hierarchical search).

There are a LOT of filter possibilities. See the search(n) manual page for details.

Parameters

[out]	results	is a bu_ptbl holding either db_full_path or directory pointers.
	flags	is a bit field for setting various search options.
	filter	is a string defining search filters to be used.
	path_c	is the count of directory paths to be searched.
	path_v	is one or more directory paths to be searched. If path_v itself is NULL, all top-level objects are searched
	dbip	The database instance pointer corresponding to the current geometry database.
	clbk	Optional callback function to call for -exec
	u1	Optional user data pointer
	u2	Optional user data pointer

Returns

Negative return values indicate a problem with the search, and non-negative values indicate a successful search. Non-negative values correspond with the number of objects found.

Return values

-2	Return code when db_search is called with a NULL dbip.
-1	Return code when the plan search string is invalid.
0	Return code when the search completed successfully but no matches were found.
>0	Return code when the search completed successfully and matched one or more objects.

The following example assumes a database instance pointer (dbip) is available and ready to use.

size_t i = 0;
struct bu_ptbl results = BU_PTBL_INIT_ZERO;
const char *plan = "-name *.s -or -below -type region";
int matches = db_search(&results, DB_SEARCH_HIDDEN | DB_SEARCH_QUIET , plan, 0, NULL, dbip, ctx);
for (i = 0; matches > 0 && i < BU_PTBL_LEN(&results); i++) {
  char *path_str = db_path_to_string((struct db_full_path *)BU_PTBL_GET(&results, i));
  bu_log("%s\n", path_str);
  bu_free(path_str, "free db_fullpath_to_string allocation");
}
db_search_free(&results);

Note: Be aware that if you are using db_search to filter pre-built lists of paths, you need to check that your generated path list is NOT empty before calling db_search. If you accidentally send an empty path list into db_search, it will assume you wanted a tops list, which has a good chance of returning unwanted results.

db_search_free()

void db_search_free ( struct bu_ptbl *  search_results )

extern

Properly free the table contents returned by db_search. The bu_ptbl itself, if not put on the stack, will need to be freed by the same calling function that allocated it.

db_ls()

size_t db_ls ( const struct db_i *  dbip, int  flags, const char *  pattern, struct directory ***  dpv  )

extern

db_ls takes a database instance pointer and assembles a directory pointer array of objects in the database according to a set of flags. An optional pattern can be supplied for match filtering via globbing rules (see bu_path_match()). If pattern is NULL, filtering is performed using only the flags.

The caller is responsible for freeing the array.

Returns - integer count of objects in dpv struct directory ** array of objects in dpv via argument

db_cyclic_paths()

int db_cyclic_paths ( struct bu_ptbl *  cyclic_paths, const struct db_i *  dbip, struct directory *  sdp  )

extern

db_cyclic_paths searches for cyclic paths in the database, either in all objects or checking whether a specific dp is cyclic within its subtree.

If sdp is NULL, ALL directory pointers in the database are checked. This is a complete validation of the whole .g file, and the only way to comprehensively search for any cyclic paths present. The return count will be the number of combs with a cyclic reference in their subtrees.

If sdp is non-NULL, the search will be limited to checking only the tree below sdp for a cyclic reference to sdp.

If a cyclic_paths is non-NULL it will be used to return db_fullpath entries for the cyclic paths found.

db_search_context_create()

struct db_search_context * db_search_context_create ( void  )

extern

db_search_context_destroy()

void db_search_context_destroy ( struct db_search_context *  ctx )

extern

db_search_register_exec()

void db_search_register_exec ( struct db_search_context *  , db_search_callback_t    )

extern

db_search_register_data()

void db_search_register_data ( struct db_search_context *  , void *    )

extern

db_search_old()

int db_search_old ( struct bu_ptbl *  results, int  flags, const char *  filter, int  path_c, struct directory **  path_v, struct db_i *  dbip, struct db_search_context *  ctx  )

extern