Latest revision as of 00:23, 29 December 2020

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.

• TrainzScript Language Reference
  • Comments & Delineation
  • TrainzScript Keywords
  • Operators
  • Types

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.

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

• 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 i is the first element and j is one beyond the last element.
• If i is omitted the range will start at the beginning of the array (index 0).
• If j is omitted the range will end after the end of the array (.size()).
• To return a single element other than the first or last, 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.

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

s[2,]  = "cde"

• Indexes from the start of the string or array to element j-1 inclusively.

s[,3]  = "abc"

• Dereference operator

GetAsset().GetConfigSoup();

• The GetConfigSoup() method to be called is the method defined for the class GetAsset().

• 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

• Boolean type cast.

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

• Integer type cast. Floats will be truncated (rounded down).

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

• Float type cast.

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

• String type cast.

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

• Class type cast.

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

• 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

• 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;

• 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 

• 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

• 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.
• If either term is a string the result will be a string.

1 + 1 = 2;
1 + 1.0 = 2.0;
"a" + "b" = "ab";
"a" + 1 = "a1";

• 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

• Is less than.
• 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;

• Is less than or equal.
• 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;

• Is greater than.
• 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;

• Is greater than or equal.
• 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

• Is equal.
• 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.

• Is not equal.
• 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
• 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

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

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

• 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];

The assignment operator sets the variable on the LHS of the expression to the same value as the variable on the RHS.

Note that string and array are object types, not primitive types. Therefore, like all objects, assignment of a string or array object means that the variable on the LHS of the assignment expression refers to the same object (that is, the same string or the same array) as the variable on the RHS. A new copy of the object is not created. If the intention is to make an assignment to a new object that is a copy of the original, you should use the .copy() method of the string or array objects, or the .clone() method (if available) of other objects.

• Expression or parameter separator.

Categories