Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kMap.h
Go to the documentation of this file.
1 /**
2 * @file kMap.h
3 * @brief Declares the kMap class.
4 *
5 * @internal
6 * Copyright (C) 2012-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_MAP_H
11 #define K_API_MAP_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kMap
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a collection of key-value pairs stored in a hash table.
23 *
24 * kMap represents a hash-table of key-value pairs. The kMap constructor accepts kType arguments that determine
25 * the key type and value type. The map will automatically grow as new items are inserted.
26 *
27 * For maps that contain key or value <em>objects</em> (e.g. kString) as opposed to <em>values</em> (e.g. kText32),
28 * the objects are not automatically destroyed when the map is destroyed. To recursively destroy both the map and its
29 * keys/values, use kObject_Dispose.
30 */
31 //typedef kObject kMap; --forward-declared in kApiDef.x.h
32
33 /**
34 * Represents a key-value pair within a map.
35 */
36 typedef kPointer kMapItem;
37
38 /**
39 * Constructs a kMap object.
40 *
41 * @public @memberof kMap
42 * @param map Map object.
43 * @param keyType Type of map key.
44 * @param valueType Type of map value.
45 * @param initialCapacity Capacity initially reserved for map items.
46 * @param allocator Memory allocator.
47 * @return Operation status.
48 */
49 kFx(kStatus) kMap_Construct(kMap* map, kType keyType, kType valueType, kSize initialCapacity, kAlloc allocator);
50
51 /**
52 * Reallocates the map.
53 *
54 * Existing items are discarded.
55 *
56 * @public @memberof kMap
57 * @param map Map object.
58 * @param keyType Type of map key.
59 * @param valueType Type of map value.
60 * @param initialCapacity Capacity initially reserved for map items.
61 * @return Operation status.
62 */
63 kFx(kStatus) kMap_Allocate(kMap map, kType keyType, kType valueType, kSize initialCapacity);
64
65 /**
66 * Performs a shallow copy of the source map.
67 *
68 * Source key-value pairs are copied by value; if the source map contains objects, the object
69 * handles are copied but the objects are not cloned.
70 *
71 * @public @memberof kMap
72 * @param map Map object.
73 * @param source Map to be copied.
74 * @return Operation status.
75 */
76 kFx(kStatus) kMap_Assign(kMap map, kMap source);
77
78 /**
79 * Sets a custom key equality comparator.
80 *
81 * @public @memberof kMap
82 * @param map Map object.
83 * @param function Key equality function (or kNULL to unset).
84 * @return Operation status.
85 */
86 kFx(kStatus) kMap_SetEqualsFx(kMap map, kEqualsFx function);
87
88 /**
89 * Sets a custom hash code generator.
90 *
91 * Calling this method will cause the existing map keys to be rehashed using
92 * using the new hash function. If changing both the equals function and the hash function,
93 * change equals first, then hash.
94 *
95 * @public @memberof kMap
96 * @param map Map object.
97 * @param function Hash code function (or kNULL to unset).
98 * @return Operation status.
99 */
100 kFx(kSize) kMap_SetHashFx(kMap map, kHashFx function);
101
102 /**
103 * Returns the key type.
104 *
105 * @public @memberof kMap
106 * @param map Map object.
107 * @return Key type.
108 */
109 kFx(kType) kMap_KeyType(kMap map);
110
111 /**
112 * Returns the value type.
113 *
114 * @public @memberof kMap
115 * @param map Map object.
116 * @return Key type.
117 */
118 kFx(kType) kMap_ValueType(kMap map);
119
120 /**
121 * Returns the count of map elements.
122 *
123 * @public @memberof kMap
124 * @param map Map object.
125 * @return Count of elements.
126 */
127 kFx(kSize) kMap_Count(kMap map);
128
129 /**
130 * Returns the number of elements for which space has been allocated.
131 *
132 * @public @memberof kMap
133 * @param map Map object.
134 * @return Map capacity, in elements.
135 */
136 kFx(kSize) kMap_Capacity(kMap map);
137
138 /**
139 * Finds the value associated with the given key.
140 *
141 * @public @memberof kMap
142 * @param map Map object.
143 * @param key Pointer to key.
144 * @param value Optionally receives value (can be kNULL).
145 * @return kOK if found; kERROR_NOT_FOUND if not found.
146 */
147 kFx(kStatus) kMap_Find(kMap map, const void* key, void* value);
148
149 /**
150 * Adds a new key-value pair.
151 *
152 * @public @memberof kMap
153 * @param map Map object.
154 * @param key Pointer to key.
155 * @param value Pointer to value.
156 * @return kOK if added; kERROR_ALREADY_EXISTS if key already present.
157 */
158 kFx(kStatus) kMap_Add(kMap map, const void* key, const void* value);
159
160 /**
161 * Adds or replaces a key-value pair.
162 *
163 * @public @memberof kMap
164 * @param map Map object.
165 * @param key Pointer to key.
166 * @param value Pointer to value.
167 * @return Operation status.
168 */
169 kFx(kStatus) kMap_Replace(kMap map, const void* key, const void* value);
170
171 /**
172 * Removes a key-value pair from the map.
173 *
174 * @public @memberof kMap
175 * @param map Map object.
176 * @param key Pointer to key.
177 * @param oldKey Optionally receives key (can be kNULL).
178 * @param oldValue Optionally receives value (can be kNULL).
179 * @return kOK if removed; kERROR_NOT_FOUND if key not found.
180 */
181 kFx(kStatus) kMap_Remove(kMap map, const void* key, void* oldKey, void* oldValue);
182
183 /**
184 * Ensures that capacity is reserved for at least the specified number of map items.
185 *
186 * @public @memberof kMap
187 * @param map Map object.
188 * @param capacity Map capacity, in items.
189 * @return kOK if removed; kERROR_NOT_FOUND if key not found.
190 */
191 kFx(kStatus) kMap_Reserve(kMap map, kSize capacity);
192
193 /**
194 * Sets the count of map items to zero.
195 *
196 * @public @memberof kMap
197 * @param map Map object.
198 * @return Operation status.
199 */
200 kFx(kStatus) kMap_Clear(kMap map);
201
202 /**
203 * Disposes any elements in the map and sets the count of map items to zero.
204 *
205 * @public @memberof kMap
206 * @param map Map object.
207 * @return Operation status.
208 */
209 kFx(kStatus) kMap_Purge(kMap map);
210
211 /**
212 * Gets a reference to the first map item (key-value pair).
213 *
214 * @public @memberof kMap
215 * @return First map item, or kNULL.
216 */
217 kFx(kMapItem) kMap_First(kMap map);
218
219 /**
220 * Given a map item, gets a reference to the next map item.
221 *
222 * @public @memberof kMap
223 * @return Next map item, or kNULL.
224 */
225 kFx(kMapItem) kMap_Next(kMap map, kMapItem item);
226
227 /**
228 * Finds the map item associated with the given key.
229 *
230 * @public @memberof kMap
231 * @param map Map object.
232 * @param key Pointer to key.
233 * @param item Optionally receives map item (can be kNULL).
234 * @return kOK if found; kERROR_NOT_FOUND if not found.
235 */
236 kFx(kStatus) kMap_FindItem(kMap map, const void* key, kMapItem* item);
237
238 /**
239 * Removes an item from the map.
240 *
241 * @public @memberof kMap
242 * @param map Map object.
243 * @param item Map item.
244 * @return Operation status.
245 */
246 kFx(kStatus) kMap_RemoveItem(kMap map, kMapItem item);
247
248 /**
249 * Returns a pointer to the key associated with a map item.
250 *
251 * @public @memberof kMap
252 * @param map Map object.
253 * @param item Map item.
254 * @return Pointer to key.
255 */
256 kFx(const void*) kMap_Key(kMap map, kMapItem item);
257
258 /**
259 * Returns a pointer to the value associated with a map item.
260 *
261 * @public @memberof kMap
262 * @param map Map object.
263 * @param item Map item.
264 * @return Pointer to value.
265 */
266 kFx(void*) kMap_Value(kMap map, kMapItem item);
267
268 /**
269 * Sets the value associated with a map item.
270 *
271 * @public @memberof kMap
272 * @param map Map object.
273 * @param item Map item.
274 * @param value Pointer to value to be copied into the map item.
275 * @return Operation status.
276 */
277 kFx(kStatus) kMap_SetValue(kMap map, kMapItem item, const void* value);
278
279 #define kMap_KeyType_(MAP) kxMap_KeyType_(MAP) ///< Macro version of kMap_KeyType.
280 #define kMap_ValueType_(MAP) kxMap_ValueType_(MAP) ///< Macro version of kMap_ValueType.
281 #define kMap_Count_(MAP) kxMap_Count_(MAP) ///< Macro version of kMap_Count.
282
283 /** Accesses a map item key and casts the key to the specified type. */
284 #define kMap_KeyAs_(MAP, ITEM, TYPE) kxMap_KeyAs_(MAP, ITEM, TYPE)
285
286 /** Accesses a map item value and casts the value to the specified type. */
287 #define kMap_ValueAs_(MAP, ITEM, TYPE) kxMap_ValueAs_(MAP, ITEM, TYPE)
288
289 kEndHeader()
290
291 #include <kApi/Data/kMap.x.h>
292
293 #endif
kMap::kMap_SetValue
kStatus kMap_SetValue(kMap map, kMapItem item, const void *value)
Sets the value associated with a map item.
kPointer
Represents a void pointer.
kMap::kMap_Purge
kStatus kMap_Purge(kMap map)
Disposes any elements in the map and sets the count of map items to zero.
kMap::kMap_Add
kStatus kMap_Add(kMap map, const void *key, const void *value)
Adds a new key-value pair.
kMap::kMap_First
kMapItem kMap_First(kMap map)
Gets a reference to the first map item (key-value pair).
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kMap::kMap_Allocate
kStatus kMap_Allocate(kMap map, kType keyType, kType valueType, kSize initialCapacity)
Reallocates the map.
kHashFx
kSize(kCall * kHashFx)(const void *item)
Callback signature to determine hash code of an item.
Definition: kApiDef.h:1020
kMap::kMap_Value
void * kMap_Value(kMap map, kMapItem item)
Returns a pointer to the value associated with a map item.
kMap::kMap_Count
kSize kMap_Count(kMap map)
Returns the count of map elements.
kMap::kMap_Clear
kStatus kMap_Clear(kMap map)
Sets the count of map items to zero.
kMap::kMap_Capacity
kSize kMap_Capacity(kMap map)
Returns the number of elements for which space has been allocated.
kMap::kMap_SetEqualsFx
kStatus kMap_SetEqualsFx(kMap map, kEqualsFx function)
Sets a custom key equality comparator.
kMap::kMap_Reserve
kStatus kMap_Reserve(kMap map, kSize capacity)
Ensures that capacity is reserved for at least the specified number of map items. ...
kMap::kMap_Remove
kStatus kMap_Remove(kMap map, const void *key, void *oldKey, void *oldValue)
Removes a key-value pair from the map.
kApiDef.h
Essential API declarations.
kEqualsFx
kBool(kCall * kEqualsFx)(const void *item1, const void *item2)
Callback signature to determine equality of two items.
Definition: kApiDef.h:1012
kMap::kMap_ValueType
kType kMap_ValueType(kMap map)
Returns the value type.
kMap::kMap_SetHashFx
kSize kMap_SetHashFx(kMap map, kHashFx function)
Sets a custom hash code generator.
kMap::kMap_Find
kStatus kMap_Find(kMap map, const void *key, void *value)
Finds the value associated with the given key.
kType
Represents metadata about a type (class, interface, or value).
kMap::kMap_FindItem
kStatus kMap_FindItem(kMap map, const void *key, kMapItem *item)
Finds the map item associated with the given key.
kMap::kMap_Construct
kStatus kMap_Construct(kMap *map, kType keyType, kType valueType, kSize initialCapacity, kAlloc allocator)
Constructs a kMap object.
kMap::kMap_Key
const void * kMap_Key(kMap map, kMapItem item)
Returns a pointer to the key associated with a map item.
kMap::kMap_Next
kMapItem kMap_Next(kMap map, kMapItem item)
Given a map item, gets a reference to the next map item.
kMap::kMap_Assign
kStatus kMap_Assign(kMap map, kMap source)
Performs a shallow copy of the source map.
kStatus
Represents an enumeration of error codes.
kMap::kMap_RemoveItem
kStatus kMap_RemoveItem(kMap map, kMapItem item)
Removes an item from the map.
kMap::kMap_KeyType
kType kMap_KeyType(kMap map)
Returns the key type.
kMap
Represents a collection of key-value pairs stored in a hash table.
kMap::kMap_Replace
kStatus kMap_Replace(kMap map, const void *key, const void *value)
Adds or replaces a key-value pair.