map.h

This interface defines a map abstraction that associates string-valued keys with values. In contrast to the HashMap type defined in the hashmap.h interface, the implementation of the Map type uses a balanced binary tree, which offers logarithmic performance and sorted iteration.

In most applications, the restriction of keys to strings is easy to circumvent. The simplest strategy is to convert key values to strings before inserting them into the map. A more general strategy is to use the bst.h interface instead.
Type
Map This type is the ADT used to represent the map.
Functions
newMap() Allocates a new map with no entries.
freeMap(map) Frees the storage associated with the map.
size(map) Returns the number of elements in the map.
isEmpty(map) Returns true if the map has no entries.
clear(map) Removes all entries from the map.
clone(map) Creates a copy of the map.
put(map, key, value) Associates key with value in the map.
get(map, key) Returns the value associated with key in the map, or NULL, if no such value exists.
containsKey(map, key) Checks to see if the map contains the specified key.
remove(map, key) Removes the key and its value from the map.
map(map, fn, data) Iterates through the map and calls the function fn on each entry.

Type detail


typedef struct MapCDT *Map;
This type is the ADT used to represent the map.

Function detail


Map newMap();
Allocates a new map with no entries.

Usage:

map = newMap();

void freeMap(Map map);
Frees the storage associated with the map.

Usage:

freeMap(map);

int size(Map map);
Returns the number of elements in the map.

Usage:

n = size(map);

bool isEmpty(Map map);
Returns true if the map has no entries.

Usage:

if (isEmpty(map)) . . .

void clear(Map map);
Removes all entries from the map.

Usage:

clear(map);

Map clone(Map map);
Creates a copy of the map. The clone function copies only the first level of the structure and does not copy the individual elements.

Usage:

newmap = clone(map);

void put(Map map, string key, void *value);
Associates key with value in the map. Each call to put supersedes any previous definition for key.

Usage:

put(map, key, value);

void *get(Map map, string key);
Returns the value associated with key in the map, or NULL, if no such value exists.

Usage:

void *value = get(map, key);

bool containsKey(Map map, string key);
Checks to see if the map contains the specified key.

Usage:

if (containsKey(map, key)) . . .

void remove(Map map, string key);
Removes the key and its value from the map.

Usage:

remove(map, key);

void map(Map map, proc fn, void *data);
Iterates through the map and calls the function fn on each entry. The callback function takes the following arguments: The data pointer allows the client to pass state information to the function fn, if necessary. If no such information is required, this argument should be NULL.

Usage:

map(map, fn, data);