CMUTIL_Map Struct Reference

Hashmap type with item order preserved. More...

Data Fields
CMBool(*	Put )(CMUTIL_Map *map, const char *key, void *value, void **prev)
	Inserts a key-value pair into the map.
void(*	PutAll )(CMUTIL_Map *map, const CMUTIL_Map *src)
	Copies all key-value pairs from one map to another.
void *(*	Get )(const CMUTIL_Map *map, const char *key)
	Retrieves the value associated with a given key in the map.
void *(*	Remove )(CMUTIL_Map *map, const char *key)
	Removes the key-value pair associated with the given key from the map.
CMUTIL_StringArray *(*	GetKeys )(const CMUTIL_Map *map)
	Get the keys of the map.
const CMUTIL_Array *(*	GetPairs )(const CMUTIL_Map *map)
	Function pointer that retrieves all key-value pairs from a map.
size_t(*	GetSize )(const CMUTIL_Map *map)
	Get the size of the map.
CMUTIL_Iterator *(*	Iterator )(const CMUTIL_Map *map)
	Get iterator for the map.
void(*	Clear )(CMUTIL_Map *map)
	Clear the map.
void(*	ClearLink )(CMUTIL_Map *map)
	Clear the map and free all key-value pairs.
void(*	Destroy )(CMUTIL_Map *map)
	Destroy the map object.
void(*	PrintTo )(const CMUTIL_Map *map, CMUTIL_String *out, const char *(*to_strcb)(void *))
	Print the map to a string.
void *(*	GetAt )(const CMUTIL_Map *map, uint32_t index)
	Get the value at a specific index in the map.
void *(*	RemoveAt )(CMUTIL_Map *map, uint32_t index)
	Remove the value at a specific index in the map.

Detailed Description

Hashmap type with item order preserved.

Field Documentation

Put

CMBool(* CMUTIL_Map::Put) (CMUTIL_Map *map, const char *key, void *value, void **prev)

Inserts a key-value pair into the map.

This function adds a new entry into the map with the specified key and value. If the key already exists in the map, the associated value is updated to the new value provided. The function returns a pointer to the previous value associated with the key if it existed, or NULL if the key was not found in the map before the operation. The order of the items in the map is preserved. If the key already exists, the previous order is discarded and the new key-value pair is inserted at the end of the map. If the load factor ratio of buckets is occupied, the map is rebuilt with 2 times of the current size to reduce the collision rate.

Parameters

map	A pointer to the map where the key-value pair should be inserted.
key	The key associated with the value to insert or update in the map.
value	A pointer to the value to associate with the specified key.
prev	A pointer to a pointer that will receive the previous value associated with the key, or NULL if the key did not previously exist in the map.

Returns

CMTrue if the operation was successful, CMFalse otherwise.

PutAll

void(* CMUTIL_Map::PutAll) (CMUTIL_Map *map, const CMUTIL_Map *src)

Copies all key-value pairs from one map to another.

This function transfers all key-value pairs from the source map to the target map. If keys in the source map already exist in the target map, their values will be replaced with the values from the source map. The operation does not clear existing entries in the target map that do not have corresponding keys in the source map.

Parameters

map	A pointer to the target map where the key-value pairs will be copied.
src	A pointer to the source map containing the key-value pairs to copy.

Get

void *(* CMUTIL_Map::Get) (const CMUTIL_Map *map, const char *key)

Retrieves the value associated with a given key in the map.

This function searches the map for the specified key and returns the value associated with it. If the key is not found, the function returns a null pointer.

Parameters

map	A pointer to the map object to search.
key	The key whose associated value is to be retrieved.

Returns

A pointer to the value associated with the given key, or NULL if the key is not found.

Remove

void *(* CMUTIL_Map::Remove) (CMUTIL_Map *map, const char *key)

Removes the key-value pair associated with the given key from the map.

This function searches the map for the specified key and removes the corresponding key-value pair if found. If the key is not found, the function does nothing and returns NULL.

Parameters

map	A pointer to the map object from which to remove the key-value pair.
key	The key to be removed from the map.

Returns

A pointer to the value associated with the removed key, or NULL if the key was not found.

GetKeys

