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 or Inherits 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:

See @Option Directive for more information.

See also