Map
Description
An associative array of Variant keys and values.
A Map contains a set of keys. Each key has an associated value. You can use the key to retrieve the value. For example:Map map;
map[5] = 10;
int x = map[5]; // x is 10
This example demonstrates that the Map uses the [] operator,
like the Array. However the Map's [] operator has two important differences:
- A Map can use any value as a key:
Map map; map["Hello"] = "world"; map[Model.find("Processor1")] = 10;
- The Map's [] will always add the value in the [] to the Map.
Map map; map[1]; map[2]; map[3]; // The map now has three keys in it. // The default value associated with // each key is a null variant.
A Variant can hold a Map value. For more information, please see the Variant topic.
Dynamic Properties
A Map can use dynamic properties to interact with string keys:
Map map;
map.Key1 = 1; // identical to map["Key1"] = 1;
map.MyKeyName = 3; // identical to map["MyKeyName"] = 3;
return map.Key1; // NOT identical to map["Key1"]
When you use dynamic properties to write to the map, the property is asserted. This is the same behavior as using the [] operator. However, when you read the map with dynamic properties, you will get an exception if that key is not present.
Examining a Map
In order to determine if a key is in the map, you can use the find() method:
var iter = map.find(3);
if (iter) {
// the key is contained in the map
print(iter.key, iter.value);
} else {
// the key is not contained in the map
print("key not found");
}
In order to examine each element of a map, you can use the begin() and end() methods in a for loop:
for (var iter = map.begin(); iter != map.end(); iter++) {
print(iter.key, iter.value);
}
As an alternative, you could use the keys property to access all the keys in the array, and use a for loop with that array:
Array keys = map.keys;
for (int i = 1; i <= keys.length; i++) {
print(keys[i], map[keys[i]]);
}
Note that the keys property constructs a new array, with a copy of all the keys in the map.
begin(), end(), and find()
The methods begin(), end(), and find() all return a map iterator object. This object has the following properties and operators:
- key - the key referenced by this iterator.
- value - the value associated with the key referenced by this iterator.
- operator bool() - casting the iterator as a bool will return true if the iterator is valid, and false if it is not.
- operator++ - incrementing the iterator will move it to the next key in the map. If the iterator is at the end of the map, this operator invalidates the iterator.
Nodes as Keys
You can use a treenode as a key. You can also use a container (a Map or an Array) that contains a treenode as a key. However, if that treenode (e.g. a flowitem) is destroyed, then that key is said to be lost. The keys array will not include those keys, and an iterator objects (returned from begin(), end(), and find()) will skip those values.
Key Ordering
The Map class is a hash map, so keys in the map are in not guaranteed to be in any order. They are not sorted by comparison, and they are not in insertion order. Even if it appears that you can depend on some particular ordering, that ordering could easily change in a bug fix release or new version of FlexSim.
Properties
keys | Returns an array of all key values in the map. |
stringKeys | Dynamically gets and sets the value for string keys. |
values | Returns an aray of all associated values in the map. |
Methods
begin | Returns an iterator to the first key/value pair in the map. |
clear | Removes all keys and associated values from the Map. |
clone | Returns a deep copy of the Map. |
end | Returns an invalid iterator. |
find | Returns an iterator to the given key if it is present, or an invalid iterator if the key is not present. |
remove | Removes the given key and its associated value from the map if it is present. |
Operators
!= | Compares two maps for equality, returning true if they are unequal. |
[] | Asserts the given key, and returns its associated value. |
= | Assigns this map to the same data as the given map. |
== | Compares two maps for equality. |
Details
Map.stringKeys
readonly stringKeys
Description
Dynamically gets and sets the value for string keys.
Allows getting and setting the value for string keys, similar to using labels:// asserts the key "MyKey" and sets its value to 5
map.MyKey = 5;
// reads the value for the key "SKU_1"
// throws if "SKU_1" is not a key in the map
Variant value = map.SKU_1;
Map.end()
end( ) |
Returns
An invalid iterator |
Description
Returns an invalid iterator.
This method is usually used as part of a for-loop:for (var iter = map.begin(); iter != map.end(); iter++) { /*... */}
When the iterator used in the loop advances past the end of the map, it becomes
invalid, and comparing it to the end() iterator will return true.Map.find()
find( Variant key ) |
Parameters
key | The key to check for in the map |
Returns
An iterator, invalid if the key is not in the map. |
Description
Returns an iterator to the given key if it is present, or an invalid iterator if the key is not present.
This method does not add the given key to the map, and so can be used to check for a key without adding it.Map.operator []
Variant operator []( Variant key ) |
Variant operator []( Map key ) |
Parameters
key | The key to use in retrieving an associated value |
Returns
Variant | The value associated with the key |
Description
Asserts the given key, and returns its associated value.
If the key is not present in the map, it is added, and its associated value is set to a null Variant. The value is returned by reference, so you can modify it:map[10] += 1; // increments the value for key 10 by 1
Map.operator ==
int operator ==( Map ) |
Parameters
The map to compare this map to |
Returns
int | True if the maps are equal |
Description
Compares two maps for equality.
Two maps are equal if the both point to the same Map object, or if they both have the same set of keys, and for all keys, the values are equal.