include/opensrf/osrf_list.h

   1 /**
   2         @file osrf_list.h
   3         @brief Header for osrfList, like a vector class in C
   4
   5         An osrfList manages an array of void pointers, allocating additional memory as
   6         needed when the array needs to grow.  Optionally, it may call a designated callback
   7         function as a destructor when one of the void pointers is removed, or when the
   8         array itself is destroyed.
   9
  10         The callback function must be of type void and accept a void pointer as its parameter.
  11         There is no specific function for installing or uninstalling such a callback; just assign
  12         directly to the freeItem member of the osrfList structure.
  13
  14         Unlike a typical vector class in, or example, C++, an osrfList does NOT shift items
  15         around to fill in the gap when you remove an item.  Items stay put.
  16
  17         The use of void pointers involves the usual risk of type errors, so be careful.
  18
  19         NULL pointers are a special case.  On the one hand an osrfList will happily store
  20         a NULL if you ask it to.  On the other hand it may overwrite a NULL pointer previously
  21         stored, treating it as disposable.  Conclusion: you can store NULLs in an osrfList, but
  22         not safely, unless you are familiar with the internal details of the implementation and
  23         work around them accordingly.
  24  */
  25
  26 #ifndef OSRF_LIST_H
  27 #define OSRF_LIST_H
  28
  29 #include <opensrf/utils.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36         @brief Macro version of osrfListGetIndex().
  37         @param l A pointer to the osrfList.
  38         @param i The zero-based index of the requested pointer.
  39 */
  40 #define OSRF_LIST_GET_INDEX(l, i) (!(l) || (i) >= (l)->size) ? NULL: (l)->arrlist[(i)]
  41
  42 /**
  43         @brief Structure for managing an array of pointers.
  44 */
  45 struct _osrfListStruct {
  46         /** @brief How many slots are in use (possibly including some NULLs). */
  47         unsigned int size;
  48         /** @brief Callback function pointer for freeing stored items. */
  49         void (*freeItem) (void* item);
  50         /** @brief Pointer to array of void pointers. */
  51         void** arrlist;
  52         /** @brief Capacity of the currently allocated array. */
  53         int arrsize;
  54 };
  55 typedef struct _osrfListStruct osrfList;
  56
  57
  58 /**
  59         @brief Iterator for traversing an osrfList.
  60 */
  61 struct _osrfListIteratorStruct {
  62         /** @brief Pointer to the associated osrfList. */
  63         const osrfList* list;
  64         /** @brief Index of the next pointer to be returned by osrfListIteratorNext(). */
  65         unsigned int current;
  66 };
  67 typedef struct _osrfListIteratorStruct osrfListIterator;
  68
  69 osrfList* osrfNewListSize( unsigned int size );
  70
  71 osrfListIterator* osrfNewListIterator( const osrfList* list );
  72
  73 void* osrfListIteratorNext( osrfListIterator* itr );
  74
  75 void osrfListIteratorFree( osrfListIterator* itr );
  76
  77 void osrfListIteratorReset( osrfListIterator* itr );
  78
  79 osrfList* osrfNewList();
  80
  81 int osrfListPush( osrfList* list, void* item );
  82
  83 void* osrfListPop( osrfList* list );
  84
  85 void* osrfListSet( osrfList* list, void* item, unsigned int position );
  86
  87 void* osrfListGetIndex( const osrfList* list, unsigned int  position );
  88
  89 void osrfListFree( osrfList* list );
  90
  91 void* osrfListRemove( osrfList* list, unsigned int position );
  92
  93 void* osrfListExtract( osrfList* list, unsigned int position );
  94
  95 int osrfListFind( const osrfList* list, void* addr );
  96
  97 unsigned int osrfListGetCount( const osrfList* list );
  98
  99 void osrfListSetDefaultFree( osrfList* list );
 100
 101 int osrfListPushFirst( osrfList* list, void* item );
 102
 103 #ifdef __cplusplus
 104 }
 105 #endif
 106
 107 #endif