Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kMap Class Reference

Description

Represents a collection of key-value pairs stored in a hash table.

The kMap class represents a hash table of key-value pairs. The kMap constructor accepts kType arguments that determine the key type and value type.

The map will automatically grow as new items are inserted. The size of the internal bucket array is always a power of two and secondary hashing is not performed on keys. This places the burden on the caller to ensure that keys have roughly uniform distribution, else clustering may occur. If in doubt, consider installing a custom hash function (via kMap_SetHashFx) to ensure good key distribution.

The following example illustrates how to construct a kMap instance, populate it, and access elements.

kStatus MapExample()
{
kMap map = kNULL;
kText32 keys[] = { "one", "two", "three", "four", "five" };
k32s values[] = { 1, 2, 3, 4, 5 };
k32s result = 0;
kMapItem resultIt = kNULL; //map iterator
kSize i;
kMapItem it = kNULL; //map iterator
{
//create a map that can store small char-array keys and 32-bit integer values
//add some initial items to the map
for (i = 0; i < kCountOf(keys); ++i)
{
kTest(kMap_Add(map, &keys[i], &values[i]));
}
//perform some queries;
//kMap_Find looks up a key and returns the value
if (kSuccess(kMap_Find(map, "three", &result)))
{
printf("three: %d\n", result);
}
//kMap_FindItem looks up a key and returns an iterator to the key-value pair
if (kSuccess(kMap_FindItem(map, "four", &resultIt)))
{
printf("four: %d\n", kMap_ValueAs_(map, resultIt, k32s));
}
//print some information about the map
printf("Key type: %s\n", kType_Name(kMap_KeyType(map)));
printf("Value type: %s\n", kType_Name(kMap_ValueType(map)));
printf("Count: %u\n", (k32u) kMap_Count(map));
//print the map items; note, the items will not be printed in sorted order
//because kMap is not a sorted collection
it = kMap_First(map);
while (!kIsNull(it))
{
const kChar* key = kMap_Key(map, it);
k32s value = *(k32s*) kMap_Value(map, it);
printf("key: %s, value: %d\n", key, value);
it = kMap_Next(map, it);
}
}
{
}
return kOK;
}

For maps that contain key or value objects (e.g. kString) as opposed to values (e.g. kText32), the objects are not automatically destroyed when the map is destroyed. To recursively destroy both the map and its keys/values, use kObject_Dispose. Similarly, kMap does not automatically dispose key/value objects when they are replaced or cleared from the map.

kStatus MapOfObjectsExample()
{
kMap map = kNULL;
kString keyIn = kNULL;
kImage valueIn = kNULL;
kString keyOut = kNULL;
kImage valueOut = kNULL;
kImage result = kNULL;
kMapItem resultIt = kNULL; //map iterator
kMapItem it = kNULL; //map iterator
{
//create a map that can store kString keys and kImage values
//add some initial items to the map
kTest(kString_Construct(&keyIn, "one", kNULL));
kTest(kImage_Construct(&valueIn, kTypeOf(k8u), 100, 100, kNULL));
kTest(kMap_AddT(map, &keyIn, &valueIn));
keyIn = valueIn = kNULL;
kTest(kString_Construct(&keyIn, "two", kNULL));
kTest(kImage_Construct(&valueIn, kTypeOf(k8u), 200, 200, kNULL));
kTest(kMap_AddT(map, &keyIn, &valueIn));
keyIn = valueIn = kNULL;
kTest(kString_Construct(&keyIn, "three", kNULL));
kTest(kImage_Construct(&valueIn, kTypeOf(k8u), 300, 300, kNULL));
kTest(kMap_AddT(map, &keyIn, &valueIn));
keyIn = valueIn = kNULL;
//perform some queries;
//kMap_FindT looks up a key and returns the value
if (kSuccess(kMap_FindT(map, "two", &result)))
{
printf("two: width(%u), height(%u)\n", (k32u)kImage_Width(result), (k32u)kImage_Height(result));
}
//kMap_FindItemT looks up a key and returns an iterator to the key-value pair
if (kSuccess(kMap_FindItemT(map, "one", &resultIt)))
{
kImage image = kMap_ValueAsT(map, resultIt, kImage);
printf("one: width(%u), height(%u)\n", (k32u)kImage_Width(image), (k32u)kImage_Height(image));
}
//there are several ways to replace a key/value pair, depending on whether it is already known
//that the key is in the collection, and whether the key/value need to be destroyed/disposed;
//the approach below first removes and destroys the key/value if they exist, then adds replacements
if (kSuccess(kMap_RemoveT(map, "one", &keyOut, &valueOut)))
{
kObject_Destroy(keyOut);
kObject_Destroy(valueOut);
}
kTest(kString_Construct(&keyIn, "one", kNULL));
kTest(kImage_Construct(&valueIn, kTypeOf(k8u), 1000, 1000, kNULL));
kTest(kMap_AddT(map, &keyIn, &valueIn));
keyIn = valueIn = kNULL;
}
{
//clean up temp variables, in case of error above
kObject_Destroy(keyIn);
kObject_Destroy(valueIn);
//dispose map; will destroy internal key/value objects
}
return kOK;
}

