Variant
Description
A type that can hold either a number, a string, a treenode or an Array.
The Variant class is an essential type by which data is exchanged between various functionalities in FlexSim. As such, the Variant represents a "jack of all trades" that can hold several different types of data. It can be a number type, holding a number value. It can be a string type, holding text data. It can be a treenode type, holding a reference to a node in FlexSim's tree. It can be an Array type, holding an array of Variants. And finally, it can be a null variant meaning it is none of the other types.
Method/Property Forwarding
Since the Variant is just a flexible container for other data types, its methods and properties are just forwarders to the various methods and properties of the types that the Variant holds. For example, if you have a Variant holding a treenode, you can use all of the methods and properties on a treenode directly on the Variant without having to cast to a treenode with the as() keyword.
Variant node = param(1);
node.name = "Object1";
node.value = 5;The only property that is exclusive to the Variant is type, which tells you what type of data is held by a Variant. All other properties and methods simply forward to the associated method or property of the held class. If the Variant does not hold the associated type, then calling the type's method will result in an exception. For example, if a Variant has a number, and you call the find() method on it, FlexScript will throw an exception.
Casting
Variant will cast to any of its target types without throwing an exception. If the Variant does not hold the target type, it will just give a null-or-similar result. This means a NULL treenode, empty string, empty Array, or 0.0 number.
Variant num = 1;
string asString = num; // empty string
Variant str = "Hello";
double asNum = str; // 0.0To determine the type of data that is held by a Variant, use the type property, or use the is() keyword.
Variants as Arrays
The Variant implements special logic associated with arrays in that you can treat a Variant like an Array even if it does not hold array data. If a Variant holds, for example, a string, you can treat the Variant as if it were a 1-length Array with a string as its first element.
Variant val = "Hello";
int len = val.length; // len = 1
return val[len]; // returns "Hello";Also, if you cast a Variant into a non-array type, and the Variant is in fact an Array, the cast operation will return the first element of the array. Thus you can even treat an Array Variant as a non-array type.
Variant myArray = ["Hello", "World"];
string myString = myArray;
return myString; // returns "Hello"These capabilities are especially useful in Process Flow, where you are often dealing with label values that may or may not contain array data, but you want to interface with those data in a consistent manner.
Null Values
To check if a Variant is null you can compare the value with the special keyword nullvar or compare its type with the VAR_TYPE_NULL macro.
Variant val;
val == nullvar //true
val.type == VAR_TYPE_NULL // trueWhere this gets more complicated is when dealing with treenode type Variants returned by other properies. See the discussion of treenode null values.
Other data types do not have null types but have an empty type that corresponds to that type:
string emptyString = "";
int emptyInt = 0;
double emptyDouble = 0.0;
Array emptyArray = [];Properties
| dataType | Gets/sets the dataType property on a treenode Variant. |
| first | Gets the first subnode of a treenode Variant. |
| labels | Accesses the labels of a treenode Variant. |
| last | Gets the last subnode of a treenode Variant. |
| length | Gets/sets the Array length of a Variant. |
| name | Gets/sets the name of a treenode Variant. |
| next | Gets the next node of a treenode Variant. |
| prev | Gets the next node of a treenode Variant. |
| rank | Gets/sets the rank of a treenode Variant. |
| subnodes | Accesses the subnodes of a treenode Variant. |
| type | Gets a Variant's type, one of VAR_TYPE_NUMBER, VAR_TYPE_STRING, VAR_TYPE_NODE, or VAR_TYPE_ARRAY |
| up | Gets/sets the parent of a treenode Variant. |
| value | Gets/sets the data value of a treenode Variant. |
Methods
| append | Appends another Variant to this Variant. |
| clone | Clones a Variant. |
| concat | Concatenates two Variants into an Array. |
| destroy | Destroys a treenode Variant. |
| endsWith | Queries whether a string Variant ends with a defined string. |
| evaluate | Evaluates a treenode Variant |
| fill | Fills an Array Variant with a defined value. |
| find | Finds a node in a treenode Variant's sub-tree by path. |
| getPath | Gets the path of a treenode Variant. |
| includes | Queries whether a string Variant includes a string. |
| indexOf | Gets the index of an element in an Array Variant. |
| join | Joins an Array Variant into a string. |
| match | Matches a reqular expression on a string Variant. |
| pop | Pops an element from an Array Variant. |
| push | Pushes a value onto an Array Variant. |
| repeat | Repeats a string Variant a number of times. |
| replace | Replaces text in a string Variant |
| reverse | Reverses an Array Variant |
| shift | Shifts (pops) an element from the front of an Array Variant. |
| slice | Returns a new Array made up of a subsection of an Array Variant. |
| splice | Removes and/or inserts elements into an Array Variant. |
| split | Splits a string Variant into an Array. |
| startsWith | Queries if a string Variant starts with a defined string. |
| toLowerCase | Creates a lower case string from a string Variant. |
| toUpperCase | Creates an upper case string from a string Variant. |
| trim | Trims white space off of the ends of a string Variant. |
| unshift | Unshifts (pushes) a value onto the front of an Array Variant. |
Operators
| - | Subtracts two numbers. |
| -- | Decrements a number Variant. |
| ! | Tests if a Variant is either a null Variant, a NULL treenode, or a 0.0 number. |
| != | Tests if a Variant is not equal to another value. |
| * | Multiplies two numbers. |
| / | Divides two numbers. |
| [] | Accesses an element of an Array Variant. |
| + | Adds two numbers. |
| ++ | Increments a number Variant |
| += | Increments a number Variant by a defined value, or appends a string to the current string Variant. |
| < | Tests if a Variant is less than a number. |
| <= | Tests if a Variant is less than or equal to a number. |
| -= | Decrements a number Variant by a defined value. |
| == | Tests if two values are equal to each other. |
| > | Tests if a Variant is greater than a number. |
| >= | Tests if a Variant is greater than or equal to a number. |
Details
Variant.length
int length
Description
Gets/sets the Array length of a Variant.
If the Variant is already an Array type, this will forward to Array.length. If the Variant is a null Variant, length will return 0. If it is a number, string, or treenode type, length will return 1.
Variant myVar; // initialized as null Variant
myVar.length; // returns 0
myVar = 5; // set to number type
myVar.length; // returns 1If length is set, the Variant will convert itself into an Array, and forward to Array.length
Variant myArray = "Hello";
myArray.length = 2; // converts to Array and sets Array length to 2.Variant.append()
| Variant append( Variant val ) |
Parameters
| val | The value to append to this Variant. |
Returns
| Variant | The modified Variant |
Description
Appends another Variant to this Variant.
If this Variant is already an Array, this forwards to Array.append(). If the Variant is a null Variant, it will become val. If it is a non-array type, it will convert itself into an Array, and forward to Array.append().
Variant.push()
| Variant push( Variant value ) |
Returns
| Variant | The modified Variant. |
Description
Pushes a value onto an Array Variant.
Forwards to Array.push(). If the Variant is a non-array value, it will convert itself into an Array, and forward to Array.push(). If it is a null Variant, it will become the passed value (not an Array).
Variant.splice()
| Variant splice( int fromIndex , int removeCount ) |
| Variant splice( int fromIndex , int removeCount , Array insertArray ) |
Returns
| Variant | The modified Variant |
Description
Removes and/or inserts elements into an Array Variant.
Forwards to Array.splice(). If the Variant is not an Array, it will make itself into an Array and forward to Array.splice().
Variant.startsWith()
| int startsWith( string str ) |
Description
Queries if a string Variant starts with a defined string.
Forwards to string.startsWith(). An exception is thrown if the Variant is not a string type.
Variant.toLowerCase()
| string toLowerCase( ) |
Description
Creates a lower case string from a string Variant.
Forwards to string.toLowerCase(). An exception is thrown if the Variant is not a string type.
Variant.toUpperCase()
| string toUpperCase( ) |
Description
Creates an upper case string from a string Variant.
Forwards to string.toUpperCase(). An exception is thrown if the Variant is not a string type.
Variant.unshift()
| Variant unshift( Variant value ) |
Returns
| Variant | The modified Variant. |
Description
Unshifts (pushes) a value onto the front of an Array Variant.
Forwards to Array.unshift(). If the Variant is a non-array value, it will convert itself into an Array, and forward to Array.unshift(). If it is a null Variant, it will become the passed value (not an Array).
Variant.operator -
| double operator -( double value ) |
| double operator -( Variant value ) |
Parameters
| value | The value to subtract from the Variant |
Returns
| double | The result of the subtraction. |
Description
Subtracts two numbers.
The following example uses treenode.labelProperties to access an object's label value.
double myVal = current.labelValue - 2;Variant.operator --
| double operator --( ) |
Description
Decrements a number Variant.
The following example uses treenode.labelProperties to decrement an object's label value.
current.labelValue--;Variant.operator !
| int operator !( ) |
Returns
| int | True if the Variant is a null Variant, a NULL treenode, or the number 0.0. False otherwise. |
Description
Tests if a Variant is either a null Variant, a NULL treenode, or a 0.0 number.
The following example uses treenode.labelProperties to compare an object's label value.
if (!current.labelValue) {
...
}Variant.operator !=
| int operator !=( int value ) |
| int operator !=( double value ) |
| int operator !=( string value ) |
| int operator !=( treenode value ) |
| int operator !=( Variant value ) |
Parameters
| value | The value to compare against. |
Returns
| int | True if the Variant is not equal to value, false otherwise. |
Description
Tests if a Variant is not equal to another value.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue != 5) {
...
}Variant.operator *
| double operator *( double value ) |
| double operator *( Variant value ) |
Parameters
| value | The value to multiply by. |
Returns
| double | The multiplication product of the two values. |
Description
Multiplies two numbers.
The following example uses treenode.labelProperties to access an object's label value.
double myVal = current.labelValue * 2;Variant.operator /
| double operator /( double value ) |
| double operator /( Variant value ) |
Parameters
| value | The value to divide the Variant by. |
Returns
| double | The result of the division. |
Description
Divides two numbers.
The following example uses treenode.labelProperties to access an object's label value.
double myVal = current.labelValue / 2;Variant.operator []
| Variant operator []( int index ) |
Parameters
| index | The index of the array element. |
Returns
| Variant | The array element at the specified index. |
Description
Accesses an element of an Array Variant.
Forwards to the Array [] operator.
The Variant implements special logic associated with arrays in that you can treat a Variant like an Array even if it does not hold array data. If a Variant holds, for example, a string, you can treat the Variant as if it were a 1-length Array with a string as its first element.
Variant val = "Hello";
int len = val.length; // len = 1
return val[len]; // returns "Hello";Variant.operator +
| double operator +( double value ) |
| Variant operator +( Variant value ) |
Parameters
| value | The value to add to the Variant. |
Returns
| double | The addition result. |
Description
Adds two numbers.
The following example uses treenode.labelProperties to access an object's label value.
double myVal = current.labelValue + 2;Variant.operator ++
| double operator ++( ) |
Description
Increments a number Variant
The following example uses treenode.labelProperties to increment an object's label value.
current.labelValue++;Variant.operator +=
| Variant operator +=( double value ) |
| Variant operator +=( string value ) |
Parameters
| value | The value to add to the Variant. |
Description
Increments a number Variant by a defined value, or appends a string to the current string Variant.
If both operands are strings, then the Variant will append value to itself. If both are numbers, the Variant will increment its value by value.
The following example uses treenode.labelProperties to access an object's label value.
double myVal = current.labelValue - 2;Variant.operator <
| int operator <( int value ) |
| int operator <( double value ) |
| int operator <( Variant value ) |
Parameters
| value |
Returns
| int |
Description
Tests if a Variant is less than a number.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue < 5) {
...
}Variant.operator <=
| int operator <=( int value ) |
| int operator <=( double value ) |
| int operator <=( Variant value ) |
Parameters
| value |
Returns
| int |
Description
Tests if a Variant is less than or equal to a number.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue <= 5) {
...
}Variant.operator -=
| Variant operator -=( double value ) |
Parameters
| value | The value to decrement the Variant by. |
Description
Decrements a number Variant by a defined value.
The following example uses treenode.labelProperties to decrement an object's label value.
current.labelValue -= 2;Variant.operator ==
| int operator ==( int value ) |
| int operator ==( double value ) |
| int operator ==( string value ) |
| int operator ==( treenode value ) |
| int operator ==( Variant value ) |
Parameters
| value | The value to compare against. |
Returns
| int | True if the Variant is equal to value, false otherwise. |
Description
Tests if two values are equal to each other.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue == 5) {
...
}Variant.operator >
| int operator >( int value ) |
| int operator >( double value ) |
| int operator >( Variant value ) |
Parameters
| value | The value to compare against. |
Returns
| int | True if the Variant is greater than value, false otherwise. |
Description
Tests if a Variant is greater than a number.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue > 5) {
...
}Variant.operator >=
| int operator >=( int value ) |
| int operator >=( double value ) |
| int operator >=( Variant value ) |
Parameters
| value | The value to compare against. |
Returns
| int | True if the Variant is greater than or equal to value, false otherwise. |
Description
Tests if a Variant is greater than or equal to a number.
The following example uses treenode.labelProperties to compare an object's label value.
if (current.labelValue >= 5) {
...
}