include/pnd_container.h

   1
   2 #ifndef h_pnd_container_h
   3 #define h_pnd_container_h
   4
   5 #ifdef __cplusplus
   6 extern "C" {
   7 #endif
   8
   9 // this interface defines a simple container for storing unsorted data; it is likely to just be
  10 // the worst linked list you've ever seen, but could be changed later and applications should only
  11 // need a recompile
  12
  13 // this simple 'Box' (shorter to type) container is not intended to be super efficient or highly usable
  14 // and as such does not include delete-node functionality or othe useful APIs, nor internal data to
  15 // support such operatins yet. Should performance become important, a hash or somesuch might be
  16 // needing implementing.
  17
  18 // The user may have a payload of a simple char*string, or a struct, or whatever they choose to stuff
  19 // in there.
  20
  21 typedef void* pnd_box_handle;
  22
  23 /* return a new container with no contained nodes.
  24  * Returns NULL on failure.
  25  */
  26 pnd_box_handle pnd_box_new ( char *name );
  27
  28 /* delete the container and all of its contents. Note that of course you have to free up any memory
  29  * referred to in advance of this operation, lest there be leaks!
  30  * Assume success always (ie: the container is either destroyed or indeterminate after.)
  31  */
  32 void pnd_box_delete ( pnd_box_handle box );
  33
  34 /* allocinsert() is used to allocate a new entry in the container of the specified size; ie:
  35  * the 'key' is a regular char* string; the 'size' refers to the requested size of the payload
  36  * you need, not the size of the key.
  37  * Returns a new payload pointer of the requested size, or NULL. Do not free this payload pointer
  38  * ever by hand.
  39  */
  40 void *pnd_box_allocinsert ( pnd_box_handle box, char *key, unsigned int size );
  41
  42 /* use find_by_key() to find a value or iteration, and unlink it */
  43 void pnd_box_delete_node ( pnd_box_handle box, void *value );
  44
  45 /* find_by_key() will attempt to locate a payload based on the specified key.
  46  * Returns the payload pointer or NULL if not found.
  47  * CASE INSENSITIVE.
  48  */
  49 void *pnd_box_find_by_key ( pnd_box_handle box, char *key );
  50
  51 /* merge two box lists */
  52 unsigned char pnd_box_append ( pnd_box_handle box, pnd_box_handle append );
  53
  54 /* should the user want to walk around the container, a couple basic functions are
  55  * provided.
  56  */
  57 char *pnd_box_get_name ( pnd_box_handle box );
  58 void *pnd_box_get_head ( pnd_box_handle box );
  59 char *pnd_box_get_key ( void *node );
  60 void *pnd_box_get_next ( void *node );
  61 unsigned int pnd_box_get_size ( pnd_box_handle box );
  62
  63 #ifdef __cplusplus
  64 } /* "C" */
  65 #endif
  66
  67 #endif