kMap supports the kObject_Clone, kObject_Dispose, and kObject_Size methods.

kMap supports the kdat6 serialization protocol.

Inheritance diagram for kMap:
Inheritance graph

Public Member Functions

kStatus kMap_Add (kMap map, const void *key, const void *value)
 Adds a new key-value pair. More...
 
kStatus kMap_Allocate (kMap map, kType keyType, kType valueType, kSize initialCapacity)
 Reallocates the map. More...
 
kStatus kMap_Assign (kMap map, kMap source)
 Performs a shallow copy of the source map. More...
 
kSize kMap_Capacity (kMap map)
 Returns the number of elements for which space has been allocated. More...
 
kStatus kMap_Clear (kMap map)
 Sets the count of map items to zero. More...
 
kStatus kMap_Construct (kMap *map, kType keyType, kType valueType, kSize initialCapacity, kAlloc allocator)
 Constructs a kMap object. More...
 
kSize kMap_Count (kMap map)
 Returns the count of map elements. More...
 
kStatus kMap_Discard (kMap map, const void *key)
 Removes a key-value pair from the map. More...
 
kStatus kMap_Find (kMap map, const void *key, void *value)
 Finds the value associated with the given key. More...
 
kStatus kMap_FindItem (kMap map, const void *key, kMapItem *item)
 Finds the map item associated with the given key. More...
 
kMapItem kMap_First (kMap map)
 Gets a reference to the first map item (key-value pair). More...
 
kBool kMap_Has (kMap map, const void *key)
 Reports whether the specified key is present in the map. More...
 
const void * kMap_Key (kMap map, kMapItem item)
 Returns a pointer to the key associated with a map item. More...
 
kType kMap_KeyType (kMap map)
 Returns the key type. More...
 
kMapItem kMap_Next (kMap map, kMapItem item)
 Given a map item, gets a reference to the next map item. More...
 
kStatus kMap_Purge (kMap map)
 Disposes any elements in the map and sets the count of map items to zero. More...
 
kStatus kMap_Remove (kMap map, const void *key, void *oldKey, void *oldValue)
 Removes a key-value pair from the map, optionally returning the old key and/or value. More...
 
kStatus kMap_RemoveItem (kMap map, kMapItem item)
 Removes an item from the map. More...
 
kStatus kMap_Replace (kMap map, const void *key, const void *value)
 Adds or replaces a key-value pair. More...
 
kStatus kMap_Reserve (kMap map, kSize capacity)
 Ensures that capacity is reserved for at least the specified number of map items. More...
 
kStatus kMap_SetEqualsFx (kMap map, kEqualsFx function)
 Sets a custom key equality comparator. More...
 
kStatus kMap_SetHashFx (kMap map, kHashFx function)
 Sets a custom hash code generator. More...
 
kStatus kMap_SetValue (kMap map, kMapItem item, const void *value)
 Sets the value associated with a map item. More...
 
void * kMap_Value (kMap map, kMapItem item)
 Returns a pointer to the value associated with a map item. More...
 
kType kMap_ValueType (kMap map)
 Returns the value type. More...
 
- Public Member Functions inherited from kObject
kAlloc kObject_Alloc (kObject object)
 Gets the memory allocator associated with this object. More...
 
kStatus kObject_Clone (kObject *object, kObject source, kAlloc allocator)
 Constructs a new object by copying an existing object, including any aggregated child elements. More...
 
kStatus kObject_Destroy (kObject object)
 Destroys the object. More...
 
kStatus kObject_Dispose (kObject object)
 Destroys the object and any aggregated child elements. More...
 
