Operators

The operator sections set out below follow the language's preference rules. The earlier the operator appears in the list, the higher the precedence and the earlier the listed operators will be evaluated.

Operators (1), Grouping & Indexing

( )

• Expression grouping.
• In common with most programming languages Trainzscript carries out arithmetical operations in the order defined by operator precedence rules.
• 3 + 2 * 12 - 7 would return 20, because multiplication is of higher precedence than addition and subtraction.
• You can force the compiler to change this sequence and make your intentions crystal clear by declaring this as ((3 + 2) * 12) - 7.

[ i ]

• Array and string indexing.
• Arrays are zero based and arrayName[0] will represent the first element.
• Similarly arrayName[arrayName.size() - 1] will represent the last element.
• A call to a value outside the range [0 … size()-1] will generate an exception.
• This notation can also be used to return a single character from a string.

intArray[intArray.size()] = 5    // will add the new value of 5 to the end of the array.

[ i , j ]

• Array and String range index.
• The expression string[0,string.size()] will return the entire string.
• The integers i and j are best thought of as 'cursor' positions where 0 is before the first element and size() is after the last element.
• If i is omitted the range will start at the beginning of the array,
• If j is omitted the range will end after the end of the array.
• To return a single element both i and j are required.
• Given the declaration string s = "abcde"

s[,3]  = "abc"
s[2,3] = "c"
s[2,]  = "cde"

intArray[2,3] = null             // will delete the third element of the array.

[ i , ]

• Indexes from i to the end of the string or array inclusively.

[ , j ]

• Indexes from the start of the string or array to element b inclusively.

.

• Dereference operator as in GetAsset().GetConfigSoup();

!

• Not Operator

!true = false
!vehicle = null

Operators (2), Incremental and Unary Operators

++

• Increments a numeric value by 1.
• Often used for control variables in loops:

for(n = 0; n < list.size(); n++) {
   DoStuffWith(n);
}

• Increments n by 1 on each pass through the loop.

--

• Decrements a numeric value by 1.
• Often used for control variables in loops:

n = list.size() - 1;
while(n >= 0) {
   DoStuffWith(n);
   n--;
}

• Decrements n by 1 on each pass through the loop.

+

• Unary plus.
• Used to denote that a value is positive.

-

• Unary minus.
• Used to denote that a value is negative.

Operators (3), Casts

(bool)

• Boolean type cast.

(bool) 0 = false
(bool) 0.0 = false
(bool) n = true     //where n is greater than zero

(int)

• Integer type cast.

(int) 5.0 = 5
(int) true = 1

(float)

• Float type cast.

(float) 100 = 100.0
(float) false = 0.0

(string)

• String type cast.

(string) 1 = "1"
(string) 0.99 = "0.99"
(string) false = "false";

(reference)

• Class type cast.

How is this used and how is it different from cast<Class>?

cast

• Dynamic cast.
• Returns null if the reference cannot be converted to the class specified by className.
• Note that ancestors of the specified class will be returned.

Vehicle vehicle = cast<Vehicle>msg.src;

MeshObject meshObject;
GameObject gameObject = cast<GameObject>meshObject;  // returns meshObject if the object exists, null otherwise

size()

• Returns the number of members of an array or the length of a string.
• In the case of an array this does not necessarily mean that all (or any) of the members actually contain values.

given string s = "abcde";
s.size() = 5;

int[] numbers = new int[5];       // creates an empty array of 5 integers
numbers.size() = 5;

copy()

• Creates a copy of an array or string.
• This is different from a simple assignment which points a variable to the same memory address as an existing variable.
• Array.copy() or string.copy() creates an additional copy of the data.

int[] numbers = new int[5];
int[] moreNumbers;

moreNumbers.copy(numbers);  // duplicates numbers 

isclass()

• Used in the declaration of a new class identifier

class MyScript isclass Vehicle {
  classMethods();
};

• Used to test whether a given reference is to a specific class.

given the declaration: 
TrackLoadInfo info = new TrackLoadInfo();

info.isclass(TrackLoadInfo);               // returns true

new

• Creates a new instance of the specified type.

int[] numbers = new int[4];                // creates an integer array containing 4 members. 
TrackLoadInfo info = new TrackLoadInfo();  // creates a new instance of the TrackLoadInfo class.

• new does not initialise the members.
• GameObject classes cannot be created using new.

Operators (4), Multiplication & Division

*

• Multiplication.
• If both terms are integers the result will be an integer.
• If either term is a float the result will be a float.

2 * 5 = 10;
2 * 5.0 = 10.0;

/

• Division.
• If both terms are integers the result will be an integer, possibly with a remainder.
• If either term is a float the result will be a float.

