Many procedures in many libraries accept arguments from a finite set (usually a fairly small one), or subsets of a finite set to describe a certain mode of operation, or several flags to describe a mode of operation. Offering a default policy for dealing with such values fosters portable and readable code, much as records do for compound values, or multiple values for procedures computing several values.
In Lisp-family languages, it is traditional to use symbols and lists of symbols for this purpose. Symbols have at least two disadvantages: they are not "type-safe", in the sense that a single symbol may be used in more than one logically independent universe of flags; and in Scheme symbols do not have associated values. In C-family languages, enumerations have names and numeric values, by default consecutive values, but often powers of two or something externally dictated. However, the name is not accessible at runtim, and enumeration types are not really disjoint from integer types (in C++ they are statically distinct).
This SRFI instead provides something related to the enums of Java version 5 and later. These are objects of a type disjoint from all others that are grouped into enumeration types (called enum classes in Java). In Java, each enumeration type is allowed to declare the number and types of values associated with each object, but in this SRFI an enumeration object has exactly one value; this is useful when translating from C to record the numeric value, but probably has other uses as well. The universes of R6RS correspond to enum types, but they are not reified.
In this SRFI, each enum has four properties: the enum type to which it belongs, its name (a symbol), its ordinal (an exact integer), and its value (any object). An enum type provides access to all the enums that belong to it by name or ordinal.
Specialized sets of enums and specialized mappings from enums to arbitrary values will be described in future SRFIs. It is also possible to use general-purpose SRFI 113 sets and bags, hash tables from SRFI 125 or elsewhere, and SRFI 146 mappings for the same purposes.
(make-enum-type list)
Returns a newly allocated enum type containing a fixed set of newly allocated enums. Both enums and enum types are immutable, and it is not possible to create an enum except as part of creating an enum type.
The elements of list are either symbols or pairs, where each such pair has a symbol in the car and any value in the cdr. Each list element causes a single enum to be generated. whose name is specified by the symbol. All the symbols must be distinct within an enum type. The position of the element in list is the ordinal of the corresponding enum, so ordinals within an enum type are also distinct. If a value is given, it becomes the value of the enum; otherwise the enum's value is the same as the ordinal.
(enum-type enum)
Returns the enum type to which enum belongs.
(enum-name enum)
Returns the name (symbol) associated with enum.
(enum-ordinal enum)
Returns the ordinal (exact integer) associated with enum.
(enum-value enum)
Returns the value associated with enum.
The following procedures, given an enum type and the value of one of its properties, locate the enum with that value. It is not possible to find an enum based on the value property, as values need not be unique within an enum type.
(enum-name->enum enum-type symbol)
If there exists an enum named symbol belonging to enum-type, return it; otherwise return #f.
(enum-ordinal->enum exact-integer symbol)
If there exists an enum whose ordinal is exact-integer belonging to enum-type, return it; otherwise return #f.
The following convenience procedures provide enum-finding followed by access to a property.
(enum-name->ordinal enum-set symbol)
Return the ordinal of the enum which belongs to enum-type and whose name is symbol. It is an error if there is no such enum.
(enum-name->valueenum-set symbol)
Return the value of the enum which belongs to enum-type and whose name is symbol. It is an error if there is no such enum.
(enum-ordinal->name enum-set exact-integer)
Return the name of the enum which belongs to enum-type and whose ordinal is exact-integer. It is an error if there is no such enum.
(enum-ordinal->value enum-set symbol)
Return the value of the enum which belongs to enum-type and whose ordinal is exact-integer. It is an error if there is no such enum.
(enum-type-size enum-type)
Returns an exact integer equal to the number of enums in enum-type.
(enum-min enum-type)
Returns the enum belonging to enum-type whose ordinal is zero.
(enum-max enum-type)
Returns the enum belonging to enum-type whose ordinal is equal to the number of enums in the enum type minus 1.
(enum-type-enums enum-type)
Returns a list of the enums belonging to enum-type ordered by increasing ordinal.
(enum-type-names enum-type)
Returns a list of the names of the enums belonging to enum-type ordered by increasing ordinal.
(enum-type-values enum-type)
Returns a list of the values of the enums belonging to enum-type ordered by increasing ordinal.
(enum-next enum)
Returns the enum that belongs to the same enum-type as enum and has an ordinal one greater than enum. Returns #f if there is no such enum.
(enum-prev enum)
Returns the enum that belongs to the same enum-type as enum and has an ordinal one less than enum. Returns #f if there is no such enum.
(enum=? enum ...)
Returns #t if all the arguments are the same enum, and #f otherwise. It is an error to apply enum=? to enums belonging to different enum types.
(enum<? enum ...)
(enum>? enum ...)
(enum<=? enum ...)
(enum>=? enum ...)
These predicates return #t if their arguments are enums whose ordinals are in increasing, decreasing, non-decreasing, and non-increasing order respectively, and #f otherwise. It is an error if any of the arguments do not belong to the same enum type as the rest.