BRL-CAD
Loading...
Searching...
No Matches
Files | Data Structures | Macros | Typedefs | Functions
Pointer Tables
libbu (Utility Functions) » Data Containers

Support for generalized "pointer tables", kept compactly in a dynamic array. More...

Collaboration diagram for Pointer Tables:

Files

file  ptbl.h
 

Data Structures

struct  bu_ptbl
 

Macros

#define BU_PTBL_NULL   ((struct bu_ptbl *)0)
 
#define BU_CK_PTBL(_p)   BU_CKMAG(_p, BU_PTBL_MAGIC, "bu_ptbl")
 
#define BU_PTBL_INIT(_p)
 
#define BU_PTBL_INIT_ZERO   { {BU_PTBL_MAGIC, BU_LIST_NULL, BU_LIST_NULL}, 0, 0, NULL }
 
#define BU_PTBL_IS_INITIALIZED(_p)   (((struct bu_ptbl *)(_p) != BU_PTBL_NULL) && LIKELY((_p)->l.magic == BU_PTBL_MAGIC))
 
#define BU_PTBL_LEN(ptbl)   (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->end:0)
 
#define BU_PTBL_TEST(ptbl)   (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->l.magic == BU_PTBL_MAGIC:0)
 
#define BU_PTBL_GET(ptbl, i)   ((ptbl)->buffer[(i)])
 
#define BU_PTBL_SET(ptbl, i, val)   ((ptbl)->buffer[(i)] = (long*)(val))
 
#define BU_PTBL_END(ptbl)   ((ptbl)->end)
 
#define BU_PTBL_BASEADDR(ptbl)   (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->buffer:NULL)
 
#define BU_PTBL_LASTADDR(ptbl)   (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->buffer + (ptbl)->end - 1:NULL)
 
#define BU_PTBL_FOR(ip, cast, ptbl)    ip = cast BU_PTBL_LASTADDR(ptbl); ip >= cast BU_PTBL_BASEADDR(ptbl); ip--
 

Typedefs

typedef struct bu_ptbl bu_ptbl_t
 

Functions

void bu_ptbl_init (struct bu_ptbl *b, size_t len, const char *str)
 
void bu_ptbl_reset (struct bu_ptbl *b)
 
size_t bu_ptbl_ins (struct bu_ptbl *b, long *p)
 
intmax_t bu_ptbl_locate (const struct bu_ptbl *b, const long *p)
 
void bu_ptbl_zero (struct bu_ptbl *b, const long *p)
 
intmax_t bu_ptbl_ins_unique (struct bu_ptbl *b, long *p)
 
size_t bu_ptbl_rm (struct bu_ptbl *b, const long *p)
 
void bu_ptbl_cat (struct bu_ptbl *dest, const struct bu_ptbl *src)
 
void bu_ptbl_cat_uniq (struct bu_ptbl *dest, const struct bu_ptbl *src)
 
void bu_ptbl_free (struct bu_ptbl *b)
 
void bu_pr_ptbl (const char *title, const struct bu_ptbl *tbl, int verbose)
 
void bu_ptbl_trunc (struct bu_ptbl *tbl, size_t end)
 

Detailed Description

Support for generalized "pointer tables", kept compactly in a dynamic array.

The table is currently un-ordered, and is merely an array of pointers. The support routines BU_*PTBL* and bu_ptbl* manipulate the array for you. Pointers to be operated on (inserted, deleted, searched for) are passed as a "pointer to long".

Macro Definition Documentation

◆ BU_PTBL_NULL

#define BU_PTBL_NULL   ((struct bu_ptbl *)0)

Definition at line 60 of file ptbl.h.

◆ BU_CK_PTBL

#define BU_CK_PTBL (   _p)    BU_CKMAG(_p, BU_PTBL_MAGIC, "bu_ptbl")

assert the integrity of a bu_ptbl struct pointer.

Definition at line 65 of file ptbl.h.

◆ BU_PTBL_INIT

#define BU_PTBL_INIT (   _p)
Value:
{ \
BU_LIST_INIT_MAGIC(&(_p)->l, BU_PTBL_MAGIC); \
(_p)->end = 0; \
(_p)->blen = 0; \
(_p)->buffer = NULL; \
}
dvec
Definition dvec.h:74
BU_PTBL_MAGIC
#define BU_PTBL_MAGIC
Definition magic.h:68

initialize a bu_ptbl struct without allocating any memory. this macro is not suitable for initializing a list head node.

Definition at line 71 of file ptbl.h.

◆ BU_PTBL_INIT_ZERO

#define BU_PTBL_INIT_ZERO   { {BU_PTBL_MAGIC, BU_LIST_NULL, BU_LIST_NULL}, 0, 0, NULL }

macro suitable for declaration statement initialization of a bu_ptbl struct. does not allocate memory. not suitable for initializing a list head node.

Definition at line 83 of file ptbl.h.

◆ BU_PTBL_IS_INITIALIZED

#define BU_PTBL_IS_INITIALIZED (   _p)    (((struct bu_ptbl *)(_p) != BU_PTBL_NULL) && LIKELY((_p)->l.magic == BU_PTBL_MAGIC))

returns truthfully whether a bu_ptbl has been initialized via BU_PTBL_INIT() or BU_PTBL_INIT_ZERO.

Definition at line 89 of file ptbl.h.

◆ BU_PTBL_LEN

#define BU_PTBL_LEN (   ptbl)    (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->end:0)

Definition at line 95 of file ptbl.h.

◆ BU_PTBL_TEST

#define BU_PTBL_TEST (   ptbl)    (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->l.magic == BU_PTBL_MAGIC:0)