10 / 5 = 2;
10 / 5.0 = 2.0;
10 / 6 = 1;

%

• Remainder or modulus operator.
• Returns the remainder from an integer division.

5 % 2 = 1;
105 % 50 = 5;
105 % 100 = 5;

Operators (5), Addition & Subtraction

+

• Addition
• If both terms are integers the result will be an integer.
• If either term is a float the result will be a float.

1 + 1 = 2;
1 + 1.0 = 2.0;

-

• Subtraction
• If both terms are integers the result will be an integer.
• If either term is a float the result will be a float.

2 - 1 = 1;
2 - 1.0 = 1.0;

Operators (6), Shifts

<<

• Shift Left
• Bitwise operator moves all of the binary values to the left by the number of places specified in the second term.
• Binary zero is appended.
• Provided there is no overflow the result is a doubling of the value for each shift.

8 << 1 = 16
8 << 2 = 32

>>

• Shift Right
• Bitwise operator moves all of the binary values one place to the right by the number of places specified in the second term.
• Binary zero is prepended and any displaced bits are discarded.
• The result is an integral halving of the value for each shift.

8 >> 1 = 4
9 >> 2 = 2

Operators (7), Comparisons

<

• Comparison operator which can be used on string, float, integer and bool values.
• Returns true if the first term is less than the second.

1 < 2 = true;
false < false = false;
"abc" < "def" = true;

<=

• Comparison operator which can be used on string, float, integer and bool values.
• Returns true if the first term is less than or equal to the second.

1 <= 2 = true;
false <= false = true;
"abc" <= "def" = true;

>

• Comparison operator which can be used on string, float, integer and bool values.
• Returns true if the first term is greater than the second.

1 > 2 = false;
true > false = true;
"abc" > "def" = false;

>=

• Comparison operator which can be used on string, float, integer and bool values.
• Returns true if the first term is greater than or equal to the second.

1 >= 2 = false;
true >= true = true;
"abc" >= "def" = false;

Operators (8), Equality

==

• Comparison operator which can be used on string, float, integer and bool values and on object references.
• Returns true if the first and second terms are equal or if they evaluate to the same object.

int a = 0;
int b = 0;
a == b;  // returns true

• Note that a = b is an assignment and will always return true. Mistyping = for == is one of the most common semantic errors in Trainzscript.

!=

• Comparison operator which can be used on string, float, integer and bool values and on object references.
• Returns true if the first and second terms are not equal and do not evaluate to the same object.

int a = 0;
int b = 0;
a != b;  // returns false

Operators (9), Bitwise Operators

&

• Bitwise AND
• Performs a bit by bit comparison of two integers and returns a new value.
• Each bit in the result is set if BOTH of the corresponding bits in the arguments are set

  0000 1111
& 0001 0111
= 0000 0111

15 & 23 = 7

^

• Bitwise XOR
• Performs a bit by bit comparison of two integers and returns a new value.
• Each bit in the result is set if EITHER BUT NOT BOTH of the corresponding bits in the arguments are set

  0000 1111
^ 0001 0111
= 0001 1000

15 ^ 23 = 24

¦

• Bitwise OR
• Performs a bit by bit comparison of two integers and returns a new value.
• Each bit in the result is set if EITHER of the corresponding bits in the arguments are set

  0000 1111
| 0001 0111
= 0001 1111

15 | 23 = 31

~

• Bitwise Inverse Operator for integer values
• Takes the binary representation of the integer and inverts each bit.
• Useful in masking out values from bitfields (eg. flags &= ~SOME_FLAG; switches off the SOME_FLAG bit from 'flags')

~0011 1101 = 1100 0010
~1000 0100 = 0111 1011

~0   = -1
~255 = -256
~5   = -6

Operators (10), Logical Operators

and

• Logical AND
• Enables multiple boolean expressions to be combined.

if (msg.minor == "Enter" and doorsOpen)

or

• Logical OR
• Enables multiple boolean expressions to be combined.

if (msg.minor == "Enter" or doorsOpen)
if ((msg.minor == "Enter" and doorsOpen) or (msg.minor == "Leave" and !doorsOpen))

Operators (11), Assignment

=

• Assignment Operator

a = 1;
Train train = World.GetTrainList()[0];

Apparently there are 2 types in Trainz gamescript that don't support direct assignment of themselves: arrays and strings. When arrays and strings appear singlely on the right hand side in assignment statements only a reference to the original is created. So in effect only the original copy exists. The original name and the new name both reference the same object. To make an assignment to a new object that is a copy of the original you can use the copy() operator.

,

• Expression or parameter separator.