Type conversions

Implicit conversions

Implicit conversions happen at run time in a number of contexts:

• In assignment statements

• When values are passed as function arguments

• When values are returned from functions

• In expressions using certain operators, such as the addition ( + ) operator

  For user-defined types, implicit conversions succeed when the value to be converted is an instance of the destination class or a class that derives from the destination class. If an implicit conversion is unsuccessful, an error occurs. For example, the following code contains a successful implicit conversion and an unsuccessful implicit conversion:

  class A {} 
  class B extends A {} 
   
  var objA:A = new A(); 
  var objB:B = new B(); 
  var arr:Array = new Array(); 
   
  objA = objB; // Conversion succeeds. 
  objB = arr; // Conversion fails.
  

  For primitive types, implicit conversions are handled by calling the same internal conversion algorithms that are called by the explicit conversion functions. The following sections discuss these primitive type conversions in detail.

Explicit conversions

It’s helpful to use explicit conversions, or casting, when you compile in strict mode, because there may be times when you do not want a type mismatch to generate a compile-time error. This may be the case when you know that coercion will convert your values correctly at run time. For example, when working with data received from a form, you may want to rely on coercion to convert certain string values to numeric values. The following code generates a compile-time error even though the code would run correctly in standard mode:

var quantityField:String = "3"; 
var quantity:int = quantityField; // compile time error in strict mode

If you want to continue using strict mode, but would like the string converted to an integer, you can use explicit conversion, as follows:

var quantityField:String = "3"; 
var quantity:int = int(quantityField); // Explicit conversion succeeds.

Casting to int, uint, and Number

You can cast any data type into one of the three number types: int, uint, and Number. If Flash Player or Adobe AIR is unable to convert the number for some reason, the default value of 0 is assigned for the int and uint data types, and the default value of NaN is assigned for the Number data type. If you convert a Boolean value to a number, true becomes the value 1 and false becomes the value 0.

var myBoolean:Boolean = true; 
var myUINT:uint = uint(myBoolean); 
var myINT:int = int(myBoolean); 
var myNum:Number = Number(myBoolean); 
trace(myUINT, myINT, myNum); // 1 1 1 
myBoolean = false; 
myUINT = uint(myBoolean); 
myINT = int(myBoolean); 
myNum = Number(myBoolean); 
trace(myUINT, myINT, myNum); // 0 0 0

String values that contain only digits can be successfully converted into one of the number types. The number types can also convert strings that look like negative numbers or strings that represent a hexadecimal value (for example, 0x1A ). The conversion process ignores leading and trailing white space characters in the string value. You can also cast strings that look like floating-point numbers using Number() . The inclusion of a decimal point causes uint() and int() to return an integer, truncating the decimal and the characters following it. For example, the following string values can be cast into numbers:

trace(uint("5")); // 5 
trace(uint("-5")); // 4294967291. It wraps around from MAX_VALUE 
trace(uint(" 27 ")); // 27 
trace(uint("3.7")); // 3 
trace(int("3.7")); // 3 
trace(int("0x1A")); // 26 
trace(Number("3.7")); // 3.7

String values that contain non-numeric characters return 0 when cast with int() or uint() and NaN when cast with Number() . The conversion process ignores leading and trailing white space, but returns 0 or NaN if a string has white space separating two numbers.

trace(uint("5a")); // 0 
trace(uint("ten")); // 0 
trace(uint("17 63")); // 0

In ActionScript 3.0, the Number() function no longer supports octal, or base 8, numbers. If you supply a string with a leading zero to the ActionScript 2.0 Number() function, the number is interpreted as an octal number, and converted to its decimal equivalent. This is not true with the Number() function in ActionScript 3.0, which instead ignores the leading zero. For example, the following code generates different output when compiled using different versions of ActionScript:

trace(Number("044"));  
// ActionScript 3.0 44 
// ActionScript 2.0 36

Casting is not necessary when a value of one numeric type is assigned to a variable of a different numeric type. Even in strict mode, the numeric types are implicitly converted to the other numeric types. This means that in some cases, unexpected values may result when the range of a type is exceeded. The following examples all compile in strict mode, though some will generate unexpected values:

var myUInt:uint = -3; // Assign int/Number value to uint variable 
trace(myUInt); // 4294967293 
 
var myNum:Number = sampleUINT; // Assign int/uint value to Number variable 
trace(myNum) // 4294967293 
 
var myInt:int = uint.MAX_VALUE + 1; // Assign Number value to uint variable 
trace(myInt); // 0 
 
myInt = int.MAX_VALUE + 1; // Assign uint/Number value to int variable 
trace(myInt); // -2147483648

The following table summarizes the results of casting to the Number, int, or uint data type from other data types.

null

Casting to Boolean

Casting to Boolean from any of the numeric data types (uint, int, and Number) results in false if the numeric value is 0, and true otherwise. For the Number data type, the value NaN also results in false . The following example shows the results of casting the numbers -1, 0, and 1:

var myNum:Number; 
for (myNum = -1; myNum<2; myNum++) 
{ 
    trace("Boolean(" + myNum +") is " + Boolean(myNum)); 
}

The output from the example shows that, of the three numbers, only 0 returns a value of false :

Boolean(-1) is true 
Boolean(0) is false 
Boolean(1) is true

Casting to Boolean from a String value returns false if the string is either null or an empty string ( "" ). Otherwise, it returns true .

var str1:String; // Uninitialized string is null. 
trace(Boolean(str1)); // false 
 
var str2:String = ""; // empty string 
trace(Boolean(str2)); // false 
 
var str3:String = " "; // white space only 
trace(Boolean(str3)); // true

Casting to Boolean from an instance of the Object class returns false if the instance is null ; otherwise, it returns true :

var myObj:Object; // Uninitialized object is null. 
trace(Boolean(myObj)); // false 
 
myObj = new Object(); // instantiate  
trace(Boolean(myObj)); // true

Boolean variables get special treatment in strict mode in that you can assign values of any data type to a Boolean variable without casting. Implicit coercion from all data types to the Boolean data type occurs even in strict mode. In other words, unlike almost all other data types, casting to Boolean is not necessary to avoid strict mode errors. The following examples all compile in strict mode and behave as expected at run time:

var myObj:Object = new Object(); // instantiate  
var bool:Boolean = myObj; 
trace(bool); // true 
bool = "random string"; 
trace(bool); // true 
bool = new Array(); 
trace(bool); // true 
bool = NaN; 
trace(bool); // false

The following table summarizes the results of casting to the Boolean data type from other data types:

null

false

Casting to String

Casting to the String data type from any of the numeric data types returns a string representation of the number. Casting to the String data type from a Boolean value returns the string "true" if the value is true , and returns the string "false" if the value is false .

Casting to the String data type from an instance of the Object class returns the string "null" if the instance is null . Otherwise, casting to the String type from the Object class returns the string "[object Object]" .

Casting to String from an instance of the Array class returns a string comprising a comma-delimited list of all the array elements. For example, the following cast to the String data type returns one string containing all three elements of the array:

var myArray:Array = ["primary", "secondary", "tertiary"]; 
trace(String(myArray)); // primary,secondary,tertiary

Casting to String from an instance of the Date class returns a string representation of the date that the instance contains. For example, the following example returns a string representation of the Date class instance (the output shows result for Pacific Daylight Time):

var myDate:Date = new Date(2005,6,1); 
trace(String(myDate)); // Fri Jul 1 00:00:00 GMT-0700 2005

The following table summarizes the results of casting to the String data type from other data types.

null

"null"