Worst-case scenario: the UEd Goblin wipes the map and burns down your house.
Legacy:Object (UT3)/Operators
The following operators are declared in the Object class and thus globally available. They are conveniently grouped by the types they operate on and sorted by precedence, starting with most tightly binding. All global operators are static, final and (with the exception of the color operators) native. See Legacy:Object (UT3)/Numeric Functions for other globally available operations on numeric values and Legacy:Object (UT3)/Functions for globally available operations on other data, like colors, strings or objects.
In the following tables, pre-operators have an empty operand 1 and post-operators have an empty operand 2. Operand types may be followed by one of the following modifiers:
- coerce
- The value of the operand is subject to automatic typecasting to match the required operand type.
Without the coerce modifier only the types byte, int and float will be auto-casted to each other. The only exception is an out operand, which will not allow automatic typecasting.
- out
- Usually only applied to the first operand of a binary operator or to the single operand of certain unary operators. The operand must be an Wikipedia:Lvalue and will be modified by the operator. Operators with an out operand may be used as stand-alone statements, while operators without any out operand would cause the compiler error "Expression has no effect."
- skip
- Only found as modifier of the second operand of a binary operator. The second operand is not evaluated if the first operand already decides the return value of the operator. This behavior is known as "short-circuiting" and is only used by the
&&
and{|
|- | |}
boolean operators.
Operators are generally Wikipedia:left-associative, i.e. Operators with the same precedence are evaluated from left to right: "a / b * c
" is the same as "(a / b) * c
". The only exception here is the conditional operator, which is right-associative("a ? b : c ? d : e
" is the same as "a ? b : (c ? d : e)
") and the assignment operator, which is non-associative since it doesn't return a value.
In the following descriptions the word iff means "if and only if."
Contents
Pre-defined Operators[edit]
The following operators do not have corresponding UnrealScript declarations. They are described here only for reference.
Symbol | Operand 1 | Operand 2 | Operand 3 | Precedence | Result | Description |
---- |
struct<type> | struct<type> | 24 | bool | Returns true iff both structs' corresponding components have the same values. | |
!= |
struct<type> | struct<type> | 26 | bool | Returns false iff any of the structs' corresponding components have the different values. | |
? : |
bool | type (skip) | type (skip) | Expression | type | If the first operand evaluates to true, the second operand is evaluated and its value is returned, otherwise the third operand is evaluated and its value is returned. |
= |
type (out) | type | Statement | Assigns the value of the second operand to the first. This is actually a statement that doesn't return any value and thus may not be used inside another expression or statement. |
Note 1: "struct<type>" is not actually a valid UnrealScript type declaration. It merely points out that both operands must be of the same struct type.
Note 2: The conditional operator ? :
is a ternary operator with the question mark separating the first and second operand and the colon separating the second and third operand. Its binds just a little more tightly than the assignment statement. Its second and third operand must have the same type, which is also used as the return type of this operator. Like other operators without any out operands, it may not be used as stand-alone statement.
Note 3: Enums are "glorified" byte value. Like bytes, enum values are compared using int operators.
Bool Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
! |
bool | preoperator | bool | Returns the opposite value, i.e. false if the operand is true and vice versa. | |
---- |
bool | bool | 24 | bool | Returns true iff both operands have the same value. |
!= |
bool | bool | 26 | bool | Returns false iff both operands have the same value. |
&& |
bool | bool (skip) | 30 | bool | Returns false iff at least one operand is false. |
^^ |
bool | bool | 30 | bool | Returns true iff the operand have different values. Technically this is the same result as the != operator, just doesn't bind as tightly. |
{| |
|||||
|bool |bool (skip) | style="text-align: right" |32 |bool |Returns true iff at least one operand is true. |}
Note 1: There are no bool versions of &&
and {|
|- | |}
without short-circuiting. If you need both expressions to be evaluated, you will have to assign them to variables first and then pass those to the operator.
Byte Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
++ |
byte (out) | preoperator | byte | Increases the value of the operand by 1 and returns the previous value. | |
---- |
byte (out) | preoperator | byte | Decreases the value of the operand by 1 and returns the previous value. | |
++ |
byte (out) | postoperator | byte | Increases the value of the operand by 1 and returns the new value. | |
---- |
byte (out) | postoperator | byte | Decreases the value of the operand by 1 and returns the new value. | |
*= |
byte (out) | byte | 34 | byte | Multiplies the two values, stores the result in the first operand and returns the result. |
*= |
byte (out) | float | 34 | byte | Multiplies the two values using floating point arithmetics, stores the result in the first operand and returns the result. |
/= |
byte (out) | byte | 34 | byte | Performs division using integer arithmetics, stores the result in the first operand and returns the result. |
+= |
byte (out) | byte | 34 | byte | Adds the two values, stores the result in the first operand and returns the result. |
-=- |
byte (out) | byte | 34 | byte | Subtracts the second from the first value, stores the result in the first operand and returns the result. |
Note: Comparisons and basic arithmetic operations with byte values are done using the corresponding int operators.
Int Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
- |
int | preoperator | int | Returns the arithmetic inverse value. | |
~ |
int | preoperator | int | Returns the bitwise negated value. | |
++ |
int (out) | preoperator | int | Increases the value of the operand by 1 and returns the previous value. | |
---- |
int (out) | preoperator | int | Decreases the value of the operand by 1 and returns the previous value. | |
++ |
int (out) | postoperator | int | Increases the value of the operand by 1 and returns the new value. | |
---- |
int (out) | postoperator | int | Decreases the value of the operand by 1 and returns the new value. | |
* |
int | int | 16 | int | Multiplies the two values. |
/ |
int | int | 16 | int | Divides the first by the second value. |
+ |
int | int | 20 | int | Adds the two values. |
- |
int | int | 20 | int | Subtracts the second from the first value. |
<< |
int | int | 22 | int | Shift bits of the first operand to the left, fill with zeroes. |
>> |
int | int | 22 | int | Shift bits of the first operand to the right, fill with sign bit, i.e. ones for negative numbers. |
>>> |
int | int | 22 | int | Shift bits of the first operand to the right, fill with zeroes. |
> |
int | int | 24 | bool | Returns true iff the first operand is arithmetically larger than the second operand. |
< |
int | int | 24 | bool | Returns true iff the first operand is arithmetically smaller than the second operand. |
>= |
int | int | 24 | bool | Returns true iff the first operand is arithmetically equal to or larger than the second operand. |
<= |
int | int | 24 | bool | Returns true iff the first operand is arithmetically equal to or larger than the second operand. |
---- |
int | int | 24 | bool | Returns true iff the two operands have the same value. |
!= |
int | int | 26 | bool | Returns true iff the two operands have different values. |
& |
int | int | 28 | int | Performs bitwise AND, i.e. a bit in the result is 1 iff the corresponding bit in both operands are 1. |
{| |
|int |int | style="text-align: right" |28 |int |Performs bitwise OR, i.e. a bit in the result is 0 iff the corresponding bit in both operands are 0. |- | style="text-align: center" |^
|int |int | style="text-align: right" |28 |int |Performs bitwise XOR, i.e. a bit in the result is 1 iff exactly one of the corresponding bit in both operands is 1. |- | style="text-align: center" |*=
|int (out) |float | style="text-align: right" |34 |int |Multiplies the two values, stores the result in the first operand and returns the result. |- | style="text-align: center" |/=
|int (out) |float | style="text-align: right" |34 |int |Divides the first by the second value, stores the result in the first operand and returns the result. |- | style="text-align: center" |+=
|int (out) |int | style="text-align: right" |34 |int |Adds the two values, stores the result in the first operand and returns the result. |- | style="text-align: center" |-=-
|int (out) |int | style="text-align: right" |34 |int |Subtracts the second from the first value, stores the result in the first operand and returns the result. |}
Note 1: The shift operators truncate the second operand's value to the five least significant bits (a value between 0 and 31) before applying the shifting operation to the first operand's value. This has the nice side effect that you can use negative values to specify the number of bits to keep instead of the number of bits to shift out.
Note 2: The operators *=
and /=
always perform floating point multiplication and division respectively. This means you may lose precision if your operands or the result requires more bits than a floating point mantissa can hold. Since UnrealScript's float values are single precision, their mantissa has a width of 23 bits. This means any values with 24 or more bits (generally all values with more than 9 decimal digits) are affected.
If you need full integer precision with potentially large values, use "A = A * B;
" instead of "A *= B;
" to get the precise value.
Note 3: There is no integer operator for remainder after division. The %
operator converts operands to float and returns a float value, so it is not suitable when dealing with large operands and you need absolute integer precision. (see note 2 above)
If you need full integer precision with potentially large values, use "A - (A / B) * B
" instead of "A % B
" to get the precise value. For powers of 2 as second operand you can also use bitwise AND with the second operand reduced by 1, e.g. "A & 0xfff
" instead of "A % 4096", with 0xfff being the hexadecimal representation of 4095.
Float Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
- |
float | preoperator | float | Returns the arithmetic inverse value. | |
** |
float | float | 12 | float | Raises the first operand to the power of the second operand. |
* |
float | float | 16 | float | Multiplies the two values. |
/ |
float | float | 16 | float | Divides the first by the second value and returns the result. |
% |
float | float | 18 | float | Divides the first by the second value and returns the remainder after division. |
+ |
float | float | 20 | float | Adds the two values. |
- |
float | float | 20 | float | Subtracts the second from the first value. |
> |
float | float | 24 | bool | Returns true iff the first operand is arithmetically larger than the second operand. |
< |
float | float | 24 | bool | Returns true iff the first operand is arithmetically smaller than the second operand. |
>= |
float | float | 24 | bool | Returns true iff the first operand is arithmetically equal to or larger than the second operand. |
<= |
float | float | 24 | bool | Returns true iff the first operand is arithmetically equal to or larger than the second operand. |
---- |
float | float | 24 | bool | Returns true iff the two operands have the same value. |
~= |
float | float | 24 | bool | Returns true iff the absolute difference of the two operands is less than 0.0001. |
!= |
float | float | 26 | bool | Returns true iff the two operands have different values. |
*= |
float (out) | float | 34 | float | Multiplies the two values, stores the result in the first operand and returns the result. |
/= |
float (out) | float | 34 | float | Divides the first by the second value, stores the result in the first operand and returns the result. |
+= |
float (out) | float | 34 | float | Adds the two values, stores the result in the first operand and returns the result. |
-=- |
float (out) | float | 34 | float | Subtracts the second from the first value, stores the result in the first operand and returns the result. |
Vector Operators[edit]
Vector is a struct defined in the Object class. See Legacy:Object (UT3)/Structs for its definition, Legacy:Object (UT3)/Numeric Functions for additional operations and Vector for a general description.
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
- |
vector | preoperator | vector | Returns a vector of the same length but reverse direction. | |
* |
vector | float | 16 | vector | Multiplies the vector's components by the float value. |
* |
float | vector | 16 | vector | Multiplies the vector's components by the float value. |
* |
vector | vector | 16 | vector | Multiplies the two vectors' corresponding components. |
/ |
vector | float | 16 | vector | Divides the vector's components by the float value. |
Dot |
vector | vector | 16 | float | Multiplies the two vectors' corresponding components and returns the sum of these products. (see Wikipedia:dot product) |
Cross |
vector | vector | 16 | vector | Calculates the Wikipedia:cross product of the two vectors. |
+ |
vector | vector | 20 | vector | Adds the two vectors. |
- |
vector | vector | 20 | vector | Adds the reverse of the second vector to the first vector. |
<< |
vector | rotator | 22 | vector | Rotates the vector as described by the rotator. |
>> |
vector | rotator | 22 | vector | "Unrotates" the vector as described by the rotator. |
---- |
vector | vector | 24 | bool | Returns true iff the two vectors have the same direction and length. |
!= |
vector | vector | 26 | bool | Returns true iff the two vectors differ in direction and/or length. |
*= |
vector (out) | float | 34 | vector | Multiplies the vector's components by the float value, stores the result in the first operand and returns the result. |
*= |
vector (out) | vector | 34 | vector | Multiplies the two vectors' corresponding components, stores the result in the first operand and returns the result. |
/= |
vector (out) | float | 34 | vector | Divides the the vector's components by the float value, stores the result in the first operand and returns the result. |
+= |
vector (out) | vector | 34 | vector | Adds the two vectors, stores the result in the first operand and returns the result. |
-=- |
vector (out) | vector | 34 | vector | Adds the reverse of the second vector to the first vector, stores the result in the first operand and returns the result. |
The result of vector rotation operators <<
and >>
can also be described using the GetAxes() and GetUnAxes() Legacy:Object (UT3)/Functions:
static final operator(22) vector << (vector A, rotator B) { local vector X, Y, Z; GetAxes(B, X, Y, Z); return X * A.X + Y * A.Y + Z * A.Z; } static final operator(22) vector >> (vector A, rotator B) { local vector X, Y, Z; GetUnAxes(B, X, Y, Z); return X * A.X + Y * A.Y + Z * A.Z; }
For <<
operand A is a vector relative to a rotation with zero pitch, yaw and roll, and the result is the same vector relative to the rotation in operand B. For >>
operand A is a vector relative to the rotation in operand B, and the result is the same vector relative to a rotation with zero pitch, yaw and roll. They are basically inverse operations.
Operator <<
could also be considered a local to global conversion as it converts a local view offset (e.g. for weapons on the HUD) to an actual global location offset from the player's view location. Conversely, operator >>
could be considered a global to local conversion.
Rotator Operators[edit]
Rotator is a struct defined in the Object class. See Legacy:Object (UT3)/Structs for its definition, Legacy:Object (UT3)/Numeric Functions for additional operations and Rotator for a general description.
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
* |
rotator | float | 16 | rotator | Multiplies the rotator's components by the float value. |
* |
float | rotator | 16 | rotator | Multiplies the rotator's components by the float value. |
/ |
rotator | float | 16 | rotator | Divides the rotator's components by the float value. |
+ |
rotator | rotator | 20 | rotator | Adds the two rotators' corresponding components. |
- |
rotator | rotator | 20 | rotator | Subtracts the second rotator's components from the corresponding components of the first rotator. |
---- |
rotator | rotator | 24 | bool | Returns true iff the two rotators have the same direction and length. |
ClockwiseFrom |
int | int | 24 | bool | Interprets the two values as corresponding rotator components. Returns true iff the shortest rotation from the first to the second operand would be in clockwise direction. |
!= |
rotator | rotator | 26 | bool | Returns true iff any of the two rotators' corresponding components are different. |
*= |
rotator (out) | float | 34 | rotator | Multiplies the rotator's components by the float value, stores the result in the first operand and returns the result. |
/= |
rotator (out) | float | 34 | rotator | Divides the the rotator's components by the float value, stores the result in the first operand and returns the result. |
+= |
rotator (out) | rotator | 34 | rotator | Adds the two rotators, stores the result in the first operand and returns the result. |
-=- |
rotator (out) | rotator | 34 | rotator | Subtracts the second rotator from the first, stores the result in the first operand and returns the result. |
String Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
> |
string | string | 24 | bool | Returns true iff the first string comes before the second one in case-sensitive order. |
< |
string | string | 24 | bool | Returns true iff the first string comes after the second one in case-sensitive order. |
>= |
string | string | 24 | bool | Returns true iff the two strings are identical or first string comes before the second one in case-sensitive order. |
<= |
string | string | 24 | bool | Returns true iff the two strings are identical or first string comes before the second one in case-sensitive order. |
---- |
string | string | 24 | bool | Returns true iff the two strings are identical. |
~= |
string | string | 24 | bool | Compares the two strings case-insensitively and returns 'true iff the two strings are identical. |
!= |
string | string | 26 | bool | Returns true iff the two strings are not identical. |
$ |
string (coerce) | string (coerce) | 40 | string | Appends the characters of the second string after those of the first and returns the result. |
@ |
string (coerce) | string (coerce) | 40 | string | Same as $ , but separates the two strings with a space characters. |
$= |
string (out) | string (coerce) | 44 | string | Appends the characters of the second string after those of the first, stores the result in the first operand and returns the result. |
@= |
string (out) | string (coerce) | 44 | string | Same as $= , but separates the two strings with a space characters. |
-=- |
string (out) | string (coerce) | 45 | string | Removes all occurrences of the second string from the first, stores the result in the first operand and returns the result. |
Note 1: Comparison operators and combined non-string assignment operators bind more tightly than string concatenation. Only the built-in assignment statement and conditional operator bind less tightly.
Note 2: The (String -= String)
operator has a different precedence than arithmetic -=-
operators.
Note 3: String order is determined by comparing the Unicode values of the individual characters from first to last. If one string is a prefix of the other (i.e. all of the first string's characters make up the beginning of the other string), then the shorter string comes first.
Object and Name Operators[edit]
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
---- |
Object | Object | 24 | bool | Returns true iff the two operands refer to the same object. |
!= |
Object | Object | 26 | bool | Returns true iff the two operands refer to different objects. |
---- |
Interface | Interface | 24 | bool | Returns true iff the two operands refer to the same interface. |
!= |
Interface | Interface | 26 | bool | Returns true iff the two operands refer to different interfaces. |
---- |
name | name | 24 | bool | Returns true iff the two operands contain the same name value. |
!= |
name | name | 26 | bool | Returns true iff the two operands contain different name values. |
Quaternion Operators[edit]
Quat is a struct defined in the Object class. See Legacy:Object (UT3)/Structs for its definition, Legacy:Object (UT3)/Numeric Functions for additional operations and Quaternion for a general description.
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
+ |
Quat | Quat | 16 | Quat | Adds the two quaternions' corresponding components. |
- |
Quat | Quat | 16 | Quat | Subtracts the second quaternion's components from the corresponding components of the first quaternion. |
Quaternion comparison is done using the built-in struct comparison operators.
Color Operators[edit]
Color and LinearColor are structs defined in the Object class. See Legacy:Object (UT3)/Structs for their definition and Legacy:Object (UT3)/Functions for additional operations.
Color operators are not declared native and are implemented in UnrealScript (as opposed to native code). They only affect the red, green and blue components of the color and return the unchanged alpha value of the first color operand.
Symbol | Operand 1 | Operand 2 | Precedence | Result | Description |
* |
Color | float | 16 | Color | Multiplies the color's components by the float value. |
* |
LinearColor | float | 16 | LinearColor | Multiplies the LinearColor's components by the float value. |
* |
float | Color | 16 | Color | Multiplies the color's components by the float value. |
+ |
Color | Color | 20 | Color | Adds the two colors' corresponding components. |
- |
Color | Color | 20 | Color | Subtracts the second color's components from the corresponding components of the first Color. |
- |
LinearColor | LinearColor | 20 | LinearColor | Subtracts the second LinearColor's components from the corresponding components of the first LinearColor. |
Note 1: Color and LinearColor comparison is done using the built-in struct comparison operators, which also means you can't compare a Color value to a LinearColor value.
Note 2: There are no combined assignment operators for color types. There also is no add operator and only one multiply operator for LinearColors.