Packageorg.as3coreaddendum.system
Classpublic class Enum
InheritanceEnum Inheritance Object
Implements IComparable, IEquatable, ISerializable
Subclasses AlphabeticalComparison, BooleanComparison, NumericRounding, StringCase

This is the base class for implementation of enumeration objects.

This class shouldn't be instantiated directly, rather than enumeration classes must extend this class.

What is an Enumerated Type?

An Enumerated Type is a data type that consists of a pre-defined set of values. Each enumerator (constant) is a value. An Enumerated Type groups a set of interrelated logical values.

Actionscript 3.0 doesn't implements Enumerated types. Rather, its uses a class with only constants to define a set of interrelated logical values.

One example is the flash.display.StageAlign class. It is the set of logical values acceptable for the flash.display.Stage.align property.

But even without the support of Actionscript 3.0 for Enumerated types you can simulate this functionality extending this Enum class.

Why use an Enumerated Type rather than a class with constants?

Following the example above, if you open the Actionscript 3.0 Language Reference and quickly look at the class flash.display.Stage and see the align property, you will note that its type is String. So you cannot immediatly know what values you can assign to it. Only after discovering that there is a class flash.display.StageAlign you note that these are the acceptable values. So this is the first problem with this approach.

The second problem is that you really can assign any String to the align property. Nothing guarantees you will pass the values that are actually in the flash.display.StageAlign class. Nor will there be any error at compile time that say that something is wrong.

But if instead of using this approach was used Enumeration types, these two problems would become two good points.

First, looking at the Actionscript 3.0 Language Reference you would see that the property align is of the type StageAlign. Automatically you check this class and see how to use it to assign a value for the align property.

Even better, if you make a mistake the compiler will warn you. You will no longer able to send an invalid value for the property.

But even with this approach remains a problem to be solved. The client of your code can still create instances of your Enumerated Type and use them when needed. In most cases this is undesirable, because you have already defined the set of acceptable values through constants in its Enumerated Type.

To resolve this problem exists a solution: the type-safe enum pattern. It is described with an example at the end of the page.

You can also check the class NumericRounding listed in the section "See also" below.

So to summarize the benefits of using Enumerated types: they make your code (or API) more readable and safe.

View the examples

See also

InvalidEnumArgumentError
IComparable
IEquatable
ISerializable


Public Properties
 PropertyDefined By
  name : String
[read-only] The name of this enum constant exactly as supplied by the constructor.
Enum
  ordinal : int
[read-only] The ordinal of this enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero).
Enum
Public Methods
 MethodDefined By
  
Enum(name:String, ordinal:int)
Constructor, creates a new Enum object.
Enum
  
compareTo(o:*):int
Compares this enum with the specified object for order.
Enum
  
equals(other:*):Boolean
Compares the target object for equality with this object.
Enum
  
toSource():String
Returns the source code String representation of the object.
Enum
  
toString():String
Returns the name of this enum constant, as contained in the declaration.
Enum
  
valueOf():int
Returns the primitive value of the object.
Enum
Property Detail
nameproperty
name:String  [read-only]

The name of this enum constant exactly as supplied by the constructor.

Most programmers should use the toString() method in preference to this one, as the toString() method may return a more user-friendly name. This property is designed primarily for use in specialized situations where correctness depends on getting the exact name.


Implementation
    public function get name():String
ordinalproperty 
ordinal:int  [read-only]

The ordinal of this enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero).


Implementation
    public function get ordinal():int
Constructor Detail
Enum()Constructor
public function Enum(name:String, ordinal:int)

Constructor, creates a new Enum object.

Parameters
name:String — The name of this enumeration constant.
 
ordinal:int — The ordinal of this enumeration constant, that is its position in the enum declaration (where the initial constant is assigned an ordinal of zero).

Throws
ArgumentError — If the name argument is null or an empty String.
 
IllegalOperationError — If this class is instantiated directly, in other words, if there is not another class extending this class.
Method Detail
compareTo()method
public function compareTo(o:*):int

Compares this enum with the specified object for order.

Enum constants are only comparable to other enum constants of the same enum type. The natural order implemented by this method is the order in which the constants are declared.

Parameters

o:* — The target object to be compared.

Returns
int — a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws
ArgumentError — If the type of the argument o is other than this exactly enum type instance.

See also

equals()method 
public function equals(other:*):Boolean

Compares the target object for equality with this object.

Parameters

other:* — The object to be compared for equality with this object.

Returns
Booleantrue if the specified object is equal to this enum constant.

See also

toSource()method 
public function toSource():String

Returns the source code String representation of the object.

Returns
String — The source code String representation of the object.

See also

toString()method 
public function toString():String

Returns the name of this enum constant, as contained in the declaration.

This method may be overridden, though it typically isn't necessary or desirable. An enum type should override this method when a more "programmer-friendly" string form exists.

Returns
String — The name of this enum constant.
valueOf()method 
public function valueOf():int

Returns the primitive value of the object.

This method is called automatically by the Flash Player every time an arithmetic operation occur. Thus, it's possible to perform these operations to check the position between two or more enum constants.

Returns
int — The primitive value of the object. In this case, the ordinal value.
Examples
Simple Enumerated Type

Suppose that we have an API that make loading of files. The acceptable file types that the API can load can be defined by an Enumerated Type. In this example the name of the Enumerated Type will be FileType. Note that you don't need to use the suffix "Enum" in its name.

Then we define the types that the API can load. In this example the API can load just image, swf and mp3 files. So we have just three constants, one to each file type.

When we want to load a file, we use the appropriate constant to tell the API what type of file will be loaded. If you need a file type that doesn't exists in the Enumerated Type, this means that the API doesn't support that file type.

     import org.as3coreaddendum.system.Enum;
     
     public class FileType extends Enum
     {
     
          public static const IMAGE   :FileType = new FileType("Image", 0);
          public static const SWF     :FileType = new FileType("SWF", 1);
          public static const MP3     :FileType = new FileType("MP3", 2);
     
          public function FileType(name:String, ordinal:int)
          {
               super(name, ordinal);
          }
     }
     
Type-safe Enumerated Type

In the above example, if the user of the API need to load a file type that doesn't exists in the Enumerated Type, it could instantiate a new object FileType with the desired type, as in the example below:

     import FileType;
     
     var videoFileType:FileType = new FileType("Video", 3);
     

This behavior would be wrong, but still allowed by the technical point of view. This would create the illusion that the user can create new types at runtime and send them to the API.

To prevent this mistake, we can implement a pattern named type-safe enum. This pattern will prevents the user create new types, throwing a runtime error.

There are some ways to do this, we will see just one below:

     import org.as3coreaddendum.system.Enum;
     
     public class FileType extends Enum
     {
     
          public static const IMAGE   :FileType = new FileType("Image", 0);
          public static const SWF     :FileType = new FileType("SWF", 1);
          public static const MP3     :FileType = new FileType("MP3", 2);
     
          private static var _created:Boolean = false;
     
          {
               _created = true;
          }
     
          public function FileType(name:String, ordinal:int)
          {
               super(name, ordinal);
               if (_created) throw new IllegalOperationError("The set of acceptable values by this Enumerated Type has already been created internally.");
          }
     }
     

What happens above is that when the FileType is loaded in the Flash Player memory at runtime, first all the static members are initialized. After that the static code block is executed:

     {
          _created = true;
     }
     

So first all the constants are initialized with the FileType instances because the _created static variable is false and then immediately after that the _created is set to true. Thus no more instances can be created.

Your Enumerated Type is safe to be used only with the set of values pre-defined by you.