Annotation of embedaddon/strongswan/src/libstrongswan/collections/array.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (C) 2014 Tobias Brunner
3: * HSR Hochschule fuer Technik Rapperswil
4: *
5: * Copyright (C) 2013 Martin Willi
6: * Copyright (C) 2013 revosec AG
7: *
8: * This program is free software; you can redistribute it and/or modify it
9: * under the terms of the GNU General Public License as published by the
10: * Free Software Foundation; either version 2 of the License, or (at your
11: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12: *
13: * This program is distributed in the hope that it will be useful, but
14: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16: * for more details.
17: */
18:
19: /**
20: * @defgroup array array
21: * @{ @ingroup collections
22: */
23:
24: #ifndef ARRAY_H_
25: #define ARRAY_H_
26:
27: #include <collections/enumerator.h>
28:
29: /**
30: * Variable sized array with fixed size elements.
31: *
32: * An array is a primitive object with associated functions to avoid the
33: * overhead of an object with methods. It is efficient in memory usage, but
34: * less efficient than a linked list in manipulating elements.
35: */
36: typedef struct array_t array_t;
37:
38: typedef enum array_idx_t array_idx_t;
39:
40: /**
41: * Special array index values for insert/remove.
42: */
43: enum array_idx_t {
44: ARRAY_HEAD = 0,
45: ARRAY_TAIL = -1,
46: };
47:
48: /**
49: * Callback function invoked for each array element.
50: *
51: * Data is a pointer to the array element. If this is a pointer based array,
52: * (esize is zero), data is the pointer itself.
53: *
54: * @param data pointer to array data, or the pointer itself
55: * @param idx array index
56: * @param user user data passed with callback
57: */
58: typedef void (*array_callback_t)(void *data, int idx, void *user);
59:
60: /**
61: * Create a array instance.
62: *
63: * Elements get tight packed to each other. If any alignment is required, pass
64: * appropriate padding to each element. The reserved space does not affect
65: * array_count(), but just preallocates buffer space.
66: *
67: * @param esize element size for this array, use 0 for a pointer array
68: * @param reserve number of items to allocate space for
69: * @return array instance
70: */
71: array_t *array_create(u_int esize, uint8_t reserve);
72:
73: /**
74: * Get the number of elements currently in the array.
75: *
76: * @return number of elements
77: */
78: int array_count(array_t *array);
79:
80: /**
81: * Compress an array, remove unused head/tail space.
82: *
83: * @param array array to compress, or NULL
84: */
85: void array_compress(array_t *array);
86:
87: /**
88: * Create an enumerator over an array.
89: *
90: * The enumerator enumerates directly over the array element (pass a pointer to
91: * element types), unless the array is pointer based. If zero is passed as
92: * element size during construction, the enumerator enumerates over the
93: * dereferenced pointer values.
94: *
95: * @param array array to create enumerator for, or NULL
96: * @return enumerator, over elements or pointers
97: */
98: enumerator_t* array_create_enumerator(array_t *array);
99:
100: /**
101: * Remove an element at enumerator position.
102: *
103: * @warning For **value based** arrays don't use the pointer returned by
104: * enumerate() anymore after calling this function. For performance reasons
105: * that pointer will point to internal data structures that get modified when
106: * this function is called.
107: *
108: * @param array array to remove element in
109: * @param enumerator enumerator position, from array_create_enumerator()
110: */
111: void array_remove_at(array_t *array, enumerator_t *enumerator);
112:
113: /**
114: * Insert an element to an array.
115: *
116: * If the array is pointer based (esize = 0), the pointer itself is appended.
117: * Otherwise the element gets copied from the pointer.
118: * The idx must be either within array_count() or one above to append the item.
119: * Passing -1 has the same effect as passing array_count(), i.e. appends the
120: * item. It is always valid to pass idx 0 to prepend the item.
121: *
122: * @param array array to append element to
123: * @param idx index to insert item at
124: * @param data pointer to array element to copy
125: */
126: void array_insert(array_t *array, int idx, void *data);
127:
128: /**
129: * Create an pointer based array if it does not exist, insert pointer.
130: *
131: * This is a convenience function for insert a pointer and implicitly
132: * create a pointer based array if array is NULL. Array is set the the newly
133: * created array, if any.
134: *
135: * @param array pointer to array reference, potentially NULL
136: * @param idx index to insert item at
137: * @param ptr pointer to append
138: */
139: void array_insert_create(array_t **array, int idx, void *ptr);
140:
141: /**
142: * Create a value based array if it does not exist, insert value.
143: *
144: * This is a convenience function to insert a value and implicitly
145: * create a value based array if array is NULL. Array is set the the newly
146: * created array, if any.
147: *
148: * @param array pointer to array reference, potentially NULL
149: * @param esize element size of this array
150: * @param idx index to insert item at
151: * @param val pointer to value to insert
152: */
153: void array_insert_create_value(array_t **array, u_int esize,
154: int idx, void *val);
155:
156: /**
157: * Insert all items from an enumerator to an array.
158: *
159: * @param array array to add items to
160: * @param idx index to insert each item with
161: * @param enumerator enumerator over void*, gets destroyed
162: */
163: void array_insert_enumerator(array_t *array, int idx, enumerator_t *enumerator);
164:
165: /**
166: * Get an element from the array.
167: *
168: * If data is given, the element is copied to that position.
169: *
170: * @param array array to get element from, or NULL
171: * @param idx index of the item to get
172: * @param data data to copy element to, or NULL
173: * @return TRUE if idx valid and item returned
174: */
175: bool array_get(array_t *array, int idx, void *data);
176:
177: /**
178: * Remove an element from the array.
179: *
180: * If data is given, the element is copied to that position.
181: *
182: * @param array array to remove element from, or NULL
183: * @param idx index of the item to remove
184: * @param data data to copy element to, or NULL
185: * @return TRUE if idx existed and item removed
186: */
187: bool array_remove(array_t *array, int idx, void *data);
188:
189: /**
190: * Sort the array.
191: *
192: * The comparison function must return an integer less than, equal to, or
193: * greater than zero if the first argument is considered to be respectively less
194: * than, equal to, or greater than the second. If two elements compare as
195: * equal, their order in the sorted array is undefined.
196: *
197: * The comparison function receives pointers to the array elements (esize != 0)
198: * or the actual pointers (esize = 0). The third argument is the user data
199: * supplied to this function.
200: *
201: * @param array array to sort, or NULL
202: * @param cmp comparison function
203: * @param user user data to pass to comparison function
204: */
205: void array_sort(array_t *array, int (*cmp)(const void*,const void*,void*),
206: void *user);
207:
208: /**
209: * Binary search of a sorted array.
210: *
211: * The array should be sorted in ascending order according to the given
212: * comparison function.
213: *
214: * The comparison function must return an integer less than, equal to, or
215: * greater than zero if the first argument (the key) is considered to be
216: * respectively less than, equal to, or greater than the second.
217: *
218: * If there are multiple elements that match the key it is not specified which
219: * element is returned.
220: *
221: * The comparison function receives the key object and a pointer to an array
222: * element (esize != 0) or an actual pointer (esize = 0).
223: *
224: * @param array array to search, or NULL
225: * @param key key to search for
226: * @param cmp comparison function
227: * @param data data to copy element to, or NULL
228: * @return index of the element if found, -1 if not
229: */
230: int array_bsearch(array_t *array, const void *key,
231: int (*cmp)(const void*,const void*), void *data);
232:
233: /**
234: * Invoke a callback for all array members.
235: *
236: * @param array array to traverse, or NULL
237: * @param cb callback function to invoke each element with
238: * @param user user data to pass to callback
239: */
240: void array_invoke(array_t *array, array_callback_t cb, void *user);
241:
242: /**
243: * Invoke a method of each element defined with offset.
244: *
245: * @param array array to traverse, or NULL
246: * @param offset offset of element method, use offsetof()
247: */
248: void array_invoke_offset(array_t *array, size_t offset);
249:
250: /**
251: * Destroy an array.
252: *
253: * @param array array to destroy, or NULL
254: */
255: void array_destroy(array_t *array);
256:
257: /**
258: * Destroy an array, call a function to clean up all elements.
259: *
260: * @param array array to destroy, or NULL
261: * @param cb callback function to free element data
262: * @param user user data to pass to callback
263: */
264: void array_destroy_function(array_t *array, array_callback_t cb, void *user);
265:
266: /**
267: * Destroy an array, call element method defined with offset.
268: *
269: * @param array array to destroy, or NULL
270: * @param offset offset of element method, use offsetof()
271: */
272: void array_destroy_offset(array_t *array, size_t offset);
273:
274:
275: /**
276: * Required on some platforms to initialize thread local value to implement
277: * array_sort().
278: */
279: void arrays_init();
280:
281: /**
282: * Destroys the thread local value if required.
283: */
284: void arrays_deinit();
285:
286: #endif /** ARRAY_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to array.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / collections