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.