Legacy:Object (UT3)/Operators

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)/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."

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)/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

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

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)/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

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.