Difference between revisions of "HashMap"

From Bohemia Interactive Community
Jump to navigation Jump to search
(Created page with "Hello! I'm a WIP, Wevy Impwortant pewson.")
 
(Fill page with some basics)
Line 1: Line 1:
Hello! I'm a WIP, Wevy Impwortant pewson.
+
{{SideTOC}}
 +
A '''HashMap''' is a container storing Key-Value pairs which is very efficient with many entries that have different keys.
 +
As a HashMap is a container, it stores some traits/properties with [[Array|Arrays]]
 +
This container was added with v2.01 #TODO make a icon thingy or note thingy
 +
 
 +
See also: [[:Category:HashMap|HashMaps]]
 +
 
 +
== Working with Hash Maps ==
 +
 
 +
=== Array properties ===
 +
 
 +
A HashMap variable is a '''reference''' to the HashMap(see [https://en.wikipedia.org/wiki/Reference_(computer_science) 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"; {{cc|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"; {{cc|is ["a",1], ["b",2], ["c",3], ["z",4]}}
 +
 
 +
=== Creating a HashMap ===
 +
 
 +
{{cc|Example of an empty HashMap}}
 +
[[private]] _myMap = [[createHashMap]];
 +
[[count]] _myMap; {{cc|returns 0}}
 +
 +
{{cc|Example of a prefilled HashMap}}
 +
[[private]] _myFilledMap = [[createHashMapFromArray]] [["a",1], ["b",2], ["c", 3]];
 +
[[count]] _myFilledMap; {{cc|returns 2}}
 +
 
 +
=== Setting an element ===
 +
 
 +
[[private]] _myMap = [[createHashMap]];
 +
_myMap [[set]] [1, "hello there"]; {{cc|_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]; {{cc|_myMap is now [["a",1337], ["b",2]] and _overwritten is true}}
 +
 
 +
Keys inside the Hashmap need to be of a supported type, not all types are supported.
 +
 
 +
GameScalar | GameBool | GameString | GameArray | GameCode | GameSide | GameConfig | GameNamespace | GameNaN
 +
#TODO
 +
#TODO HashMapKey type
 +
 
 +
 
 +
=== Getting an element ===
 +
 
 +
Values are retrieved by their key:
 +
 
 +
[[private]] _myMap = [[createHashMapFromArray]] [["a",1], ["b",2]];
 +
_myMap [[get]] "a"; {{cc|returns 1}}
 +
_myMap [[get]] "z"; {{cc|returns [[Nothing]]}}
 +
_myMap [[get]] ["z", "NotFound"]; {{cc|returns "NotFound"}}
 +
 
 +
=== 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 ; {{cc|returns 2}}
 +
 
 +
=== HashMap Copy ===
 +
 
 +
[[private]] _myMap = [[createHashMapFromArray]] [["a",1], ["b",2]];
 +
[[private]] _myNewMap = _myMap;
 +
_myMap [[set]] ["a", 1337];
 +
_myNewMap [[get]] "a"; {{cc|will be 1337}}
 +
 
 +
In order to avoid this behaviour, '''copy''' the HashMap with [[+|+ (plus)]]:
 +
 
 +
{{cc|making copy}}
 +
[[private]] _myMap = [[createHashMapFromArray]] [["a",1], ["b",2]];
 +
[[private]] _myNewMap = [[+]]_myMap;
 +
_myMap [[set]] ["a", 1337];
 +
_myNewMap [[get]] "a"; {{cc|still 1}}
 +
 
 +
[[Array|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"; {{cc|_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
 +
 
 +
 
 +
 
 +
== See Also ==
 +
 
 +
* [[:Category:HashMaps|HashMaps]]
 +
 
 +
[[Category: Data Types]]

Revision as of 13:02, 14 December 2020

Template:SideTOC A HashMap is a container storing Key-Value pairs which is very efficient with many entries that have different keys. As a HashMap is a container, it stores some traits/properties with Arrays This container was added with v2.01 #TODO make a icon thingy or note thingy

See also: HashMaps

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]

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

Keys inside the Hashmap need to be of a supported type, not all types are supported.

GameScalar | GameBool | GameString | GameArray | GameCode | GameSide | GameConfig | GameNamespace | GameNaN

  1. TODO
  2. TODO HashMapKey type


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 get ["z", "NotFound"];	// returns "NotFound"

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

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


See Also