Difference between revisions of "Types"

Revision as of 17:35, 5 April 2008

UnrealScript is a strongly-typed language and has various built-in data types. UnrealScript types can be divided in three general groups: primitive types, reference types and composite types.

Primitive types

Int

UnrealScript has two integer types and int is the larger of them. Int values are integer numbers in the range -2147483648 to 2147483647, in other words signed 32 bit values.

Int literals can be specified in decimal or hexadecimal notation. Values exceeding the allowed range are truncated to the least significant 32 bits. For example the hexadecimal literal 0x100000005 actually represents the value 5.

Byte

The smaller of UnrealScript's two integer types is byte. Byte values are integer numbers in the range 0 to 255, in other words unsigned 8 bit values.

Any int literal can also be used in "byte context". If the value is outside the allowed range it will be truncated to the 8 least significant bits. For example the hexadecimal literal 0x100 (256) actually represents the value 0 and the decimal literal -1 represents the value 255.

Bool

UnrealScript's boolean type is bool and allows the values true and false. These are also the names of the boolean literals.

The bool type has some restrictions in UnrealScript. For example it's not possible to declare static or dynamic arrays of bool values in Unreal Engine generations 1 and 2 or to use the parameter modifier "out" on bool parameters in function declarations.

Float

UnrealScript has a single precision floating point type called float. The possible float values are distributed over the huge range of about 3.403·10³⁸ to -3.403·10³⁸. The smallest possible value greater than 0 is about 1.175·10^-38. Generally, float values have a precision of about 6 or 7 decimal digits.

Float literals can either be specified in decimal or scientific notation. For example the literal 1.2e3 means 1.2·10³ = 1230. Note that float literals must always contain the decimal point, even when using scientific notation, and must always start with a number or with the minus sign followed by a number. Unfortunately, negative exponents are not allowed in scientific notation. A hexadecimal representation like in Java is not supported.

If a floating point operation has a result that exceeds the highest or lowest possible number, the return value has the special value of positive or negative infinity respectively. Invalid operations such as division by zero or adding positive and negative infinity return the special value NaN, "Not a Number". Be careful about those three special values as they will propagate. That means, if you subtract, add, multiply or divide infinity values, the result will be infinity again. If you perform an operation with the NaN value, the result will either be NaN again or (for comparison operators) something totally unexpected. For example if you perform the operation a = x / 0, variable a will contain NaN. Now the comparison a == a will actually return the value false! Unlike NaN, infinity values will behave as expected if used in comparison operations, that is positive infinity is greater than any other value, negative infinity is smaller than any other value.

Technical information: As specified in the IEEE floating-point standard, the float type internally has a length of 32 bits and consists of a 23 bit fraction part, an 8 bit exponent and one sign bit. Especially the 23 bit fraction part (called the "mantissa") imposes a limit on floating point precision. When large int values greater than 2²³ or smaller than -2²³ are typecasted to float, they may get rounded.

String

UnrealScript has a character string data type called string. Strings can contain any combination of Unicode characters.

String literals are enclosed in double quotes and may not extends past the end of a line. Technically string literals are allowed to have a length of up to 1023 characters. Internally strings are zero-terminated, which means no string can contain the null character because it would be recognized as the end of the string.

String values are immutable and UnrealScript neither provides "character" type nor allows direct access to individual string characters. There are, however, functions for extracting substrings and returning the Unicode value of the first character of a string. There's also a function for returning a string of length 1 containing a character corresponding to a specified Unicode value.

Name

The data type name is a very unusual one. To the programmer it appears a lot like a case-insensitive string with very limited character set. Every object and every class has a name, but names are also used for a variety of other things, such as identifying states, code labels, trigger events or bones of a skeletal mesh.

Name literals are enclosed in single quotes and may contain the letters A to Z, both upper and lowercase, the numbers 0 to 9, the underscore character _ and the space character. Names are limited to a length of up to 63 characters.

Internally names are represented as int values, which makes sense since names are used in many places and would take up a lot of space if represented as strings. At runtime, the first mentioned string representation of a name is stored in the global name table. Whenever a name value is to a string through typecasting, the string representation from the name table is used. This means that even though you could use the name literal 'cOnTrOlLeR' in your code, it would most likely be represented by the string Controller instead, because that's the spelling used for the name of the class with that name.

Reference types

Object

An object reference does not contain an object, it only points to (i.e. "reference") an instance of an object. That means the object reference's value actually is a pointer, not an object. Different object references may point to the same object. An object reference may also point to no object at all.

Object references can be restricted to instances of a certain class. For example, an object reference might only accept instances of the class WebApplication, which also includes instances of WebApplication subclasses like UTServerAdmin.

Object literals start with the name of the object's class, followed by the qualified or unqualified name of the object instance to reference, enclosed in single quotes. It is also possible to specify a literal for the empty object reference with the keyword None. Another special object literal is the keyword Self, which references the object instance executing the current function or state code. It is not available in static functions, because those functions are not executed in the context of an object instance but of an object class.

Actor

Actor references are basically the same as object references, just restricted to Actor or one of its subclasses. The only difference to non-actor references is, that the Actor class provides a Destroy method. This method not only gets rid of the actor instance it was called on, but also implicitly sets all references to that actor instance to none.

Most of your object references will probably be actor references, but apart from None and Self you will rarely encounter object literals of type Actor or one of its subclasses. Mappers sometimes see actor literals in the property window of various level objects, but UnrealScript programmers usually won't use them.

Class

A class reference is very similar to an object reference, except that it is restricted to the type Class. Class references can be further restricted to a certain meta class, that means the type of referenced class. Such a restricted class reference is called a class limiter and is denoted by the keyword Class followed by the name of the meta class in angle brackets. For example class<Info> denotes a reference that can point to the class Info or one of its subclasses.

Class literals are specified in the same way as other object literals. The type of reference, here class, followed by the class name, optionally qualified with the containing package name, and enclosed in single quotes. For example class'Info' or class'Engine.Info' references the Info class located in the Engine package. The special object literal None can be used for class references and means "no class".

Delegate

Main article: Delegates

Delegates were introduced in Unreal Engine 2 and are function references. In Unreal Engine 2, delegates could only be declared using function syntax and replacing the keyword Function with the keyword Delegate. Unreal Engine 3 also provides a notation similar to class limiters or dynamic arrays that can be used as variable or parameter type. This notation starts with the keyword Delegate, followed by the name of a prototype delegate function declaration in angle brackets.

Function literals are only used for delegate assignments and look more like a variable access than a literal. Basically you reference the object instance containing the function you want to assign to a delegate property (unless, of course, the function is contained in the same object instance as the code doing the assignment), followed by a dot and the pure function name without anything afterwards. As with object references, the keyword None means "no function". For delegate function declarations this means the default body, if available, is executed when the delegate is called.

Pointer

Also starting with Unreal Engine 2, UnrealScript has a generic pointer data type, but it only serves as a placeholder for pointer variables in native code. UnrealScript itself provides no way to access or modify pointer properties.

Composite types

Enums

Main article: Enums

Structs

Main article: Structs

Static arrays

Dynamic arrays

Main article: Dynamic arrays