Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kCollection.h
Go to the documentation of this file.
1 /**
2 * @file kCollection.h
3 * @brief Declares the kCollection interface.
4 *
5 * @internal
6 * Copyright (C) 2008-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_COLLECTION_H
11 #define K_API_COLLECTION_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @interface kCollection
19 * @ingroup kApi-Data
20 * @brief Supports forward iteration over a collection of items.
21 * @see kIterator
22 *
23 * The kCollection interface supports forward iteration over a collection of elements. Typically,
24 * the classes that implement this interface provide alternative, class-specific accessor
25 * methods with better performance. However, the kCollection interface can be used to reduce the amount
26 * of container-specific code required to iterate over a variety of collections, in contexts where
27 * performance is not important.
28 *
29 * @code
30 * kObject collection = arrayList;
31 * kIterator it = kCollection_GetIterator(collection);
32 * kType type = kCollection_ItemType(collection);
33 *
34 * while (kCollection_HasNext(collection, it))
35 * {
36 * void* item = kCollection_Next(collection, &it);
37 * //...
38 * }
39 * @endcode
40 */
41 //typedef kObject kCollection; --forward-declared in kApiDef.x.h
42
43 /**
44 * @struct kIterator
45 * @ingroup kApi-Data
46 * @brief Used in conjunction with the kCollection class to iterate over elements.
47 * @see kCollection
48 *
49 * kIterator is an opaque value type; an iterator instance can be copied by value, but the
50 * contents of the iterator structure should not be examined or manipulated directly. Use
51 * kCollection methods to work with the iterator.
52 */
53 //typedef kPointer kIterator; --forward-declared in kApiDef.x.h
54
55 /**
56 * Gets the collection element type.
57 *
58 * @public @memberof kCollection
59 * @param collection Collection object.
60 * @return Item type.
61 */
62 kFx(kType) kCollection_ItemType(kCollection collection);
63
64 /**
65 * Gets the collection element count.
66 *
67 * @public @memberof kCollection
68 * @param collection Collection object.
69 * @return Item count.
70 */
71 kFx(kSize) kCollection_Count(kCollection collection);
72
73 /**
74 * Returns an iterator to the first element in the collection.
75 *
76 * @public @memberof kCollection
77 * @param collection Collection object.
78 * @return Iterator.
79 */
80 kFx(kIterator) kCollection_GetIterator(kCollection collection);
81
82 /**
83 * Determines whether a collection has another item.
84 *
85 * @public @memberof kCollection
86 * @param collection Collection object.
87 * @param iterator Collection iterator.
88 * @return kTRUE if the collection has a next element.
89 */
90 kFx(kBool) kCollection_HasNext(kCollection collection, kIterator iterator);
91
92 /**
93 * Gets the next collection element and then advances the iterator.
94 *
95 * @public @memberof kCollection
96 * @param collection Collection object.
97 * @param iterator Pointer to collection iterator.
98 * @return Pointer to next collection element.
99 */
100 kFx(void*) kCollection_Next(kCollection collection, kIterator* iterator);
101
102 kEndHeader()
103
104 #include <kApi/Data/kCollection.x.h>
105
106 #endif
kCollection::kCollection_GetIterator
kIterator kCollection_GetIterator(kCollection collection)
Returns an iterator to the first element in the collection.
kCollection
Supports forward iteration over a collection of items.
kSize
Represents an unsigned integer that can store a pointer address.
kIterator
Used in conjunction with the kCollection class to iterate over elements.
kCollection::kCollection_HasNext
kBool kCollection_HasNext(kCollection collection, kIterator iterator)
Determines whether a collection has another item.
kApiDef.h
Essential API declarations.
kCollection::kCollection_ItemType
kType kCollection_ItemType(kCollection collection)
Gets the collection element type.
kType
Represents metadata about a type (class, interface, or value).
kCollection::kCollection_Next
void * kCollection_Next(kCollection collection, kIterator *iterator)
Gets the next collection element and then advances the iterator.
kBool
Represents a boolean value.
kCollection::kCollection_Count
kSize kCollection_Count(kCollection collection)
Gets the collection element count.