CMUTIL_StringArray *(* CMUTIL_Map::GetKeys) (const CMUTIL_Map *map)

Get the keys of the map.

This function returns a string array containing all the keys present in the map. The caller is responsible for freeing the returned string array using the Destroy method.

Parameters

map	A pointer to the map object from which to retrieve the keys.

Returns

A pointer to a string array containing the keys or nullptr if the map is empty.

GetPairs

const CMUTIL_Array *(* CMUTIL_Map::GetPairs) (const CMUTIL_Map *map)

Function pointer that retrieves all key-value pairs from a map.

This function pointer takes a constant CMUTIL_Map pointer and returns a CMUTIL_Array pointer containing all the key-value pairs with CMUTIL_MapPair form in the map. The CMUTIL library defines the structure and behavior of the map and the array.

Parameters

map	A constant pointer to the map from which key-value pairs are to be retrieved.

Returns

A pointer to a CMUTIL_Array containing the map's key-value pairs. Do not destroy the returned array as it is managed by the map.

GetSize

size_t(* CMUTIL_Map::GetSize) (const CMUTIL_Map *map)

Get the size of the map.

This function returns the number of key-value pairs currently stored in the map.

Parameters

map	A pointer to the map object from which to retrieve the size.

Returns

The number of key-value pairs in the map.

Iterator

CMUTIL_Iterator *(* CMUTIL_Map::Iterator) (const CMUTIL_Map *map)

Get iterator for the map.

This function returns an iterator object that can be used to traverse the values in the map. The caller is responsible for freeing the returned iterator using the Destroy method.

Parameters

map	A pointer to the map object from which to retrieve the iterator.

Returns

A pointer to the iterator object, or NULL if the map is empty.

Clear

void(* CMUTIL_Map::Clear) (CMUTIL_Map *map)

Clear the map.

This function removes all key-value pairs from the map, effectively resetting it to an empty state. The function does not free the memory associated with the map itself, only the key-value pairs. If this map is created with freecb, it will be called freecb for each value. Otherwise, it will not free the values.

Parameters

map	A pointer to the map object to be cleared.

ClearLink

void(* CMUTIL_Map::ClearLink) (CMUTIL_Map *map)

Clear the map and free all key-value pairs.

This function removes all key-value pairs from the map, effectively resetting it to an empty state. The function will free the memory associated with the map itself and all key-value pairs. Whether this map is created with or without freecb, it will not free the values.

Parameters

map	A pointer to the map object to be cleared.

Destroy

void(* CMUTIL_Map::Destroy) (CMUTIL_Map *map)

Destroy the map object.

This function frees the memory associated with the map object and all key-value pairs. If the map was created with a freecb function, it will be called for each value to free any additional memory.

Parameters

map	A pointer to the map object to be destroyed.

PrintTo

void(* CMUTIL_Map::PrintTo) (const CMUTIL_Map *map, CMUTIL_String *out, const char *(*to_strcb)(void *))

Print the map to a string.

This function appends a string representation of the map to the provided CMUTIL_String object. The format of the string is implementation-dependent.

Parameters

map	A pointer to the map object to be printed.
out	A pointer to the CMUTIL_String object to append the output.
to_strcb	A callback function to convert value to string, or NULL to use as string itself.

GetAt

void *(* CMUTIL_Map::GetAt) (const CMUTIL_Map *map, uint32_t index)

Get the value at a specific index in the map.

This function retrieves the value at the specified index in the map. The index is zero-based, with 0 being the first element.

Parameters

map	A pointer to the map object from which to retrieve the value.
index	The index of the value to retrieve.

Returns

A pointer to the value at the specified index, or NULL if the index is out of bounds.

RemoveAt

void *(* CMUTIL_Map::RemoveAt) (CMUTIL_Map *map, uint32_t index)

Remove the value at a specific index in the map.

This function removes the value at the specified index in the map. The index is zero-based, with 0 being the first element.

Parameters

map	A pointer to the map object from which to remove the value.
index	The index of the value to remove.

Returns

A pointer to the removed value, or NULL if the index is out of bounds.

---

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

• /home/runner/work/libcmutils/libcmutils/src/libcmutils.h