Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kArrayList.h
Go to the documentation of this file.
1 /**
2 * @file kArrayList.h
3 * @brief Declares the kArrayList class.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_ARRAY_LIST_H
11 #define K_API_ARRAY_LIST_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kArrayList
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a list implemented with a dynamic array.
23 *
24 * kArrayList represents a dynamic, array-based list of objects or values. The kArrayList constructor
25 * accepts a kType value that determines the type of items that will be stored in the list. The list will
26 * automatically grow as new items are added.
27 *
28 * @code
29 * kStatus ArrayListExample()
30 * {
31 * kArrayList list = kNULL;
32 * k32s values[] = { 1, 2, 3, 5, 7, 9 };
33 * kSize i;
34 *
35 * kTry
36 * {
37 * //create a list that can store 32-bit integers
38 * kTest(kArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL));
39 *
40 * //add some initial items to the list
41 * for (i = 0; i < kCountOf(values); ++i)
42 * {
43 * kTest(kArrayList_Add(list, &values[i]);
44 * }
45 *
46 * //print some information about the list and its items
47 * printf("Item type: %s\n", kType_Name(kArrayList_ItemType(list)));
48 * printf("Count: %u\n", (k32u) kArrayList_Count(list));
49 *
50 * for (i = 0; i < kArrayList_Count(list); ++i)
51 * {
52 * //the kArrayList_As_ macro can be used to get a list item and cast it to the desired type;
53 * //this is equivalent to *(k32s*)kArrayList_At(list, i);
54 * k32s value = kArrayList_As_(list, i, k32s);
55 *
56 * printf("Item %u: %d\n", (k32u)i, value);
57 * }
58 * }
59 * kFinally
60 * {
61 * kObject_Destroy(list);
62 *
63 * kEndFinally();
64 * }
65 *
66 * return kOK;
67 * }
68 *
69 * @endcode
70 *
71 * For lists that contain <em>objects</em> (e.g. kImage) as opposed to <em>values</em> (e.g. k32s), the objects
72 * are not automatically destroyed when the list is destroyed. To recursively destroy both the list and the
73 * list items, use kObject_Dispose.
74 */
75 //typedef kObject kArrayList; --forward-declared in kApiDef.x.h
76
77 /**
78 * Constructs a kArrayList object.
79 *
80 * @public @memberof kArrayList
81 * @param list Receives constructed list object.
82 * @param itemType Type of list element.
83 * @param initialCapacity Capacity initially reserved for list items.
84 * @param allocator Memory allocator (or kNULL for default).
85 * @return Operation status.
86 */
87 kFx(kStatus) kArrayList_Construct(kArrayList* list, kType itemType, kSize initialCapacity, kAlloc allocator);
88
89 /**
90 * Reallocates the list item buffer.
91 *
92 * @public @memberof kArrayList
93 * @param list List object.
94 * @param itemType Type of list element.
95 * @param initialCapacity Capacity initially reserved for list items.
96 * @return Operation status.
97 */
98 kFx(kStatus) kArrayList_Allocate(kArrayList list, kType itemType, kSize initialCapacity);
99
100 /**
101 * Attaches the list object to an external buffer.
102 *
103 * The list count is set to the same value as the list capacity argument.
104 *
105 * @public @memberof kArrayList
106 * @param list List object.
107 * @param items Item buffer.
108 * @param itemType Type of list element.
109 * @param capacity List capacity.
110 * @return Operation status.
111 */
112 kFx(kStatus) kArrayList_Attach(kArrayList list, void* items, kType itemType, kSize capacity);
113
114 /**
115 * Copies the specified items into the list, replacing existing contents.
116 *
117 * The list count is set to the value of the count argument.
118 *
119 * @public @memberof kArrayList
120 * @param list List object.
121 * @param items Item buffer.
122 * @param itemType Type of list element.
123 * @param count Count of list items.
124 * @return Operation status.
125 */
126 kFx(kStatus) kArrayList_Import(kArrayList list, const void* items, kType itemType, kSize count);
127
128 /**
129 * Appends the specified items to the list.
130 *
131 * @public @memberof kArrayList
132 * @param list List object.
133 * @param items Item buffer.
134 * @param count Count of list items.
135 * @return Operation status.
136 */
137 kFx(kStatus) kArrayList_Append(kArrayList list, const void* items, kSize count);
138
139 /**
140 * Performs a shallow copy of the source list.
141 *
142 * Source items are copied by value; if the source list contains objects, the object
143 * handles are copied but the objects are not cloned.
144 *
145 * @public @memberof kArrayList
146 * @param list List object.
147 * @param source Source list to be copied.
148 * @return Operation status.
149 */
150 kFx(kStatus) kArrayList_Assign(kArrayList list, kArrayList source);
151
152 /**
153 * Sets the count of list items to zero.
154 *
155 * @public @memberof kArrayList
156 * @param list List object.
157 * @return Operation status.
158 */
159 kFx(kStatus) kArrayList_Clear(kArrayList list);
160
161 /**
162 * Disposes any elements in the list and sets the count of list items to zero.
163 *
164 * @public @memberof kArrayList
165 * @param list List object.
166 * @return Operation status.
167 */
168 kFx(kStatus) kArrayList_Purge(kArrayList list);
169
170 /**
171 * Sets the memory for all list elements to zero.
172 *
173 * @public @memberof kArrayList
174 * @param list List object.
175 * @return Operation status.
176 */
177 kFx(kStatus) kArrayList_Zero(kArrayList list);
178
179 /**
180 * Adds the specified item to the end of the list.
181 *
182 * @public @memberof kArrayList
183 * @param list List object.
184 * @param item Pointer to item that will be copied (by value) into the list.
185 * @return Operation status.
186 */
187 kFx(kStatus) kArrayList_Add(kArrayList list, const void* item);
188
189 /**
190 * Inserts an item into the list at the specified position.
191 *
192 * Increases list capacity, if necessary.
193 *
194 * @public @memberof kArrayList
195 * @param list List object.
196 * @param before Item will be inserted before the item at this index.
197 * @param item Pointer to item that will be copied (by value) into the list.
198 * @return Operation status.
199 */
200 kFx(kStatus) kArrayList_Insert(kArrayList list, kSize before, const void* item);
201
202 /**
203 * Removes an item from the list at the specified index.
204 *
205 * @public @memberof kArrayList
206 * @param list List object.
207 * @param index Item at this index will be removed from the list.
208 * @param item Destination for the removed item (copied by value, can be null).
209 * @return Operation status.
210 */
211 kFx(kStatus) kArrayList_Remove(kArrayList list, kSize index, void* item);
212
213 /**
214 * Sets the value of an item.
215 *
216 * @public @memberof kArrayList
217 * @param list List object.
218 * @param index Item index.
219 * @param item Item that will be copied into the list.
220 * @return Operation status.
221 */
222 kFx(kStatus) kArrayList_SetItem(kArrayList list, kSize index, const void* item);
223
224 /**
225 * Gets the value of an item.
226 *
227 * @public @memberof kArrayList
228 * @param list List object.
229 * @param index Item index.
230 * @param item Destination for item that will be copied (by value) from the list.
231 * @return Operation status.
232 */
233 kFx(kStatus) kArrayList_Item(kArrayList list, kSize index, void* item);
234
235 /**
236 * Sets the current count of list items to the specified value.
237 *
238 * Increases list capacity if necessary; existing list items are preserved.
239 *
240 * @public @memberof kArrayList
241 * @param list List object.
242 * @param count List size, in items.
243 * @return Operation status.
244 */
245 kFx(kStatus) kArrayList_Resize(kArrayList list, kSize count);
246
247 /**
248 * Increases the list count by the specified amount.
249 *
250 * Increases list capacity if necessary; existing list items are preserved.
251 * New items are not initialized.
252 *
253 * @public @memberof kArrayList
254 * @param list List object.
255 * @param count Amount to add to the existing count.
256 * @return Operation status.
257 */
258 kFx(kStatus) kArrayList_AddCount(kArrayList list, kSize count);
259
260 /**
261 * Decreases the list count by the specified amount.
262 *
263 * @public @memberof kArrayList
264 * @param list List object.
265 * @param count Amount to remove from the existing count.
266 * @return Operation status.
267 */
268 kFx(kStatus) kArrayList_RemoveCount(kArrayList list, kSize count);
269
270 /**
271 * Ensures that capacity is reserved for at least the specified number of list items.
272 *
273 * Existing list items are preserved.
274 *
275 * @public @memberof kArrayList
276 * @param list List object.
277 * @param capacity List capacity, in items.
278 * @return Operation status.
279 */
280 kFx(kStatus) kArrayList_Reserve(kArrayList list, kSize capacity);
281
282 /**
283 * Returns a pointer to the list item buffer.
284 *
285 * @public @memberof kArrayList
286 * @param list List object.
287 * @return Pointer to list items.
288 */
289 kFx(void*) kArrayList_Data(kArrayList list);
290
291 /**
292 * Returns the total size of list data (Count x ItemSize), in bytes.
293 *
294 * @public @memberof kArrayList
295 * @param list List object.
296 * @return Data size, in bytes.
297 */
298 kFx(kSize) kArrayList_DataSize(kArrayList list);
299
300 /**
301 * Returns a pointer to the specified item in the list buffer.
302 *
303 * @public @memberof kArrayList
304 * @param list List object.
305 * @param index Item index.
306 * @return Pointer to list element.
307 */
308 kFx(void*) kArrayList_At(kArrayList list, kSize index);
309
310 /**
311 * Returns the list element type.
312 *
313 * @public @memberof kArrayList
314 * @param list List object.
315 * @return Item type.
316 */
317 kFx(kType) kArrayList_ItemType(kArrayList list);
318
319 /**
320 * Returns the list element size.
321 *
322 * @public @memberof kArrayList
323 * @param list List object.
324 * @return Item size, in bytes.
325 */
326 kFx(kSize) kArrayList_ItemSize(kArrayList list);
327
328 /**
329 * Returns the current count of items in the list.
330 *
331 * @public @memberof kArrayList
332 * @param list List object.
333 * @return Current count of items.
334 */
335 kFx(kSize) kArrayList_Count(kArrayList list);
336
337 /**
338 * Returns the number of elements for which space has been allocated.
339 *
340 * @public @memberof kArrayList
341 * @param list List object.
342 * @return List capacity.
343 */
344 kFx(kSize) kArrayList_Capacity(kArrayList list);
345
346 #define kArrayList_AddCount_(LIST, C) kxArrayList_AddCount_(LIST, C) ///< Macro version of kArrayList_AddCount.
347 #define kArrayList_RemoveCount_(LIST, C) kxArrayList_RemoveCount_(LIST, C) ///< Macro version of kArrayList_RemoveCount.
348 #define kArrayList_Clear_(LIST) kxArrayList_Clear_(LIST) ///< Macro version of kArrayList_Clear.
349
350 #define kArrayList_ItemType_(LIST) kxArrayList_ItemType_(LIST) ///< Macro version of kArrayList_ItemType.
351 #define kArrayList_ItemSize_(LIST) kxArrayList_ItemSize_(LIST) ///< Macro version of kArrayList_ItemSize.
352 #define kArrayList_Count_(LIST) kxArrayList_Count_(LIST) ///< Macro version of kArrayList_Count.
353 #define kArrayList_Capacity_(LIST) kxArrayList_Capacity_(LIST) ///< Macro version of kArrayList_Capacity.
354
355 #define kArrayList_Data_(LIST) kxArrayList_Data_(LIST) ///< Macro version of kArrayList_Data.
356 #define kArrayList_DataSize_(LIST) kxArrayList_DataSize_(LIST) ///< Macro version of kArrayList_DataSize.
357
358 #define kArrayList_At_(LIST, INDEX) kxArrayList_At_(LIST, INDEX) ///< Macro version of kArrayList_At.
359
360 #define kArrayList_First_(LIST) kxArrayList_First_(LIST) ///< Gets a pointer to the first item.
361 #define kArrayList_Last_(LIST) kxArrayList_Last_(LIST) ///< Gets a pointer to the last item.
362
363 #define kArrayList_Begin_(LIST) kxArrayList_Begin_(LIST) ///< Gets a pointer to the first item.
364 #define kArrayList_End_(LIST) kxArrayList_End_(LIST) ///< Gets a pointer to one past the last item.
365
366 #define kArrayList_RBegin_(LIST) kxArrayList_RBegin_(LIST) ///< Gets a pointer to the last item.
367 #define kArrayList_REnd_(LIST) kxArrayList_REnd_(LIST) ///< Gets a pointer to one before the first item.
368
369 #define kArrayList_As_(LIST, INDEX, TYPE) kxArrayList_As_(LIST, INDEX, TYPE) ///< Gets an item pointer and casts to the specified type.
370
371 kEndHeader()
372
373 #include <kApi/Data/kArrayList.x.h>
374
375 #endif
kArrayList::kArrayList_Construct
kStatus kArrayList_Construct(kArrayList *list, kType itemType, kSize initialCapacity, kAlloc allocator)
Constructs a kArrayList object.
kArrayList::kArrayList_Item
kStatus kArrayList_Item(kArrayList list, kSize index, void *item)
Gets the value of an item.
kArrayList::kArrayList_SetItem
kStatus kArrayList_SetItem(kArrayList list, kSize index, const void *item)
Sets the value of an item.
kArrayList::kArrayList_Attach
kStatus kArrayList_Attach(kArrayList list, void *items, kType itemType, kSize capacity)
Attaches the list object to an external buffer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kArrayList::kArrayList_Capacity
kSize kArrayList_Capacity(kArrayList list)
Returns the number of elements for which space has been allocated.
kArrayList::kArrayList_DataSize
kSize kArrayList_DataSize(kArrayList list)
Returns the total size of list data (Count x ItemSize), in bytes.
kArrayList::kArrayList_Purge
kStatus kArrayList_Purge(kArrayList list)
Disposes any elements in the list and sets the count of list items to zero.
kArrayList::kArrayList_Data
void * kArrayList_Data(kArrayList list)
Returns a pointer to the list item buffer.
kArrayList::kArrayList_Count
kSize kArrayList_Count(kArrayList list)
Returns the current count of items in the list.
kArrayList::kArrayList_AddCount
kStatus kArrayList_AddCount(kArrayList list, kSize count)
Increases the list count by the specified amount.
kArrayList::kArrayList_Add
kStatus kArrayList_Add(kArrayList list, const void *item)
Adds the specified item to the end of the list.
kArrayList::kArrayList_ItemSize
kSize kArrayList_ItemSize(kArrayList list)
Returns the list element size.
kArrayList::kArrayList_Remove
kStatus kArrayList_Remove(kArrayList list, kSize index, void *item)
Removes an item from the list at the specified index.
kArrayList::kArrayList_At
void * kArrayList_At(kArrayList list, kSize index)
Returns a pointer to the specified item in the list buffer.
kArrayList::kArrayList_ItemType
kType kArrayList_ItemType(kArrayList list)
Returns the list element type.
kArrayList::kArrayList_Zero
kStatus kArrayList_Zero(kArrayList list)
Sets the memory for all list elements to zero.
kArrayList::kArrayList_Import
kStatus kArrayList_Import(kArrayList list, const void *items, kType itemType, kSize count)
Copies the specified items into the list, replacing existing contents.
kApiDef.h
Essential API declarations.
kArrayList::kArrayList_Resize
kStatus kArrayList_Resize(kArrayList list, kSize count)
Sets the current count of list items to the specified value.
kArrayList::kArrayList_Assign
kStatus kArrayList_Assign(kArrayList list, kArrayList source)
Performs a shallow copy of the source list.
kType
Represents metadata about a type (class, interface, or value).
kArrayList
Represents a list implemented with a dynamic array.
kArrayList::kArrayList_Reserve
kStatus kArrayList_Reserve(kArrayList list, kSize capacity)
Ensures that capacity is reserved for at least the specified number of list items.
kArrayList::kArrayList_Allocate
kStatus kArrayList_Allocate(kArrayList list, kType itemType, kSize initialCapacity)
Reallocates the list item buffer.
kStatus
Represents an enumeration of error codes.
kArrayList::kArrayList_RemoveCount
kStatus kArrayList_RemoveCount(kArrayList list, kSize count)
Decreases the list count by the specified amount.
kArrayList::kArrayList_Insert
kStatus kArrayList_Insert(kArrayList list, kSize before, const void *item)
Inserts an item into the list at the specified position.
kArrayList::kArrayList_Append
kStatus kArrayList_Append(kArrayList list, const void *items, kSize count)
Appends the specified items to the list.
kArrayList::kArrayList_Clear
kStatus kArrayList_Clear(kArrayList list)
Sets the count of list items to zero.