Two patch sets from Scott McKellar
[OpenSRF.git] / 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