Operators

Basics

Preoperators / Postoperators

If any operator is available as pre- and postoperator both versions basically have the same effect on the variable. The only difference is what they return: Preoperators return the variable's new value (after the operator's effect) while postoperators return the old value (the value before the operator did something).

Precedence of operators

The precedence of operators is used to group expressions.

local int a,b,c,d,e;

a=2; b=3; c=4; d=2; e=5;

                    // log output:
log(a@b@c@d@e);     // 2 3 4 2 5
log(a*b+++c**d*e);  // 86.000000
log(a@b@c@d@e);     // 2 4 4 2 5

UnrealScript actually evaluates the expression like this:

 (a * (b++)) + ((c ** d) * e)

You should use a form that uses some spaces and only few (or no) parentheses. This helps understanding the expression a lot when you look at it again after some time:

 a * b++ + c**d * e

Boolean Operators

iff (if and only if)

The word "iff" means "if and only if," implying that if the given condition isn't met, the operation will yield a different (the opposite) result. (This is maths and logic jargon, not an UnrealScript operator.)

short-circuit

Some binary boolean operators only evaluate their right operand if the result of the entire expression isn't already defined by the result of the first operand. In this case, the right operand is skipped, which is a particularly handy feature if evaluation of that right operand has non-trivial side effects (like a function call) or relies on the left operand's result.

if (bAlreadyConfirmed || ShowMessageBox("Are you sure?")) ...  // show message only when needed
if (ThisPawn != None && ThisPawn.bIsPlayer) ...                // prevent "Accessed None"s

Operation	Operator	Precedence	Description	Short-circuit
Negation	`!`	Unary	Negates a boolean expression
And	`&&`	30	True iff both operands are true	First operand false → expression false
Exclusive Or	`^^`	30	True iff one of the operands is true (but not both)
Inclusive Or	`\|\|`	32	True iff one or both of the operands are true	First operand true → expression true

Comparison Operators

Comparison operators apply to values of all types. Only compatible types can be compared (numbers with numbers, strings with strings and so on). Object (classes, actors, textures, etc.) and Name properties can only be compared using Equal or Unequal.

Operation	Operator	Precedence	Remarks
Equal	`==`	24
Approximately Equal	`~=`	24	Equality within 0.0001 (numbers) Case-insensitve equality (strings)
Less	`<`	24
Less or Equal	`<=`	24
Greater	`>`	24
Greater or Equal	`>=`	24
Not Equal	`!=`	26

Conditional Operator ??

The conditional operator ?? (only in Devastation) can be used as a shorthand for what would normally be single line if .. then .. else blocks. If used appropriately it can enhance the readability of code. The conditional operator must always be applied to an expression that will return a boolean result.

// The form of the conditional operator is:
boolean condition ?? value if condition is true : value if condition is false

// Some example code.    (boolean expression)      (result if true)     (result if false)
GRI.SuddenDeathSeconds = SuddenDeathSeconds > 0 ?? SuddenDeathSeconds : 120;

