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