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
	Execution context for the -exec filter. More...

Macros
#define	DB_SEARCH_TREE 0x0
	Do a hierarchy-aware search. This is the default. More...

#define	DB_SEARCH_FLAT 0x1
	Do a flat search without hierarchy. More...

#define	DB_SEARCH_HIDDEN 0x2
	Search using hidden objects. More...

#define	DB_SEARCH_RETURN_UNIQ_DP 0x4
	Return the set of unique directory pointers instead of full paths. More...

#define	DB_SEARCH_QUIET 0x8
	Silence all warnings. More...

#define	DB_LS_PRIM 0x1
	filter for primitives (solids) More...

#define	DB_LS_COMB 0x2
	filter for combinations More...

#define	DB_LS_REGION 0x4
	filter for regions More...

#define	DB_LS_HIDDEN 0x8
	include hidden objects in results More...

#define	DB_LS_NON_GEOM 0x10
	filter for non-geometry objects More...

#define	DB_LS_TOPS 0x20
	filter for objects un-referenced by other objects More...

#define	DB_LS_CYCLIC 0x40
	filter for objects with a cyclic reference in subtrees More...

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

Functions
struct db_search_context *	db_search_context_create (void)
	Allocates a new context. More...

void	db_search_context_destroy (struct db_search_context *ctx)
	Free a context created by db_search_context_create. More...

void	db_search_register_exec (struct db_search_context *, db_search_callback_t)
	Register a callback for -exec filters. More...

void	db_search_register_data (struct db_search_context , void )
	Register a userdata for the callback. More...

int	db_search (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)
	Search for objects in a geometry database using filters. More...

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)

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 146 of file search.h.

◆ DB_SEARCH_FLAT

#define DB_SEARCH_FLAT 0x1

Do a flat search without hierarchy.

Definition at line 147 of file search.h.

◆ DB_SEARCH_HIDDEN

#define DB_SEARCH_HIDDEN 0x2

Search using hidden objects.

Definition at line 148 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 149 of file search.h.

◆ DB_SEARCH_QUIET

#define DB_SEARCH_QUIET 0x8

Silence all warnings.

Definition at line 150 of file search.h.

◆ DB_LS_PRIM

#define DB_LS_PRIM 0x1

filter for primitives (solids)

Definition at line 181 of file search.h.

◆ DB_LS_COMB

#define DB_LS_COMB 0x2

filter for combinations

Definition at line 182 of file search.h.

◆ DB_LS_REGION

#define DB_LS_REGION 0x4

filter for regions

Definition at line 183 of file search.h.

◆ DB_LS_HIDDEN

#define DB_LS_HIDDEN 0x8

include hidden objects in results

Definition at line 184 of file search.h.

◆ DB_LS_NON_GEOM

#define DB_LS_NON_GEOM 0x10

filter for non-geometry objects

Definition at line 185 of file search.h.

◆ DB_LS_TOPS

#define DB_LS_TOPS 0x20

filter for objects un-referenced by other objects

Definition at line 186 of file search.h.

◆ DB_LS_CYCLIC

#define DB_LS_CYCLIC 0x40

filter for objects with a cyclic reference in subtrees

Definition at line 187 of file search.h.

Typedef Documentation

◆ db_search_callback_t

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

Definition at line 40 of file search.h.

Function Documentation

◆ db_search_context_create()

struct db_search_context * db_search_context_create ( void )

Allocates a new context.

◆ db_search_context_destroy()

void db_search_context_destroy ( struct db_search_context * ctx )

Free a context created by db_search_context_create.

◆ db_search_register_exec()

void db_search_register_exec	(	struct db_search_context *	,
		db_search_callback_t
	)

Register a callback for -exec filters.

◆ db_search_register_data()

void db_search_register_data	(	struct db_search_context *	,
		void *
	)

Register a userdata for the callback.

◆ 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,
		struct db_search_context *	ctx
	)

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.
	ctx	Context for -exec. Can be NULL if there are no -exec filters present.

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 )

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
	)

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
	)

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.

Files

Data Structures

Macros

Typedefs

Functions