ds_map_add

This function should be used to add sets of key/value pairs into the specified DS map.

You can check this function to see if it was successful or not (it will return true on success or false otherwise), as it may fail if there already exists the same key in the DS map or you specify a non-existent DS map as the ID of the map to add to.

The keys and and values you supply can be made up of any combination of data types, so all of the following - and more - are acceptable (although, in practice, you would most commonly use a string for the key):

ds_map_add(map, 5, undefined);
ds_map_add(map, "level", 1);
ds_map_add(map, 89.6, "hello world");
ds_map_add(map, 5, buffer_get_address(buff)); // This will return false and fail, as the key 5 already exists in the map

You can also add to a map using the accessor "?", as shown below, however this is a ds_map_set operation and will successfully update existing keys as well, unlike the add function.

map[? 5] = undefined;
map[? "level"] = 1;
map[? 89.6] = "hello world";
map[? 5] = buffer_get_address(buff); // This will succeed as it is a "set" and not an "add"

NOTE Unlike other data structures in GameMaker this key will not go to the start (nor the end) of the DS map, but rather it will just go into the DS map somewhere.

Syntax:

ds_map_add(id, key, val);

Returns:

Boolean

Example:

inventory = ds_map_create();
ds_map_add(inventory, "hp potion", 1);
ds_map_add(inventory, "gold", 100);

This will create a new map, assigning its id to the variable "inventory". It then adds two new keys to the map, "hp potion" and "gold", and sets their initial values as 1 and 100.