kBool kObject_Equals (kObject object, kObject other)
 Determines whether the object is equal to another object. More...
 
kBool kObject_HasForeignData (kObject object)
 Reports whether the object, including aggregated child elements, contains any foreign memory references. More...
 
kSize kObject_HashCode (kObject object)
 Gets a hash code representing the state of this object. More...
 
kBool kObject_Is (kObject object, kType type)
 Determines whether this object is an instance of the specified type. More...
 
kBool kObject_IsShared (kObject object)
 Reports whether the object is currently shared (reference count greater than one). More...
 
kStatus kObject_SetPool (kObject object, kObjectPool pool)
 Sets the object pool associated with this object. More...
 
kStatus kObject_Share (kObject object)
 Increments the reference count associated with this object. More...
 
kSize kObject_Size (kObject object)
 Estimates the memory consumed by this object, including any aggregated child elements. More...
 
kType kObject_Type (kObject object)
 Returns the type of the object. More...
 

Related

#define kMap_AddT(kMap_map, KPtr_key, VPtr_value)
 Adds a new key-value pair. More...
 
#define kMap_FindItemT(kMap_map, KPtr_key, kMapItemPtr_item)
 Finds the map item associated with the given key. More...
 
#define kMap_FindT(kMap_map, KPtr_key, VPtr_value)
 Finds the value associated with the given key. More...
 
#define kMap_HasT(kMap_map, KPtr_key)
 Reports whether the specified key is present in the map. More...
 
#define kMap_KeyAsT(kMap_map, kMapItem_item, K)
 Gets the key associated with a map item. More...
 
#define kMap_KeyT(kMap_map, kMapItem_item, K)
 Returns a strongly-typed pointer to the key associated with a map item. More...
 
#define kMap_RemoveT(kMap_map, KPtr_key, KPtr_oldKey, VPtr_oldValue)
 Removes a key-value pair from the map, returning the old key and/or value. More...
 
#define kMap_ReplaceT(kMap_map, KPtr_key, VPtr_value)
 Adds or replaces a key-value pair. More...
 
#define kMap_SetValueAsT(kMap_map, kMapItem_item, V_value, V)
 Sets the value associated with a map item. More...
 
#define kMap_SetValueT(kMap_map, kMapItem_item, VPtr_value)
 Sets the value associated with a map item. More...
 
#define kMap_ValueAsT(kMap_map, kMapItem_item, V)
 Gets the value associated with a map item. More...
 
#define kMap_ValueT(kMap_map, kMapItem_item, V)
 Returns a strongly-typed pointer to the value associated with a map item. More...
 
kPointer kMapItem
 Represents a key-value pair within a map.
 

Additional Inherited Members

- Protected Member Functions inherited from kObject
kStatus kObject_FreeMem (kObject object, void *mem)
 Protected method called by derived classes to free memory using the object's allocator. More...
 
kStatus kObject_FreeMemRef (kObject object, void *mem)
 Protected method called by derived classes to free memory (and reset the provided memory pointer to kNULL) using the object's allocator. More...
 
kStatus kObject_GetMem (kObject object, kSize size, void *mem)
 Protected method called by derived classes to allocate memory using the object's allocator. More...
 
kStatus kObject_GetMemZero (kObject object, kSize size, void *mem)
 Protected method called by derived classes to allocate and zero memory using the object's allocator. More...
 
kStatus kObject_Init (kObject object, kType type, kAlloc alloc)
 Protected method called by derived classes to initialize the kObject base class. More...
 
kStatus kObject_VDisposeItems (kObject object)
 Protected virtual method that destroys any aggregated child objects associated with a collection. More...
 
kBool kObject_VEquals (kObject object, kObject other)
 Protected virtual method that compares two objects for equality. More...
 
kBool kObject_VHasForeignData (kObject object)
 Protected virtual method that reports whether the object, including aggregated child elements, contains any foreign memory references. More...
 
kSize kObject_VHashCode (kObject object)
 Protected virtual method that calculates a hash code representing the object instance. More...
 
kStatus kObject_VInitClone (kObject object, kObject source, kAlloc allocator)
 Protected virtual method that clones (makes a deep copy of) the specified source object. More...
 
kStatus kObject_VRelease (kObject object)
 Protected virtual method that deallocates any resources owned by the object. More...
 
kSize kObject_VSize (kObject object)
 Protected virtual method that calculates the total size (in bytes) of the object instance. More...
 

The documentation for this class was generated from the following file: