Enum Statement and Associated Built-in Functions

ENUM Statement in Sheerpower

The ENUM statement defines a related set of named numeric constants. Values can be assigned explicitly or generated automatically in sequence.

Enums are useful for representing states, choices, categories, command words, and other sets of related values. They improve readability by replacing unexplained numeric values with meaningful names.

Syntax

In this syntax:

enum_name

The name of the enum type.

name1, name2, name3, ...

The names of the enum members. When no explicit values are supplied, Sheerpower assigns values automatically, starting with 1 and increasing by 1 for each following member.

You can also assign explicit numeric values if required:

When a member does not include an explicit value, Sheerpower assigns it the value of the preceding member plus 1. It is recommended that you do not use values of zero or duplicate values. This makes checking for unknown enum values easier.

Example: Traffic Light States

Explanation

In this example, the ENUM statement defines three traffic-light states. Because no explicit values are supplied, Sheerpower assigns the following values:

• traffic_light->red is 1.
• traffic_light->yellow is 2.
• traffic_light->green is 3.

The current state is set to yellow. The select case statement then selects the action associated with that state.

The size(enum_name, 2) function returns the number of members in an enum. In this example, it returns 3.

Using an enum improves readability by replacing hardcoded numeric values with meaningful names. It also reduces errors and makes the program easier to maintain.

Explicit Values

Enum members can be assigned specific numeric values:

Members following an explicitly assigned value continue sequentially unless another explicit value is supplied:

Best Practices

Use meaningful and consistent member names. Keep each enum focused on one concept, such as states, categories, commands, or options.

Avoid unnecessarily long names that make expressions difficult to read. The enum type name should provide enough context to keep its member names concise.

Unless you have special case needs, there is no need to specify any values in your enum statement.

Using enumname$() with Enums

The enumname$() function converts an assigned enum value into its corresponding member name. It is useful for error reporting, logging, debugging, and displaying enum values.

Syntax

enum_type

An enum type declared with the ENUM statement.

value

The assigned numeric value whose member name is required.

name$

The matching enum member name.

Example

When a matching member is found, enumname$() returns its name. If no member has the supplied value, it returns the value inside question marks and sets _integer to zero.

Avoiding Hardcoded Member Names

Using enumname$() avoids duplicating enum member names as string literals.

If a member is renamed, code that obtains the name through enumname$() remains synchronized with the enum declaration.

enumvalue() - Convert an Enum Member Name to Its Value

The enumvalue() function looks up an enum member by name and returns the numeric value assigned to that member.

It is the inverse of enumname$():

The name comparison is case-insensitive. Therefore, "yellow", "Yellow", and "YELLOW" all match the same enum member.

Syntax

enum_type

An enum type declared with the ENUM statement.

name$

The enum member name to find. The comparison is case-insensitive.

result

The numeric value assigned to the matching enum member. If no member matches, the function returns zero.

Assigned Values and Ordinal Positions

Every enum member has both an assigned numeric value and an ordinal position.

The assigned value is the number associated with the member. The ordinal is the member's position in the enum declaration, independent of its assigned value.

The first member has ordinal 1, the second has ordinal 2, and so on.

Detecting a Successful Lookup

After enumvalue() performs a lookup, _integer contains the ordinal position of the matching member.

If no member matches, _integer is zero. Therefore, the reliable not-found test is:

Why _integer Contains the Ordinal

The value returned by enumvalue() cannot reliably indicate whether the lookup succeeded because zero may be a valid enum value.

Both calls return zero. However, _integer distinguishes the successful lookup from the failed lookup:

• "off" matches the first member, so _integer is 1.
• "bogus" does not match a member, so _integer is 0.

Using the ordinal guarantees that every successful lookup sets _integer to a value greater than zero. Zero is reserved exclusively for a failed lookup.

Names That Do Not Match

An unknown name does not raise an exception. Instead, enumvalue() returns zero and sets _integer to zero.

Validating User or Configuration Input

A common use of enumvalue() is converting a text setting into an enum value while detecting spelling errors or unsupported values.

Converting a Stored Name Back to a Value

Use enumname$() and enumvalue() together when enum member names are stored in a file, database, or configuration setting.

Converting a Web Form Value

A web form can submit an enum member name. The program can convert the name and substitute a default when the submitted name is not recognized.

Parsing Keywords

The function can recognize enum member names while processing tokens or command words.

Unknown words are ignored because they set _integer to zero.

Using the Ordinal Position

The ordinal stored in _integer can be used as an index into an array containing information associated with each enum member.

In this example, value is 300 and ordinal is 3.

Quick Reference

Comparing enumname$() and enumvalue()

The two enum lookup functions are inverses of each other, and they treat _integer differently. enumname$() places the matched value in _integer; enumvalue() places the matched ordinal position there. The table contrasts both functions side by side.