OpenSRF/src/libstack/osrf_list.h

   1 #include <stdio.h>
   2 #include "opensrf/utils.h"
   3 #include <Judy.h>
   4
   5 /**
   6   Items are stored as void*'s so it's up to the user to
   7   manage the data wisely.  Also, if the 'freeItem' callback is defined for the list,
   8   then, it will be used on any item that needs to be freed, so don't mix data
   9   types in the list if you want magic freeing */
  10
  11 struct __osrfListStruct {
  12         Pvoid_t list;                                                   /* the list */
  13         int size;                                                               /* how many items in the list including NULL items between non-NULL items */
  14         void (*freeItem) (void* item);  /* callback for freeing stored items */
  15 };
  16 typedef struct __osrfListStruct osrfList;
  17
  18
  19 struct __osrfListIteratorStruct {
  20         osrfList* list;
  21         unsigned long current;
  22 };
  23 typedef struct __osrfListIteratorStruct osrfListIterator;
  24
  25
  26 /**
  27   Creates a new list iterator with the given list
  28   */
  29 osrfListIterator* osrfNewListIterator( osrfList* list );
  30
  31 /**
  32   Returns the next non-NULL item in the list, return NULL when
  33   the end of the list has been reached
  34   */
  35 void* osrfListIteratorNext( osrfListIterator* itr );
  36
  37 /**
  38   Deallocates the given list
  39   */
  40 void osrfListIteratorFree( osrfListIterator* itr );
  41
  42 void osrfListIteratorReset( osrfListIterator* itr );
  43
  44
  45 /**
  46   Allocates a new list
  47   @param compress If true, the list will compress empty slots on delete.  If item positionality
  48   is not important, then using this feature is reccomended to keep the list from growing indefinitely.
  49   if item positionality is not important.
  50   @return The allocated list
  51   */
  52 osrfList* osrfNewList();
  53
  54 /**
  55   Pushes an item onto the end of the list.  This always finds the highest index
  56   in the list and pushes the new item into the list after it.
  57   @param list The list
  58   @param item The item to push
  59   @return 0 on success, -1 on failure
  60   */
  61 int osrfListPush( osrfList* list, void* item );
  62
  63 /**
  64   Puts the given item into the list at the specified position.  If there
  65   is already an item at the given position and the list has it's
  66   "freeItem" function defined, then it will be used to free said item.
  67   If no 'freeItem' callback is defined, then the displaced item will
  68   be returned;
  69   @param list The list
  70   @param item The item to put into the list
  71   @param position The position to place the item in
  72   @return NULL in successfully inserting the new item and freeing
  73   any displaced items.  Returns the displaced item if no "freeItem"
  74   callback is defined.
  75         */
  76 void* osrfListSet( osrfList* list, void* item, unsigned long position );
  77
  78 /**
  79   Returns the item at the given position
  80   @param list The list
  81   @param postiont the position
  82   */
  83 void* osrfListGetIndex( osrfList* list, unsigned long  position );
  84
  85 /**
  86   Frees the list and all list items (if the list has a "freeItem" function defined )
  87   @param list The list
  88   */
  89 void osrfListFree( osrfList* list );
  90
  91 /**
  92   Removes the list item at the given index
  93   @param list The list
  94   @param position The position of the item to remove
  95   @return A pointer to the item removed if "freeItem" is not defined
  96   for this list, returns NULL if it is.
  97   */
  98 void* osrfListRemove( osrfList* list, int position );
  99
 100 /**
 101   Finds the list item whose void* is the same as the one passed in
 102   @param list The list
 103   @param addr The pointer connected to the list item we're to find
 104   @return the index of the item, or -1 if the item was not found
 105   */
 106 int osrfListFind( osrfList* list, void* addr );
 107
 108
 109 void __osrfListSetSize( osrfList* list );
 110
 111 /**
 112   @return The number of non-null items in the list
 113   */
 114 unsigned long osrfListGetCount( osrfList* list );
 115
 116