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

Do no remove, this fixes the anchor on doc.flexsim.com

Map.keys

readonly Array keys

Description

Returns an array of all key values in the map.

The array is a new copy of all keys values. If keys and values are both accessed without any intervening insertions or removals, the resulting arrays will be ordered the same way.
Do no remove, this fixes the anchor on doc.flexsim.com

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;
Do no remove, this fixes the anchor on doc.flexsim.com

Map.values

readonly Array values

Description

Returns an aray of all associated values in the map.

he array is a new copy of all associated values. If keys and values are both accessed without any intervening insertions or removals, the resulting arrays will be ordered the same way.
Do no remove, this fixes the anchor on doc.flexsim.com

Map.begin()

begin( )

Returns

An iterator to the first key/value pair in the map

Description

Returns an iterator to the first key/value pair in the map.

If the map is empty, then this method returns an iterator equal to the end()
Do no remove, this fixes the anchor on doc.flexsim.com

Map.clear()

clear( )

Description

Removes all keys and associated values from the Map.

Do no remove, this fixes the anchor on doc.flexsim.com

Map.clone()

Map clone( )

Returns

Map A copy of the map

Description

Returns a deep copy of the Map.

Map map1;
Map map2 = map1; // map2 points at the same map as map1
map1[10] = 2; // map2 can access the key 10
Map map3 = map1.clone();
map3[20]; // does not affect map1 or map2
Do no remove, this fixes the anchor on doc.flexsim.com

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.
Do no remove, this fixes the anchor on doc.flexsim.com

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.
Do no remove, this fixes the anchor on doc.flexsim.com

Map.remove()

int remove( Variant key )

Parameters

key The key to remove

Returns

int True if the key was removed, false if the key was not present.

Description

Removes the given key and its associated value from the map if it is present.

Do no remove, this fixes the anchor on doc.flexsim.com

Map.operator !=

int operator !=( Map )

Parameters

The map to compare to this map

Returns

int True if the maps are unequal

Description

Compares two maps for equality, returning true if they are unequal.

Returns the opposite of the == operator.
Do no remove, this fixes the anchor on doc.flexsim.com

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
Do no remove, this fixes the anchor on doc.flexsim.com

Map.operator =

Map operator =( Variant )

Parameters

The map to assign this map to

Returns

Map The assigned map

Description

Assigns this map to the same data as the given map.

After the assignment, both map variables will point at the same Map object. This is a shallow assignment.
Do no remove, this fixes the anchor on doc.flexsim.com

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.