Legacy:Object (UT3)/Operators

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to navigation Jump to search
UT3:: 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)/Operators/Numeric Functions for other globally available operations on numeric values and Legacy:Object (UT3)/Operators/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."

Pre-defined Operators

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

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

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

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

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

Vector is a struct defined in the Object class. See Legacy:Object (UT3)/Operators/Structs for its definition, Legacy:Object (UT3)/Operators/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)/Operators/Functions:

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

} </uscript>

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

Rotator is a struct defined in the Object class. See Legacy:Object (UT3)/Operators/Structs for its definition, Legacy:Object (UT3)/Operators/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

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

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

Quat is a struct defined in the Object class. See Legacy:Object (UT3)/Operators/Structs for its definition, Legacy:Object (UT3)/Operators/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

Color and LinearColor are structs defined in the Object class. See Legacy:Object (UT3)/Operators/Structs for their definition and Legacy:Object (UT3)/Operators/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.