include/opensrf/osrf_list.h

   1 #ifndef OSRF_LIST_H
   2 #define OSRF_LIST_H
   3
   4 #include <opensrf/utils.h>
   5
   6 #define OSRF_LIST_GET_INDEX(l, i) (!l || i >= l->size) ? NULL: l->arrlist[i]
   7
   8 /**
   9   Items are stored as void*'s so it's up to the user to
  10   manage the data wisely.  Also, if the 'freeItem' callback is defined for the list,
  11   then, it will be used on any item that needs to be freed, so don't mix data
  12   types in the list if you want magic freeing */
  13
  14 struct _osrfListStruct {
  15         unsigned int size;                      /* how many items in the list including NULL items between non-NULL items */
  16         void (*freeItem) (void* item);  /* callback for freeing stored items */
  17         void** arrlist;
  18         int arrsize; /* how big is the currently allocated array */
  19 };
  20 typedef struct _osrfListStruct osrfList;
  21
  22
  23 struct _osrfListIteratorStruct {
  24         const osrfList* list;
  25         unsigned int current;
  26 };
  27 typedef struct _osrfListIteratorStruct osrfListIterator;
  28
  29 osrfList* osrfNewListSize( unsigned int size );
  30
  31
  32 /**
  33   Creates a new list iterator with the given list
  34   */
  35 osrfListIterator* osrfNewListIterator( const osrfList* list );
  36
  37 /**
  38   Returns the next non-NULL item in the list, return NULL when
  39   the end of the list has been reached
  40   */
  41 void* osrfListIteratorNext( osrfListIterator* itr );
  42
  43 /**
  44   Deallocates the given list
  45   */
  46 void osrfListIteratorFree( osrfListIterator* itr );
  47
  48 void osrfListIteratorReset( osrfListIterator* itr );
  49
  50
  51 /**
  52   Allocates a new list
  53   @return The allocated list
  54   */
  55 osrfList* osrfNewList();
  56
  57 /**
  58   Pushes an item onto the end of the list.  This always finds the highest index
  59   in the list and pushes the new item into the list after it.
  60   @param list The list
  61   @param item The item to push
  62   @return 0 on success, -1 on failure
  63   */
  64 int osrfListPush( osrfList* list, void* item );
  65
  66
  67 /**
  68  * Removes the last item in the list
  69  * See osrfListRemove for details on how the removed item is handled
  70  * @return The item, unless 'freeItem' exists, then returns NULL
  71  */
  72 void* osrfListPop( osrfList* list );
  73
  74 /**
  75   Puts the given item into the list at the specified position.  If there
  76   is already an item at the given position and the list has its
  77   "freeItem" function defined, then it will be used to free said item.
  78   If no 'freeItem' callback is defined, then the displaced item will
  79   be returned;
  80   @param list The list
  81   @param item The item to put into the list
  82   @param position The position to place the item in
  83   @return NULL in successfully inserting the new item and freeing
  84   any displaced items.  Returns the displaced item if no "freeItem"
  85   callback is defined.
  86         */
  87 void* osrfListSet( osrfList* list, void* item, unsigned int position );
  88
  89 /**
  90   Returns the item at the given position
  91   @param list The list
  92   @param postiont the position
  93   */
  94 void* osrfListGetIndex( const osrfList* list, unsigned int  position );
  95
  96 /**
  97   Frees the list and all list items (if the list has a "freeItem" function defined )
  98   @param list The list
  99   */
 100 void osrfListFree( osrfList* list );
 101
 102 /**
 103   Removes the list item at the given index
 104   @param list The list
 105   @param position The position of the item to remove
 106   @return A pointer to the item removed if "freeItem" is not defined
 107   for this list, returns NULL if it is.
 108   */
 109 void* osrfListRemove( osrfList* list, unsigned int position );
 110
 111 /**
 112   Finds the list item whose void* is the same as the one passed in
 113   @param list The list
 114   @param addr The pointer connected to the list item we're to find
 115   @return the index of the item, or -1 if the item was not found
 116   */
 117 int osrfListFind( const osrfList* list, void* addr );
 118
 119 /**
 120   @return The number of non-null items in the list
 121   */
 122 unsigned int osrfListGetCount( const osrfList* list );
 123
 124 /**
 125  * May be used as a default memory freeing call
 126  * Just calls free() on list items
 127  */
 128 void osrfListVanillaFree( void* item );
 129
 130 /**
 131  * Tells the list to just call 'free()' on each item when
 132  * an item or the whole list is destroyed
 133  */
 134 void osrfListSetDefaultFree( osrfList* list );
 135
 136 /**
 137  * Inserts the new item at the first free (null) slot
 138  * in the array.  Item is shoved onto the end of the
 139  * list if there are no null slots */
 140 int osrfListPushFirst( osrfList* list, void* item );
 141
 142
 143 #endif