Tweaking comments for doxygen:
[OpenSRF.git] / include / opensrf / osrf_list.h
1 /**
2         @file osrf_list.h
3         @brief Header for osrfList, like a vector class in C
4
5         An osrfList manages an array of void pointers, allocating additional memory as
6         needed when the array needs to grow.  Optionally, it may call a designated callback
7         function as a destructor when one of the void pointers is removed, or when the
8         array itself is destroyed.
9
10         The callback function must be of type void and accept a void pointer as its parameter.
11         There is no specific function for installing or uninstalling such a callback; just assign
12         directly to the freeItem member of the osrfList structure.
13
14         Unlike a typical vector class in, or example, C++, an osrfList does NOT shift items
15         around to fill in the gap when you remove an item.  Items stay put.
16
17         The use of void pointers involves the usual risk of type errors, so be careful.
18
19         NULL pointers are a special case.  On the one hand an osrfList will happily store
20         a NULL if you ask it to.  On the other hand it may overwrite a NULL pointer previously
21         stored, treating it as disposable.  Conclusion: you can store NULLs in an osrfList, but
22         not safely, unless you are familiar with the internal details of the implementation and
23         work around them accordingly.
24  */
25
26 #ifndef OSRF_LIST_H
27 #define OSRF_LIST_H
28
29 #include <opensrf/utils.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /**
36         @brief Macro version of osrfListGetIndex().
37         @param l A pointer to the osrfList.
38         @param i The zero-based index of the requested pointer.
39 */
40 #define OSRF_LIST_GET_INDEX(l, i) (!(l) || (i) >= (l)->size) ? NULL: (l)->arrlist[(i)]
41
42 /**
43         @brief Structure for managing an array of pointers.
44 */
45 struct _osrfListStruct {
46         /** @brief How many slots are in use (possibly including some NULLs). */
47         unsigned int size;
48         /** @brief Callback function pointer for freeing stored items. */
49         void (*freeItem) (void* item);
50         /** @brief Pointer to array of void pointers. */
51         void** arrlist;
52         /** @brief Capacity of the currently allocated array. */
53         int arrsize;
54 };
55 typedef struct _osrfListStruct osrfList;
56
57
58 /**
59         @brief Iterator for traversing an osrfList.
60 */
61 struct _osrfListIteratorStruct {
62         /** @brief Pointer to the associated osrfList. */
63         const osrfList* list;
64         /** @brief Index of the next pointer to be returned by osrfListIteratorNext(). */
65         unsigned int current;
66 };
67 typedef struct _osrfListIteratorStruct osrfListIterator;
68
69 osrfList* osrfNewListSize( unsigned int size );
70
71 osrfListIterator* osrfNewListIterator( const osrfList* list );
72
73 void* osrfListIteratorNext( osrfListIterator* itr );
74
75 void osrfListIteratorFree( osrfListIterator* itr );
76
77 void osrfListIteratorReset( osrfListIterator* itr );
78
79 osrfList* osrfNewList();
80
81 int osrfListPush( osrfList* list, void* item );
82
83 void* osrfListPop( osrfList* list );
84
85 void* osrfListSet( osrfList* list, void* item, unsigned int position );
86
87 void* osrfListGetIndex( const osrfList* list, unsigned int  position );
88
89 void osrfListFree( osrfList* list );
90
91 void* osrfListRemove( osrfList* list, unsigned int position );
92
93 void* osrfListExtract( osrfList* list, unsigned int position );
94                 
95 int osrfListFind( const osrfList* list, void* addr );
96
97 unsigned int osrfListGetCount( const osrfList* list );
98
99 void osrfListSetDefaultFree( osrfList* list );
100
101 int osrfListPushFirst( osrfList* list, void* item );
102
103 #ifdef __cplusplus
104 }
105 #endif
106
107 #endif