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