EntropicLqd: Be interesting to see if they added support for it within the engine in UT2004 (not that I'm planning on getting it).

Numeric Operators

Numeric operators apply to values of type int, float and byte.

Operation	Operator	Precedence	Description
Negation	`-`	Unary	Returns the negative value of the operand
Increment	`++`	Pre-/Postoperator	Increments the variable operand by 1
Decrement	`--`	Pre-/Postoperator	Decrements the variable operand by 1
Exponentiation	`**`	12	Puts the first operand to the power of the second operand
Multiplication	`*`	16	Multiplies both operands
Division	`/`	16	Divides the first operand by the second operand
Modulo	`%`	18	Divides the first operand by the second and returns the remainder
Addition	`+`	20	Adds both operands
Subtraction	`-`	20	Subtracts the second operand from the first operand

The modulo operator follows the computer science definition of modulus rather than the mathematical one::

 -8 % 10 = -8 (and not 2)

This results from differing interpretations of whether % should be a "modulo" or "remainder" operator (which is not the same thing), as well as differing results of what the integer division operation returns for negative numbers in different programming languages. UnrealScript's definition is consistent with what (most) C/C++ does, which is probably appropriate considering that the language is similar in many other ways. See Useful Maths Functions for the alternative.

The assignment operator = can be combined with +, -, * and /. These combined operators +=, -=, *= and /= assign the result of the operation to the first operand (which must be a variable). These combined assignment operators also return the new value of the variable, so

b += c;      // equivalent to  b = b + c;
a = b += c;  // equivalent to  b = b + c;  a = b;  or  a = (b = b + c);

will add b and c and assign the result to a and b.

Bitwise Operators

Operation	Operator	Precedence	Description
Inversion	`~`	Unary	Performs a bitwise inversion of the operand
Shift Left	`<<`	22	Shifts the bits of the first operand to the left
Shift Right (Arithmetic)	`>>`	22	Shifts the bits of the first operand right, maintaining its signum
Shift Right	`>>>`	22	Shifts the bits of the first operand right, filling with zeroes
And	`&`	28	Bitwise and
Or	`\|`	28	Bitwise or
Exclusive Or	`^`	28	Bitwise exclusive or

For the shift operators, only the 5 least significant bits of the second operand are used.
What does that mean? Well, it's a neat feature that allows you to specify, how many bits you want to stay instead of how many you want to get rid of:

// IntToHex() is a custom function that converts an integer into its hexadecimal string representation

// -12 = 0xfffffff4 -> five least significant bits: 0xfffffff4 & 0x0000001f = 0x00000014 = 20
// 12 bits = 3 hex digits; 20 bits = 5 hex digits
  
// shift positive ints                 log output
log(IntToHex(0x02468ace <<   12));  //  68ace000
log(IntToHex(0x02468ace <<  -12));  //  ace00000 = same as 0x02468ace <<  20
log(IntToHex(0x02468ace >>   12));  //  00002468
log(IntToHex(0x02468ace >>  -12));  //  00000024 = same as 0x02468ace >>  20
log(IntToHex(0x02468ace >>>  12));  //  00002468
log(IntToHex(0x02468ace >>> -12));  //  00000024 = same as 0x02468ace >>> 20
  
// shift negative ints (to prove there's no difference from the usual behavior)
log(IntToHex(0xfdb97531 <<   12));  //  97531000
log(IntToHex(0xfdb97531 <<  -12));  //  53100000 = same as 0xfdb97531 <<  20
log(IntToHex(0xfdb97531 >>   12));  //  ffffdb97
log(IntToHex(0xfdb97531 >>  -12));  //  ffffffdb = same as 0xfdb97531 >>  20
log(IntToHex(0xfdb97531 >>>  12));  //  000fdb97
log(IntToHex(0xfdb97531 >>> -12));  //  00000fdb = same as 0xfdb97531 >>> 20

Vector Operators

Rotator Operators

String Operators

Operation	Operator	Precedence	Description
String Concatenation	`@`	40	The two strings are put together with a space in between.
String Concatenation	`$`	40	The two strings are put together without any space in between.
String Concatenation and Assign	`@=`	44	The two strings are put together with a space in between and the result is assigned to the first variable and returned.
String Concatenation and Assign	`$=`	44	The two strings are put together without any space in between and the result is assigned to the first variable and returned.
Remove and Assign	`-=`	45	Removes all occurances of the second string from the first string.

Aside from the string operators, there are other things that you can do with strings that have been implemented as Global Functions.

Color Operators

Color operators are only available in subclasses of Actor.

Operation	Operator	Precedence	Description
Multiplication	`*`	16	Multiplies all components of the color by a float
Addition	`+`	20	Adds the colors
Subtraction	`-`	20	Subtracts the colors (what happens if the RH component is bigger than the LH?)

There are no combined assignment operators for colors.

Complete Table Of Precedences

The higher an operator is in this table the more tightly it binds.

Operator class	Examples
Parentheses	`( )`
Unary operators	`- ! ~ ++ --`
Exponentiation	`**`
Multiplicative operators	`* / Cross Dot`
Additive operators	`+ -`
Bit shifting and vector rotating operators	`<< >> >>>`
Comparison operators (except inequality)	`< > <= >= ~= == ClockwiseFrom`
Inequality	`!=`
Bitwise Integer operators	`& \| ^`
Logical AND, logical XOR	`&& ^^`
Logical OR	`\|\|`
Combined assignment operators	`+= -= *= /=`
String concatenation	`@ $`
String concatenation and assign	`@= $=`
String removal and assign	`-=`