DEFENUM

---

General Form:

• [FILE PRIVATE | PRIVATE | PUBLIC] DEFENUM enumname
•    DIM _constant = startvalue
•    ...
• END ENUM

Where:

• startvalue = numeric expression

---

A DEFENUM statement defines a set of constants with a similar purpose. Often a variable or a function parameter can be one of several constants and the DEFENUM statement provides a formal way of grouping the constant definitions together. In the DEFSUB declaration of a function, the AS clause can be used to specify a numeric parameter to use a certain set of constants. Note that there is currently no checking that the correct constants are being used, although a future version of KCML will make the checks. For example:

DEFENUM DayOfWeek
    DIM _DAY_Sunday=1
    DIM _DAY_Monday=2
    DIM _DAY_Tuesday=3
    DIM _DAY_Wednesday=4
    DIM _DAY_Thursday=5
    DIM _DAY_Friday=6
    DIM _DAY_Saturday=7
END ENUM
DEFSUB 'PrintDayOfWeek(Day AS DayOfWeek)
    ...
END SUB

The prefix PRIVATE or PUBLIC may be applied to DEFENUM and this is then applied to all constants defined within.

The KCML workbench is aware of enumerations and will display the enumeration name, the constant name as well as its value when tooltipping an variable typed as an enumeration.

Generated Functions

Several functions are also generated automatically to assist in the use of enumerated values. They all make use of the basic enumaration value names. Typically all members of an enumeration will have a common prefix. The basic names is the member name with the common prefix removed. The common prefix is defined to be the longest prefix containing a final underscore that all members of the enumeration have in common. Thus if the full names were _MyEnum_XOne, _MyEnum_XTwo and _MyEnum_XThree then the common prefix would be _MyEnum_ and the basic names would be XOne, XTwo and XThree.

'_Enum_XXX(BYREF e$()_KCML_DEFENUM_Entry)

This function returns an array, one element per enumeration member, describing the enumeration. The function takes on parameter which is a BYREF string array with elements from the record KCML_DEFENUM_Entry. The array is DIMmed to the correct size by the function, which returns the number of elements as the result.

// Using DayOfWeek enum defined above
DIM i
DIM e$(0)_KCML_DEFENUM_Entry
'_Enum_DayOfWeek(BYREF e$())
FOR i = 1 TO DIM(e$(), 1)
    PRINT FLD(e$(i).defenum_name$)
NEXT i

'_ToString_XXX(enumvalue, BYREF convertedstring$)

This function takes two parameters: a value and a BYREF string. An enumeration value is passed in and the corresponding basic name is returned by the string. If the value is not a member of the enumeration then this function will return FALSE.

// Using DayOfWeek enum defined above
DIM d AS DayOfWeek
DIM s$0
d = _DAY_Saturday
IF ('_tostring_dayofweek(d, BYREF s$) == TRUE)
    // In this example s$ will be Saturday
    PRINT "Today is ";s$
ELSE
    STOP "Invalid day"
END IF

'_FromString_XXX(searchstring$, BYREF convertedvalue)

This function takes two parameters: a string and a BYREF value. A string containing a basic name is passed in and the corresponding value in the second parameter. If the string is not a member of the enumeration then this function will return FALSE.

// Using DayOfWeek enum defined above
DIM d AS DayOfWeek
DIM s$0
REDIM s$ = "Saturday"
IF ('_fromstring_dayofweek(s$, BYREF d) == TRUE)
    // In this example d will be _DAY_Saturday
    PRINT "The code for ";s$; " is "; d
ELSE
    STOP "Invalid string"
END IF

ENUM_CAST

This is not a function, but a built in operator to KCML, to convert from a numeric to an enumeration type. See ENUM_CAST.