Enum
Statement
Declares an enumeration and specifies its members.
Syntax
[ modifiers ] _
Enum enumeration_name [ Is base_type ]
member_name [ = member_data ]
…
End [ Enum ]
Parts
modifiers
Optional modifiers:
@Closed
– The enumeration cannot be extended with new members. But you can make a new enumeration that extends a closed one.@Deprecated
– See @Deprecated.@Flags
– Changes the enumeration into a set of bit flags.@MustUse
– Code that calls a procedure that returns the enumeration type must use the result. See @MustUse.
enumeration_name
- Mandatory name for the enumeration. Names ignore letter case.
Is
- A keyword before
base_type
. - You can also use one of the non-reserved keywords
Extends
orInherits
as an alternative. base_type
- A numeric data type,
String
, or a different enumeration. The data type sets the range of possible values and the minimum value. An enumeration must have the modifier@Closed
to be extended. - Optional in the usual construct.
- With
@Flags
: Mandatory integer data type or a different enumeration with@Flags
. Only an enumeration with@Flags
can extend an enumeration with@Flags
. member_name
- Mandatory name
- You can put one or more members on one line.
Use a semicolon (
;
) between each member on the same line. A semicolon is also permitted at the end of a line. - You can use the modifier
@Deprecated
before a member. If you try to use such members, the compiler shows a warning. But@Deprecated
is applicable to only one member. If you use it on a line with semicolons, the compiler will show a different warning. member_data
- Optional constant expression.
It must have the same type as
base_type
, or automatically convert to that type. - Mandatory with the directive
@Option Enum Equals
. - Not permitted without
base_type
. End
- Completes the statement.
You can also use
End Enum
. - You can change the syntax of this part. See @Option Directive for more information.
Instructions
An enumeration is a type of class that lets you easily declare many related constants. Each constant is an object with the data type of the enumeration.
An enumeration can be as easy as what follows:
Enum direction
North
South
East
West
End
Alternatively, you can write many constants on one line. You write a semicolon between each constant.
Enum direction
North; South; East; West
End
If you convert an enumeration constant to a string, the result is the name of the constant.
PrintLine direction.North
' Output:
' North
You can give members some related data:
Enum color Is Int32
RED = %X0FF0000
GREEN = %X00FF00
BLUE = %X0000FF
End
You can use strings, Characters, integers, floating-point, or fixed-point data types. Each value must be different, but it is not necessary to initialize each constant. A constant without an initializer gets a value automatically.
For number types, the initial constant gets the default value of the type. Each subsequent member adds one to the value before it.
For String
, each member without an initializer gets the name of the member as a string.
The code that follows shows how easy it is to add string values to the initial example.
Enum direction Is String
North ' = "North"
South ' = "South"
East ' = "East"
West ' = "West"
End
You can get access to the related data of an enumeration with the dictionary-access operator (!
).
Print direction!North
' Output:
' North
And below is an example where the strings are not the same as the name.
You get access to the related data of an enumeration variable through the method Data
.
Enum TopWebsite Is String
GoogleSearch = "google.com"
YouTube = "youtube.com"
Facebook = "facebook.com"
Wikipedia = "wikipedia.org"
End
Var site As TopWebsite = TopWebsite.Wikipedia
PrintLine $"The address of {site} is <{site.Data()}>."
' Output:
' The address of Wikipedia is <wikipedia.org>.
You can make an enumeration of the planets:
Enum Planet Is Int16
Mercury = 1; Venus; Earth; Mars; Jupiter; Uranus; Neptune
End
' Get planet by index. Variable must be nullable.
Var #possiblePlanet = Planet(3)
' Variable has the value Planet.Earth.
' Try to find the tenth planet.
#possiblePlanet = Planet(10)
' Variable has the value #Null.
@Flags
The construct with the modifier @Flags
must have a related value with an integer data type.
Each member without an initializer gets the value with the “least significant bit” not used at that point.
Thus the initial member has a default value of one, the second is 2, the third is 4, the fourth is 8, etc.
base_type
is usually one of the primitive integer types:
Int8
, UInt8
, Int16
, UInt16
, Int32
, UInt32
, Int64
, UInt64
, Int128
, or UInt128
.
If base_type
is an enumeration with @Flags
, the new statement is an extension to the flags.
base_type
must have one or more bits available.
In the example that follows, the comment after each member shows two numbers.
The left number is the decimal (base-10) value automatically assigned to the constant.
The right number (in parentheses) is the same value in binary (base-2).
The comment after End Enum
shows all the bits used by this enumeration.
@Flags @Closed
Enum Days Is Int8
None = 0
Monday ' = 1 (00000001)
Tuesday ' = 2 (00000010)
Wednesday ' = 4 (00000100)
Thursday ' = 8 (00001000)
Friday ' = 16 (00010000)
Saturday ' = 32 (00100000)
Sunday ' = 64 (01000000)
End Enum ' Total 127 (01111111)
Var weekend As Days = Days.Saturday Or Days.Sunday
PrintLine weekend
' Output:
' Saturday, Sunday
Var legDays = Days.Monday Or Days.Wednesday
Var upperBodyDays = Days.Tuesday Or Days.Friday
Var restDays = weekend Or (Not legDays And Not upperBodyDays)
PrintLine restDays
' Output:
' Thursday, Saturday, Sunday
Aliases
Aliases are not possible, because two constants cannot refer to the same object.
But, you can use Const
to make something almost the same.
Enum TrafficLight
RED; YELLOW; GREEN
END
Const AMBER = TrafficLight.YELLOW
We do not recommend such aliases, because they can cause problems.
You cannot use the qualified name TrafficLight.AMBER
.
Also, when you use Print
(or other string conversions) with AMBER
, the result is "YELLOW"
.
Using enumeration types with Select…Case
When you use the statement Select…Case
with the modifier @Strict
, the compiler tries to be as correct as possible.
If the test expression is an enumeration type, you must do a test for all the values in the given enumeration.
Also, if you add one or more members to the enumeration, the program will not compile until you add tests for them.
If you start with the code for TrafficLight
from above.
Then, you add a statement to do tests for all the members with Select
.
Subsequently, you add a new member for lights that flash yellow. But when you try to compile, you get an error.
Enum TrafficLight
RED; YELLOW; GREEN
FLASH_YELLOW
End Enum
Var light As TrafficLight
' ...
' Error: "@STRICT SELECT is missing test(s) for enumeration TrafficLight".
@Strict Select light
Case TrafficLight.RED
' Red light.
Case TrafficLight.YELLOW
' Yellow light.
Case TrafficLight.GREEN
' Green light.
End Select
It is necessary to add a new test.
' ...
' Green light.
Case TrafficLight.FLASH_YELLOW
' Flashing yellow light.
End Select
Changes in syntax with @Option
There are three areas where you can change the syntax of the statement:
@Option Type Extends
,@Option Type Inherits
,@Option Type Is
@Option Enum Equals
@Option End Block
and@Option End
See @Option Directive for more information.