Package | org.as3coreaddendum.system |
Class | public class Enum |
Inheritance | Enum ![]() |
Implements | IComparable, IEquatable, ISerializable |
Subclasses | AlphabeticalComparison, BooleanComparison, NumericRounding, StringCase |
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.
See also
Property | Defined 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 |
Method | Defined 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 |
name | property |
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.
public function get name():String
ordinal | property |
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).
public function get ordinal():int
Enum | () | Constructor |
public function Enum(name:String, ordinal:int)
Constructor, creates a new Enum object.
Parametersname: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).
|
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.
|
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.
|
int — a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
|
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.
|
Boolean — true 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.
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.
ReturnsString — 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.
Returnsint — The primitive value of the object. In this case, the ordinal value.
|
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); } }
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.