Maps

In quite a few situations you need to store pairs consisting of a key and a value. For example, a character can have a number of different items and for each item it has a particular number of those. In this case the item is the key and the number is the value. Maps maintain such pairs, sorted by key. You can add pairs to the map and search for the value corresponding to certain keys. Because the keys are sorted you can also find previous and next keys. Sometimes it is also useful to use a map to just store keys without a corresponding value. In that case you can simply use a value of 0. The following functions exist:

ds_map_create() Creates a new map. The function returns an integer as an id that must be used in all other functions to access the particular map.
ds_map_destroy(id) Destroys the map with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_map_clear(id) Clears the map with the given id, removing all data from it but not destroying it.
ds_map_copy(id,source) Copies the map source into the map with the given id.
ds_map_size(id) Returns the number of key-value pairs stored in the map.
ds_map_empty(id) Returns whether the map is empty. This is the same as testing whether the size is 0.
ds_map_add(id,key,val) Adds the key-value pair to the map.
ds_map_replace(id,key,val) Replaces the value corresponding with the key with a new value.
ds_map_delete(id,key) Deletes the key and the corresponding value from the map. (If there are multiple entries with the same key, only one is removed.)
ds_map_exists(id,key) Returns whether the key exists in the map.
ds_map_find_value(id,key) Returns the value corresponding to the key.
ds_map_find_previous(id,key) Returns the largest key in the map smaller than the indicated key. (Note that the key is returned, not the value. You can use the previous routine to find the value.)
ds_map_find_next(id,key) Returns the smallest key in the map larger than the indicated key.
ds_map_find_first(id) Returns the smallest key in the map.
ds_map_find_last(id) Returns the largest key in the map.
ds_map_write(id) Turns the data structure into a string and returns this string. The string can then be used to e.g. save it to a file. This provides an easy mechanism for saving data structures.
ds_map_read(id,str) Reads the data structure from the given string (as created by the previous call).