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