4 #include <opensrf/utils.h>
6 #define OSRF_LIST_GET_INDEX(l, i) (!l || i >= l->size) ? NULL: l->arrlist[i]
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 */
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 */
18 int arrsize; /* how big is the currently allocated array */
20 typedef struct _osrfListStruct osrfList;
23 struct _osrfListIteratorStruct {
27 typedef struct _osrfListIteratorStruct osrfListIterator;
29 osrfList* osrfNewListSize( unsigned int size );
33 Creates a new list iterator with the given list
35 osrfListIterator* osrfNewListIterator( const osrfList* list );
38 Returns the next non-NULL item in the list, return NULL when
39 the end of the list has been reached
41 void* osrfListIteratorNext( osrfListIterator* itr );
44 Deallocates the given list
46 void osrfListIteratorFree( osrfListIterator* itr );
48 void osrfListIteratorReset( osrfListIterator* itr );
53 @return The allocated list
55 osrfList* osrfNewList();
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.
61 @param item The item to push
62 @return 0 on success, -1 on failure
64 int osrfListPush( osrfList* list, void* item );
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
72 void* osrfListPop( osrfList* list );
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
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"
87 void* osrfListSet( osrfList* list, void* item, unsigned int position );
90 Returns the item at the given position
92 @param postiont the position
94 void* osrfListGetIndex( const osrfList* list, unsigned int position );
97 Frees the list and all list items (if the list has a "freeItem" function defined )
100 void osrfListFree( osrfList* list );
103 Removes the list item at the given index
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.
109 void* osrfListRemove( osrfList* list, unsigned int position );
112 Finds the list item whose void* is the same as the one passed in
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
117 int osrfListFind( const osrfList* list, void* addr );
120 @return The number of non-null items in the list
122 unsigned int osrfListGetCount( const osrfList* list );
125 * May be used as a default memory freeing call
126 * Just calls free() on list items
128 void osrfListVanillaFree( void* item );
131 * Tells the list to just call 'free()' on each item when
132 * an item or the whole list is destroyed
134 void osrfListSetDefaultFree( osrfList* list );
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 );