Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kList.h
Go to the documentation of this file.
1 /**
2 * @file kList.h
3 * @brief Declares the kList class.
4 *
5 * @internal
6 * Copyright (C) 2013-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_LIST_H
11 #define K_API_LIST_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kList
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a doubly-linked list.
23 *
24 * kList represents a doubly-linked list of objects or values. The kList constructor accepts a kType
25 * value that determines the type of items that will be stored in the list. The list will automatically
26 * grow as new items are added or inserted.
27 *
28 * @code
29 * kStatus ListExample()
30 * {
31 * kList list = kNULL;
32 * k32s values[] = { 1, 2, 3, 5, 7, 9 };
33 * kSize i;
34 * kListItem it = kNULL; //list iterator
35 *
36 * kTry
37 * {
38 * //create a list that can store 32-bit integers
39 * kTest(kList_Construct(&list, kTypeOf(k32s), 0, kNULL));
40 *
41 * //add some initial items to the list
42 * for (i = 0; i < kCountOf(values); ++i)
43 * {
44 * kTest(kList_Add(list, &values[i], kNULL);
45 * }
46 *
47 * //print some information about the list and its items
48 * printf("Item type: %s\n", kType_Name(kList_ItemType(list)));
49 * printf("Count: %u\n", (k32u) kList_Count(list));
50 *
51 * it = kList_First(list);
52 *
53 * while (!kIsNull(it))
54 * {
55 * //the kList_As_ macro can be used to get a list item and cast it to the desired type;
56 * //this is equivalent to *(k32s*)kList_At(list, it);
57 * k32s value = kList_As_(list, it, k32s);
58 *
59 * it = kList_Next(list, it);
60 * }
61 * }
62 * kFinally
63 * {
64 * kObject_Destroy(list);
65 *
66 * kEndFinally();
67 * }
68 *
69 * return kOK;
70 * }
71 *
72 * @endcode
73 *
74 * For lists that contain <em>objects</em> (e.g. kImage) as opposed to <em>values</em> (e.g. k32s), the objects
75 * are not automatically destroyed when the list is destroyed. To recursively destroy both the list and the
76 * list items, use kObject_Dispose.
77 */
78 //typedef kObject kList; --forward-declared in kApiDef.x.h
79
80 /**
81 * Represents a node within a kList object.
82 */
83 typedef kPointer kListItem;
84
85 /**
86 * Constructs a kList object.
87 *
88 * @public @memberof kList
89 * @param list List object.
90 * @param itemType Type of list item.
91 * @param initialCapacity Capacity initially reserved for list items.
92 * @param allocator Memory allocator.
93 * @return Operation status.
94 */
95 kFx(kStatus) kList_Construct(kList* list, kType itemType, kSize initialCapacity, kAlloc allocator);
96
97 /**
98 * Reallocates the list.
99 *
100 * Existing items are discarded.
101 *
102 * @public @memberof kList
103 * @param list List object.
104 * @param itemType Type of list item.
105 * @param initialCapacity Capacity initially reserved for list items.
106 * @return Operation status.
107 */
108 kFx(kStatus) kList_Allocate(kList list, kType itemType, kSize initialCapacity);
109
110 /**
111 * Performs a shallow copy of the source list.
112 *
113 * Source items are copied by value; if the source list contains objects, the object
114 * handles are copied but the objects are not cloned.
115 *
116 * @public @memberof kList
117 * @param list List object.
118 * @param source List to be copied.
119 * @return Operation status.
120 */
121 kFx(kStatus) kList_Assign(kList list, kList source);
122
123 /**
124 * Returns the item type.
125 *
126 * @public @memberof kList
127 * @param list List object.
128 * @return Item type.
129 */
130 kFx(kType) kList_ItemType(kList list);
131
132 /**
133 * Returns the count of list elements.
134 *
135 * @public @memberof kList
136 * @param list List object.
137 * @return Count of elements.
138 */
139 kFx(kSize) kList_Count(kList list);
140
141 /**
142 * Returns the number of elements for which space has been allocated.
143 *
144 * @public @memberof kList
145 * @param list List object.
146 * @return List capacity, in elements.
147 */
148 kFx(kSize) kList_Capacity(kList list);
149
150 /**
151 * Adds a new item to the end of the list
152 *
153 * Increases list capacity, if necessary.
154 *
155 * @public @memberof kList
156 * @param list List object.
157 * @param itemContent Optional pointer to item content that will be copied (by value) into the list.
158 * @param item Optionally receives pointer to newly-inserted item.
159 * @return Operation status.
160 */
161 kFx(kStatus) kList_Add(kList list, const void* itemContent, kListItem* item);
162
163 /**
164 * Inserts an item into the list before the specified list item.
165 *
166 * Increases list capacity, if necessary.
167 *
168 * @public @memberof kList
169 * @param list List object.
170 * @param before Item will be inserted before this list node (if null, inserts at tail).
171 * @param itemContent Optional pointer to item content that will be copied (by value) into the list.
172 * @param item Optionally receives pointer to newly-inserted item.
173 * @return Operation status.
174 */
175 kFx(kStatus) kList_Insert(kList list, kListItem before, const void* itemContent, kListItem* item);
176
177 /**
178 * Removes the specified item from the list.
179 *
180 * @public @memberof kList
181 * @param list List object.
182 * @param item Node to be removed from the list.
183 * @return Operation status.
184 */
185 kFx(kStatus) kList_Remove(kList list, kListItem item);
186
187 /**
188 * Sets the content associated with a list item.
189 *
190 * @public @memberof kList
191 * @param list List object.
192 * @param item List item.
193 * @param content Pointer to content to be copied into the list item.
194 * @return Operation status.
195 */
196 kFx(kStatus) kList_SetItem(kList list, kListItem item, const void* content);
197
198 /**
199 * Gets the content associated with a list item.
200 *
201 * @public @memberof kList
202 * @param list List object.
203 * @param item List item.
204 * @param content Destination for content that will be copied (by value) from the list item.
205 * @return Operation status.
206 */
207 kFx(kStatus) kList_Item(kList list, kListItem item, void* content);
208
209 /**
210 * Ensures that capacity is reserved for at least the specified number of list items.
211 *
212 * @public @memberof kList
213 * @param list List object.
214 * @param capacity List capacity, in items.
215 * @return kOK if removed; kERROR_NOT_FOUND if key not found.
216 */
217 kFx(kStatus) kList_Reserve(kList list, kSize capacity);
218
219 /**
220 * Sets the count of list items to zero.
221 *
222 * @public @memberof kList
223 * @param list List object.
224 * @return Operation status.
225 */
226 kFx(kStatus) kList_Clear(kList list);
227
228 /**
229 * Disposes any elements in the list and sets the count of list items to zero.
230 *
231 * @public @memberof kList
232 * @param list List object.
233 * @return Operation status.
234 */
235 kFx(kStatus) kList_Purge(kList list);
236
237 /**
238 * Gets a reference to the first list item.
239 *
240 * @public @memberof kList
241 * @return First list item, or kNULL.
242 */
243 kFx(kListItem) kList_First(kList list);
244
245 /**
246 * Gets a reference to the last list item.
247 *
248 * @public @memberof kList
249 * @return Last list item, or kNULL.
250 */
251 kFx(kListItem) kList_Last(kList list);
252
253 /**
254 * Given a list item, gets a reference to the next list item.
255 *
256 * @public @memberof kList
257 * @return Next list item, or kNULL.
258 */
259 kFx(kListItem) kList_Next(kList list, kListItem item);
260
261 /**
262 * Given a list item, gets a reference to the previous list item.
263 *
264 * @public @memberof kList
265 * @return Previous list item, or kNULL.
266 */
267 kFx(kListItem) kList_Previous(kList list, kListItem item);
268
269 /**
270 * Finds a reference to the list item at the specified index.
271 *
272 * This method requires a linear search through the list.
273 *
274 * @public @memberof kList
275 * @param list List object.
276 * @param index List item index.
277 * @return List item at index.
278 */
279 kFx(kListItem) kList_FindIndex(kList list, kSize index);
280
281 /**
282 * Returns a pointer to the content associated with a list item.
283 *
284 * @public @memberof kList
285 * @param list List object.
286 * @param item List item.
287 * @return Pointer to key.
288 */
289 kFx(void*) kList_At(kList list, kListItem item);
290
291 /**
292 * Returns a pointer to the content associated with a list item at the specified index.
293 *
294 * @public @memberof kList
295 * @param list List object.
296 * @param index Item index.
297 * @return Pointer to key.
298 */
299 kFx(void*) kList_AtIndex(kList list, kSize index);
300
301
302 #define kList_ItemType_(LIST) kxList_ItemType_(LIST) ///< Macro version of kList_ItemType.
303 #define kList_Count_(LIST) kxList_Count_(LIST) ///< Macro version of kList_Count.
304 #define kList_Capacity_(LIST) kxList_Capacity_(LIST) ///< Macro version of kList_Capacity.
305
306 #define kList_First_(LIST) kxList_First_(LIST) ///< Macro version of kList_First.
307 #define kList_Last_(LIST) kxList_Last_(LIST) ///< Macro version of kList_Last.
308
309 #define kList_Next_(LIST, ITEM) kxList_Next_(LIST, ITEM) ///< Macro version of kList_Next.
310 #define kList_Previous_(LIST, ITEM) kxList_Previous_(LIST, ITEM) ///< Macro version of kList_Previous.
311
312 #define kList_At_(LIST, ITEM) kxList_At_(LIST, ITEM) ///< Macro version of kList_At.
313
314 /** Accesses list item content and casts to the specified type. */
315 #define kList_As_(LIST, ITEM, TYPE) kxList_As_(LIST, ITEM, TYPE)
316
317 kEndHeader()
318
319 #include <kApi/Data/kList.x.h>
320
321 #endif
kList::kList_SetItem
kStatus kList_SetItem(kList list, kListItem item, const void *content)
Sets the content associated with a list item.
kList::kList_Add
kStatus kList_Add(kList list, const void *itemContent, kListItem *item)
Adds a new item to the end of the list.
kList::kList_ItemType
kType kList_ItemType(kList list)
Returns the item type.
kPointer
Represents a void pointer.
kList::kList_Last
kListItem kList_Last(kList list)
Gets a reference to the last list item.
kList::kList_FindIndex
kListItem kList_FindIndex(kList list, kSize index)
Finds a reference to the list item at the specified index.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kList::kList_Assign
kStatus kList_Assign(kList list, kList source)
Performs a shallow copy of the source list.
kList::kList_Construct
kStatus kList_Construct(kList *list, kType itemType, kSize initialCapacity, kAlloc allocator)
Constructs a kList object.
kList::kList_Insert
kStatus kList_Insert(kList list, kListItem before, const void *itemContent, kListItem *item)
Inserts an item into the list before the specified list item.
kList::kList_Remove
kStatus kList_Remove(kList list, kListItem item)
Removes the specified item from the list.
kList::kList_Purge
kStatus kList_Purge(kList list)
Disposes any elements in the list and sets the count of list items to zero.
kList::kList_Clear
kStatus kList_Clear(kList list)
Sets the count of list items to zero.
kList::kList_Item
kStatus kList_Item(kList list, kListItem item, void *content)
Gets the content associated with a list item.
kApiDef.h
Essential API declarations.
kList::kList_Reserve
kStatus kList_Reserve(kList list, kSize capacity)
Ensures that capacity is reserved for at least the specified number of list items.
kList::kList_Capacity
kSize kList_Capacity(kList list)
Returns the number of elements for which space has been allocated.
kList::kList_Count
kSize kList_Count(kList list)
Returns the count of list elements.
kType
Represents metadata about a type (class, interface, or value).
kList
Represents a doubly-linked list.
kStatus
Represents an enumeration of error codes.
kList::kList_At
void * kList_At(kList list, kListItem item)
Returns a pointer to the content associated with a list item.
kList::kList_Allocate
kStatus kList_Allocate(kList list, kType itemType, kSize initialCapacity)
Reallocates the list.
kList::kList_AtIndex
void * kList_AtIndex(kList list, kSize index)
Returns a pointer to the content associated with a list item at the specified index.
kList::kList_Previous
kListItem kList_Previous(kList list, kListItem item)
Given a list item, gets a reference to the previous list item.
kList::kList_First
kListItem kList_First(kList list)
Gets a reference to the first list item.
kList::kList_Next
kListItem kList_Next(kList list, kListItem item)
Given a list item, gets a reference to the next list item.