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.0

To 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 // true

Where 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

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

Variant.dataType

int dataType

Description

Gets/sets the dataType property on a treenode Variant.

An exception is thrown if the Variant is not a treenode type.

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

Variant.first

treenode first

Description

Gets the first subnode of a treenode Variant.

Forwards to treenode.first. An exception is thrown if the Variant is not a treenode type.

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

Variant.labels

readonly labels

Description

Accesses the labels of a treenode Variant.

Forwards to treenode.labels. An exception is thrown if the Variant is not a treenode type.

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

Variant.last

treenode last

Description

Gets the last subnode of a treenode Variant.

Forwards to treenode.last. An exception is thrown if the Variant is not a treenode type.

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

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 1

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

Variant.name

string name

Description

Gets/sets the name of a treenode Variant.

Forwards to treenode.name. An exception is thrown if the Variant is not a treenode type.

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

Variant.next

readonly treenode next

Description

Gets the next node of a treenode Variant.

Forwards to treenode.next. An exception is thrown if the Variant is not a treenode type.

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

Variant.prev

readonly treenode prev

Description

Gets the next node of a treenode Variant.

Forwards to treenode.prev. An exception is thrown if the Variant is not a treenode type.

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

Variant.rank

int rank

Description

Gets/sets the rank of a treenode Variant.

Forwards to treenode.rank. An exception is thrown if the Variant is not a treenode type.

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

Variant.subnodes

readonly subnodes

Description

Accesses the subnodes of a treenode Variant.

Forwards to treenode.subnodes. An exception is thrown if the Variant is not a treenode type.

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

Variant.type

readonly int type

Description

Gets a Variant's type, one of VAR_TYPE_NUMBER, VAR_TYPE_STRING, VAR_TYPE_NODE, or VAR_TYPE_ARRAY

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

Variant.up

treenode up

Description

Gets/sets the parent of a treenode Variant.

Forwards to treenode.up. An exception is thrown if the Variant is not a treenode type.

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

Variant.value

Variant value

Description

Gets/sets the data value of a treenode Variant.

Forwards to treenode.value. An exception is thrown if the Variant is not a treenode type.

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

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().

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

Variant.clone()

Variant clone( )

Returns

Variant A clone of the Variant.

Description

Clones a Variant.

If the Variant is an Array type, this forwards to Array.clone(). Otherwise it just returns a copy of its value.

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

Variant.concat()

Array concat( Array other )

Parameters

other The Array to concatenate onto the end of this Variant.

Returns

Array The resulting Array.

Description

Concatenates two Variants into an Array.

Forwards to Array.concat().

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

Variant.destroy()

destroy( )

Description

Destroys a treenode Variant.

Forwards to treenode.destroy(). An exception is thrown if the Variant is not a treenode type.

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

Variant.endsWith()

int endsWith( string str )

Description

Queries whether a string Variant ends with a defined string.

Forwards to string.endsWith(). An exception is thrown if the Variant is not a string type.

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

Variant.evaluate()

Variant evaluate( )
Variant evaluate( Variant p1 ... p20 )

Parameters

p1-p20 The parameters to pass to the evaluation.

Description

Evaluates a treenode Variant

Forwards to treenode.evaluate(). An exception is thrown if the Variant is not a treenode type.

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

Variant.fill()

Variant fill( Variant value )

Description

Fills an Array Variant with a defined value.

Forwards to Array.fill(). If the Variant is not already an Array, it simply sets its value to the passed value.

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

Variant.find()

treenode find( string path )

Description

Finds a node in a treenode Variant's sub-tree by path.

Forwards to treenode.find(). An exception is thrown if the Variant is not a treenode type.

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

Variant.getPath()

string getPath( treenode relativeTo = 0 , int byName = 1 )

Description

Gets the path of a treenode Variant.

Forwards to treenode.getPath(). An exception is thrown if the Variant is not a treenode type.

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

Variant.includes()

int includes( string str )

Description

Queries whether a string Variant includes a string.

Forwards to string.includes(). An exception is thrown if the Variant is not a string type.

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

Variant.indexOf()

int indexOf( Variant )

Description

Gets the index of an element in an Array Variant.

Forwards to Array.indexOf(). If the Variant is not an Array, it is treated as an array of length 1.

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

Variant.join()

string join( string separator = 0 )

Description

Joins an Array Variant into a string.

Forwards to Array.join(). If the Variant is not already an Array, it will create a new Array from itself, and call join on that Array.

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

Variant.match()

Description

Matches a reqular expression on a string Variant.

Forwards to string.match(). An exception is thrown if the Variant is not a string type.

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

Variant.pop()

Variant pop( )

Description

Pops an element from an Array Variant.

Forwards to Array.pop(). If the Variant is not an Array, it will convert itself into a null Variant, and return its original value.

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

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).

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

Variant.repeat()

string repeat( int numRepeats )

Description

Repeats a string Variant a number of times.

Forwards to string.repeat(). An exception is thrown if the Variant is not a string type.

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

Variant.replace()

string replace( string findStr , string replaceWith )

Parameters

findStr
replaceWith
findPattern

Description

Replaces text in a string Variant

Forwards to string.replace(). An exception is thrown if the Variant is not a string type.

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

Variant.reverse()

Variant reverse( )

Description

Reverses an Array Variant

Forwards to Array.reverse(). 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).

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

Variant.shift()

Variant shift( )

Description

Shifts (pops) an element from the front of an Array Variant.

Forwards to Array.shift(). If the Variant is not an Array, it will convert itself into a null Variant, and return its original value.

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

Variant.slice()

Array slice( int fromIndex , int toIndex )

Description

Returns a new Array made up of a subsection of an Array Variant.

Forwards to Array.slice(). If the Variant is not an Array, it will create an Array from itself and forward to Array.slice().

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

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().

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

Variant.split()

Array split( string delimiter , int limit = -1 )

Description

Splits a string Variant into an Array.

Forwards to string.split(). An exception is thrown if the Variant is not a string type.

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

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.

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

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.

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

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.

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

Variant.trim()

Variant trim( )

Description

Trims white space off of the ends of a string Variant.

Forwards to string.trim(). An exception is thrown if the Variant is not a string type.

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

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).

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

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

Variant.operator --

double operator --( )

Description

Decrements a number Variant.

The following example uses treenode.labelProperties to decrement an object's label value.

current.labelValue--;
Do no remove, this fixes the anchor on doc.flexsim.com

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

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

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

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

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

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

Variant.operator ++

double operator ++( )

Description

Increments a number Variant

The following example uses treenode.labelProperties to increment an object's label value.

current.labelValue++;
Do no remove, this fixes the anchor on doc.flexsim.com

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

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

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

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

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

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

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) {
	...
}