Definition at line 96 of file ptbl.h.

◆ BU_PTBL_GET

#define BU_PTBL_GET (   ptbl,
  i 
)    ((ptbl)->buffer[(i)])

Definition at line 97 of file ptbl.h.

◆ BU_PTBL_SET

#define BU_PTBL_SET (   ptbl,
  i,
  val 
)    ((ptbl)->buffer[(i)] = (long*)(val))

Definition at line 98 of file ptbl.h.

◆ BU_PTBL_END

#define BU_PTBL_END (   ptbl)    ((ptbl)->end)

DEPRECATED

Definition at line 101 of file ptbl.h.

◆ BU_PTBL_BASEADDR

#define BU_PTBL_BASEADDR (   ptbl)    (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->buffer:NULL)

DEPRECATED

Definition at line 103 of file ptbl.h.

◆ BU_PTBL_LASTADDR

#define BU_PTBL_LASTADDR (   ptbl)    (((uintptr_t)(ptbl) != (uintptr_t)NULL)?(ptbl)->buffer + (ptbl)->end - 1:NULL)

DEPRECATED

Definition at line 105 of file ptbl.h.

◆ BU_PTBL_FOR

#define BU_PTBL_FOR (   ip,
  cast,
  ptbl 
)     ip = cast BU_PTBL_LASTADDR(ptbl); ip >= cast BU_PTBL_BASEADDR(ptbl); ip--

A handy way to visit all the elements of the table is:

struct edgeuse **eup; for (eup = (struct edgeuse **)BU_PTBL_LASTADDR(&eutab); eup >= (struct edgeuse **)BU_PTBL_BASEADDR(&eutab); eup–) { NMG_CK_EDGEUSE(*eup); } — OR — for (BU_PTBL_FOR(eup, (struct edgeuse **), &eutab)) { NMG_CK_EDGEUSE(*eup); }

Definition at line 119 of file ptbl.h.

Typedef Documentation

◆ bu_ptbl_t

typedef struct bu_ptbl bu_ptbl_t

Definition at line 59 of file ptbl.h.

Function Documentation

◆ bu_ptbl_init()

void bu_ptbl_init ( struct bu_ptbl *  b,
size_t  len,
const char *  str 
)
extern

This collection of routines implements a "pointer table" data structure providing a convenient mechanism for managing a collection of pointers to objects. This is useful where the size of the array is not known in advance and may change with time. It's convenient to be able to write code that can say "remember this object", and then later on iterate through the collection of remembered objects.

When combined with the concept of placing "magic numbers" as the first field of each data structure, the pointers to the objects become automatically typed. Initialize struct & get storage for table. Recommend 8 or 64 for initial len.

◆ bu_ptbl_reset()

void bu_ptbl_reset ( struct bu_ptbl *  b)
extern

Reset the table to have no elements, but retain any existing storage.

◆ bu_ptbl_ins()

size_t bu_ptbl_ins ( struct bu_ptbl *  b,
long *  p 
)
extern

Append/Insert a (long *) item to/into the table.

◆ bu_ptbl_locate()

intmax_t bu_ptbl_locate ( const struct bu_ptbl *  b,
const long *  p 
)
extern

locate a (long *) in an existing table

Returns
index of first matching element in array, if found
-1 if not found

We do this a great deal, so make it go as fast as possible. this is the biggest argument I can make for changing to an ordered list. Someday....

◆ bu_ptbl_zero()

void bu_ptbl_zero ( struct bu_ptbl *  b,
const long *  p 
)
extern

Set all occurrences of "p" in the table to zero. This is different than deleting them.

◆ bu_ptbl_ins_unique()

intmax_t bu_ptbl_ins_unique ( struct bu_ptbl *  b,
long *  p 
)
extern

Append item to table, if not already present. Unique insert.

Returns
index of first matching element in array, if found. (table unchanged)
-1 if table extended to hold new element

We do this a great deal, so make it go as fast as possible. this is the biggest argument I can make for changing to an ordered list. Someday....

◆ bu_ptbl_rm()

size_t bu_ptbl_rm ( struct bu_ptbl *  b,
const long *  p 
)
extern

Remove all occurrences of an item from a table

Returns
Number of copies of 'p' that were removed from the table.
0 if none found.

we go backwards down the table looking for occurrences of p to delete. We do it backwards to reduce the amount of data moved when there is more than one occurrence of p in the table. A pittance savings, unless you're doing a lot of it.

◆ bu_ptbl_cat()

void bu_ptbl_cat ( struct bu_ptbl *  dest,
const struct bu_ptbl *  src 
)
extern

Catenate one table onto end of another. There is no checking for duplication.

◆ bu_ptbl_cat_uniq()

void bu_ptbl_cat_uniq ( struct bu_ptbl *  dest,
const struct bu_ptbl *  src 
)
extern

Catenate one table onto end of another, ensuring that no entry is duplicated. Duplications between multiple items in 'src' are not caught. The search is a nasty n**2 one. The tables are expected to be short.

◆ bu_ptbl_free()

void bu_ptbl_free ( struct bu_ptbl *  b)
extern

Deallocate dynamic buffer associated with a table, and render this table unusable without a subsequent bu_ptbl_init().

◆ bu_pr_ptbl()

void bu_pr_ptbl ( const char *  title,
const struct bu_ptbl *  tbl,
int  verbose 
)
extern

Print a bu_ptbl array for inspection.

◆ bu_ptbl_trunc()

void bu_ptbl_trunc ( struct bu_ptbl *  tbl,
size_t  end 
)
extern

truncate a bu_ptbl to the specified size.