HashMap
A HashMap is a container storing Key-Value pairs which is very efficient with many entries that have different keys.
Due to keys being stored by their hash, a HashMap provides constant-time lookup for keys, meaning it is very efficient for finding a key. More information on Wikipedia.
As a HashMap is a container, it stores some traits/properties with Arrays
Working with Hash Maps
Array properties
A HashMap variable is a reference to the HashMap(see Wikipedia reference page); this means that if the HashMap is edited, all the scripts/functions using a reference to this HashMap will see the edition.
private _myMap = createHashMapFromArray [["a",1], ["b",2], ["c",3]]; private _myNewMap = _myMap; _myMap set ["z", 4]; _myNewMap get "z"; // will be 4
An array set through setVariable does not need to be assigned again if you modify it by reference:
player setVariable ["myMap", createHashMapFromArray [["a",1], ["b",2], ["c",3]]]; private _myMap = player getVariable "myMap"; _myMap set ["z", 4]; player getVariable "myMap"; // is [["a",1], ["b",2], ["c",3], ["z",4]]
Key Types
Due to the keys requirement to be hashable not all variable types are supported to be used as a key in the HashMap.
Supported types are:
The Array type also can only contain supported types.
The virtual type HashMapKey is a combination of all supported types.
Array keys are deep-copied on insertion, and cannot be modified when retrieved via keys or inside forEach.
Creating a HashMap
// Example of an empty HashMap private _myMap = createHashMap; count _myMap; // returns 0 // Example of a prefilled HashMap private _myFilledMap = createHashMapFromArray [["a",1], ["b",2], ["c", 3]]; count _myFilledMap; // returns 2
Setting an element
private _myMap = createHashMap; _myMap set [1, "hello there"]; // _myMap is 1, "hello there"
Inserting an element with a key that already exists inside the HashMap, will overwrite the existing key.
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; _overwritten = _myMap set ["a", 1337]; // _myMap is now [["a",1337], ["b",2]] and _overwritten is true
Getting an element
Values are retrieved by their key:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; _myMap get "a"; // returns 1 _myMap get "z"; // returns Nothing _myMap getOrDefault ["z", "NotFound"]; // returns "NotFound"
Checking if an element exists
You can check if a key is in the HashMap using the in command:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; "a" in _myMap; // returns true "z" in _myMap; // returns false
Counting elements
The count command can be used to return the number of Key-Value Pairs stored in the HashMap:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; count _myMap ; // returns 2
Retrieving Keys
You can retrieve an Array of all keys in the HashMap using the keys command:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; keys _myMap; // returns ["a", "b"]
HashMap Copy
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; private _myNewMap = _myMap; _myMap set ["a", 1337]; _myNewMap get "a"; // will be 1337
In order to avoid this behaviour, copy the HashMap with + (plus):
// making copy private _myMap = createHashMapFromArray [["a",1], ["b",2]]; private _myNewMap = +_myMap; _myMap set ["a", 1337]; _myNewMap get "a"; // still 1
Arrays stored as Key or value in the HashMap will also be deep-copied.
Removing (deleting) elements
You can remove elements from the HashMap by using deleteAt with the elements key:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; _myMap deleteAt "b"; // _myMap is "a",1
Iterating through the HashMap
The simplest way to iterate through a HashMap is the forEach command:
private _myMap = createHashMapFromArray [["a",1], ["b",2]]; { systemChat str [ _x, _y ] } forEach _myMap;
When iterating through a HashMap with forEach, the _x variable holds the key of the current element, while the _y variable holds its value.
Advanced usage
Common errors
Scalar Key precision
bla bla when using scalar key bla bla link to wikipedia floating point precision