11.1 bnd_bsearch

binary search with bounding element return

Synopsis

     #include <suplib/lists.h>
     
     
     
     const void *bnd_bsearch(
       const void *key,
       const void *base,
       size_t n,
       size_t size,
       const void **lo_bnd,
       const void **hi_bnd,
       int (*cmp)(const void *keyval,const void *datum)
     );

Parameters

const void *key

a pointer to the comparison key

const void *base

the list of objects

size_t n

the number of objects in the list

size_t size

the size of an object in bytes

const void **lo_bnd

the address of a pointer which will be set to the address of the largest object lower than the key

const void **hi_bnd

the address of a pointer which will be set to the address of the smallest object higher than the key

int (*cmp)(const void *keyval,const void *datum)

a routine which compares the user supplied key to an object, returning <1, 0, or >1 if the key is respectively less than, equal to, or greater than the object

Description

bnd_bsearch performs a binary search upon a list of objects, returning the matching object or the bounding objects if the key is not found.

• If an object matches key, its address is returned and lo_bnd and hi_bnd are set to the address.
• If an object is not found, NULL is returned, and hi_bnd and lo_bnd are set as follows:
  • If key falls between two objects, lo_bnd and hi_bnd are set to the addresses of the bracketing objects.
  • If key is less than any object in the list, lo_bnd is set to NULL and hi_bnd is set to base.
  • If key is larger than any object in the list, lo_bnd is set to base + (n-1) and hi_bnd is set to NULL.

Warning

Note that while hi_bnd and lo_bnd are declared as void *, the calling routine must pass a pointer to a pointer!

Author

Diab Jerius