Enums and enum sets (Gauche Users’ Reference)

11.47 `srfi.209` - Enums and enum sets

Module: srfi.209 ¶

Enums are objects to represent a finite set of options. Traditionally Lisp-family languages have used symbols or keywords for the purpose, but it is error prone that you can pass arbitrary symbols which can only be checked at runtime.

The enums in this srfi allows the user to define and use enums statically, that is, checked at macro-expansion time.

There are three kind of objects involved in the enum system:

Enum type: An enum type defines all possible enums that can belong to the type. It can be created at macro-expansion time with define-enum, or at run-time with make-enum-type. It is an immutable object.
Enum: An enum is an object that belong to a certain enum type. Each enum has a name (a symbol unique within the enum type), an ordinal (nonnegative contiguous exact integer), and a value (arbitrary Scheme value, defaults to the name). Enums are instantiated at the same time as an enum type is instantiated. It is also an immutable object.
Enum set: An enum set is a subset of enums from the enums in a certain enum type. An efficient set operation over an enum set is provided.

Enum types

Macro: define-enum type-name (name-value …) make-set ¶

[SRFI-209] {srfi.209} The high-level declarative interface. This defines a new enum type and interface macros.

The enums the enum type contains are specified with name-value …, each of which must be either a symbol, or a form (symbol value). If it is a symbol, it is used both as the enum name and its value. If it is (symbol value), the symbol is used as the enum name and the value is used as its value.

The type-name argument must be an identifier and is bound to a macro, which takes a single symbol as an argument. When invoked, it expands into an enum object.

The make-set argument must also be an identifier and is bound to a macro, which takes zero or more symbols and expands into an enum set object.

Since type-name and make-set are macros, the given enum name(s) can be statically checked at expansion time.

(define-enum fruits (apple orange banana mango papaya) fruit-set)

(fruits apple) ⇒ #<enum apple>
(fruits mango) ⇒ #<enum mango>

(fruit-set oragne mango papaya)
  ⇒ #<enum-set fruits (orange mango papaya)>

Function: make-enum-type list :optional name ¶

[SRFI-209] {srfi.209} A procedural interface to create enum type and associated enums.

This procdure first creates enums according to list. Each element must be either a symbol, or a form (symbol value). If it’s the former, the symbol is used both as the enum name and its value. If it’s the latter, the symbol is used as the enum name and the value is used as its value. Note that enum objects can only be created with this procedure (or the high-level macro) along with an enum type.

Each enum also gets a nonnegative integer ordinal, in the order of list, starting from zero.

The optional name argument is a Gauche’s extension. It attaches name to the created enum-type. It is only for debugging aid, and printed when you write the enum type.

Enum type is immutable. Once created, its enum members cannot be changed.

(make-enum-type '(one two three))
  ⇒ #<enum-type (one ...)>
(make-enum-type '(one two three) 'counts)
  ⇒ #<enum-type counts>

Function: enum-type? obj ¶: [SRFI-209] {srfi.209} Returns #t if obj is an enum-type, #f otherwise.

Function: enum-type-size etype ¶: [SRFI-209] {srfi.209} Returns the number of enums the enum type etype has.

Function: enum-min etype ¶

Function: enum-max etype ¶

[SRFI-209] {srfi.209} Returns the minimun and maximum enum the enum type etype has.

(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-min fruits) ⇒ #<enum apple>
(enum-max fruits) ⇒ #<enum papaya>

They throw an error if etype has no enums.

Function: enum-type-enums etype ¶

[SRFI-209] {srfi.209} Returns a list of enums the enum type etype has, in the order of their ordinals.

(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-type-enums fruits)
  ⇒ (#<enum apple> #<enum orange> #<enum banana>
     #<enum mango> #<enum papaya>)

Function: enum-type-names etype ¶

[SRFI-209] {srfi.209} Returns a list of names of enums the enum type etype has, in the order of their ordinals.

(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-type-names fruits)
  ⇒ (apple orange banana mango papaya)

Function: enum-type-values etype ¶: [SRFI-209] {srfi.209} Returns a list of the values of the enums the enum type etype has, in the order of their ordinals.

Function: enum-type-contains? etype enum ¶: [SRFI-209] {srfi.209} Returns #t iff enum type etype contains enum, #f otherwise.

Function: enum-name->enum etype symbol ¶: [SRFI-209] {srfi.209} Returns an enum object in etype whose name is symbol. If etype doesn’t have an enum of such name, #f is returned.

Function: enum-ordinal->enum etype n ¶: [SRFI-209] {srfi.209} Returns n-th enum of etype. If n is over the range of enums in etype, #f is returned.

Function: enum-name->ordinal etype symbol ¶: [SRFI-209] {srfi.209} Returns the ordinal of the enum in etype whose name is symbol. An error is thrown if etype doesn’t have such symbol.

Function: enum-name->value etype symbol ¶: [SRFI-209] {srfi.209} Returns the value of the enum in etype whose name is symbol. An error is thrown if etype doesn’t have such symbol.

Function: enum-ordinal->name etype n ¶: [SRFI-209] {srfi.209} Returns the name of the n-th enum of etype. An error is thrown if n is out of the range.

Function: enum-ordinal->value etype n ¶: [SRFI-209] {srfi.209} Returns the value of the n-th enum of etype. An error is thrown if n is out of the range.

Function: make-enum-comparator etype ¶: [SRFI-209] {srfi.209} Returns a comparator that can compare two enums that belong to etype. See srfi.114 - Comparators, for the details of comparators.

Enums

Function: enum-type enum ¶

Function: enum-name enum ¶

Function: enum-ordinal enum ¶

Function: enum-value enum ¶

[SRFI-209] {srfi.209} Returns enum’s type (<enum-type> instance), enum’s name (symbol), enum’s ordinal (nonnegative exact integer), and enum’s value (any object), respectively.

Note that enum objects can only be constructed with the enum type it belongs (by define-enum or make-enum-type), and they are immutable.

Function: enum? obj ¶: [SRFI-209] {srfi.209} Returns #t if obj is an enum, #f otherwise.

Function: enum=? enum0 enum1 enums ... ¶
Function: enum<? enum0 enum1 enums ... ¶
Function: enum<=? enum0 enum1 enums ... ¶
Function: enum>? enum0 enum1 enums ... ¶
Function: enum>=? enum0 enum1 enums ... ¶: [SRFI-209] {srfi.209} These comapres enums by its ordinals. All the enums must belong to the same enum type, or an error is thrown.

Function: enum-next enum ¶: [SRFI-209] {srfi.209} Returns the next enum of enum, that is, an enum that belongs to the same enum type as enum and has an incremented ordinal. If enum is the last enum of its type, #f is returned.

Function: enum-prev enum ¶: [SRFI-209] {srfi.209} Returns the previous enum of enum, that is, an enum that belongs to the same enum type as enum and has a decremented ordinal. If enum is the first enum of its type, #f is returned.

Enum sets

Function: enum-type->enum-set etype ¶: [SRFI-209] {srfi.209} Returns an enum set that contains all enums in the enum type etype.

Function: enum-set etype enum … ¶: [SRFI-209] {srfi.209} Returns an enum set that contains enum … of an enum type etype. An error is thrown unless all enum … belong to etype.

Function: enum-empty-set etype ¶: [SRFI-209] {srfi.209} Returns an empty enum set for the enum type etype.

Function: list->enum-set etype enum-list ¶: [SRFI-209] {srfi.209} Returns an enum set of an enum type etype, contaning enums listed in enum-list. If enum-list contains anything other than enums from etype, an error is thrown.

Function: enum-set-projection etype-or-eset eset ¶: [SRFI-209] {srfi.209} The etype-or-eset argument must be an enum type or an enum set. Returns a new enum set on an enum type etype-or-eset (if it is an enum set, its enum type is used), which contains enums having the same names as the names of enums contained in eset. The eset’s enum type doesn’t need to be the same as the result enum set.

Function: enum-set-copy eset ¶: [SRFI-209] {srfi.209} Returns a copy of an enum set eset.

Function: enum-set? obj ¶: [SRFI-209] {srfi.209} Returns #t if obj is an enum set, #f otherwise.

Function: enum-set-contains? eset enum ¶: [SRFI-209] {srfi.209} Returns #t if enum is a member of eset, #f otherwise.

Function: enum-set-empty? eset ¶: [SRFI-209] {srfi.209} Returns a#t if eset is empty.

Function: enum-set-disjoint? eset1 eset2 ¶: [SRFI-209] {srfi.209} Returns #t if two enum sets on the same enum type share no common enums. An error is thrown unless eset1 and eset2 are for the same enum type..

Function: enum-set=? eset1 eset2 ¶
Function: enum-set<? eset1 eset2 ¶
Function: enum-set<=? eset1 eset2 ¶
Function: enum-set>? eset1 eset2 ¶
Function: enum-set>=? eset1 eset2 ¶: [SRFI-209] {srfi.209} This determines subset relationship of two enum sets. Both enum sets must be for the same enum type, or an error is thrown.

Function: enum-set-subset? eset1 eset2 ¶: [SRFI-209] {srfi.209} Returns #t if the names of the member of enum set eset1 is a subset of the names of the member of eset2. Otherwise returns #f. Unlike enum-set<?, two enum set can be of different enum types. Comparison is done with the names only.

Function: enum-set-any? pred eset ¶
Function: enum-set-every? pred eset ¶: [SRFI-209] {srfi.209} Returns #t if any or every application of proc to the elemens of enum set eset yields true. Otherwise returns #f.

Function: enum-set-type eset ¶: [SRFI-209] {srfi.209} Returns the enum type of the enum set eset.

Function: enum-set-size eset ¶: [SRFI-209] {srfi.209} Returns the number of elements in the enum set eset.

Function: enum-set->enum-list eset ¶: [SRFI-209] {srfi.209} Returns a list of enums contained in the enum set eset, in the increasing order of enumcs.

Function: enum-set-adjoin eset enum … ¶

Function: enum-set-adjoin! eset enum … ¶

[SRFI-209] {srfi.209} Returns an enum set that contains all the members in the enum set eset plus enum …. All enums must belong to the same enum type of eset.

The linear update version enum-set-adjoin! may modify eset to produce the result.

Function: enum-set-delete eset enum … ¶

Function: enum-set-delete! eset enum … ¶

[SRFI-209] {srfi.209} Returns an enum set that contains all the members in the enum set eset except enum …. All enums must belong to the same enum type of eset.

The linear update version enum-set-delete! may modify eset to produce the result.

Function: enum-set-delete-all eset list … ¶

Function: enum-set-delete-all! eset list … ¶

[SRFI-209] {srfi.209} Returns an enum set that contains all the members in the enum set eset the enums in list. An error is thrown if list contains non-enums, or enums that do not belong to the same enum type of eset.

The linear update version enum-set-delete-all! may modify eset to produce the result.

Function: enum-set-count pred eset ¶: [SRFI-209] {srfi.209} Applies pred on each enum in eset, and returns the number of times when pred yields a true value.

Function: enum-set-filter pred eset ¶
Function: enum-set-remove pred eset ¶: [SRFI-209] {srfi.209} Returns a new enum set that contains the enums that satisfy or do not satisfy pred.

Function: enum-set-map->list proc eset ¶: [SRFI-209] {srfi.209} Applies proc on each enum in eset, and returns a list of the results, in the increasing order of enums.

Function: enum-set-for-each proc eset ¶: [SRFI-209] {srfi.209} Applies proc on each enum in eset in the increasing order. The results of proc are discarded.

Function: enum-set-fold kons knil eset ¶: [SRFI-209] {srfi.209}

Function: enum-set-complement eset ¶
Function: enum-set-complement! eset ¶: [SRFI-209] {srfi.209}

Function: enum-set-union eset1 eset2 ¶
Function: enum-set-union! eset1 eset2 ¶: [SRFI-209] {srfi.209}

Function: enum-set-intersection eset1 eset2 ¶
Function: enum-set-intersection! eset1 eset2 ¶: [SRFI-209] {srfi.209}

Function: enum-set-difference eset1 eset2 ¶
Function: enum-set-difference! eset1 eset2 ¶: [SRFI-209] {srfi.209}

Function: enum-set-xor eset1 eset2 ¶
Function: enum-set-xor! eset1 eset2 ¶: [SRFI-209] {srfi.209}

R6RS enumeration compatibility

Macro: define-enumeration type-name (name-value …) make-set ¶: [SRFI-209] {srfi.209}

Function: make-enumeration symbol-list ¶: [SRFI-209] {srfi.209}

Function: enum-set-universe eset ¶: [SRFI-209] {srfi.209}

Function: enum-set-costructor eset ¶: [SRFI-209] {srfi.209}

Function: enum-set-member? symbol eset ¶: [SRFI-209] {srfi.209}

Function: enum-set-indexer eset ¶: [SRFI-209] {srfi.209}

Function: enum-set->list eset ¶: [SRFI-209] {srfi.209}

11.47 srfi.209 - Enums and enum sets

Enum types

Enums

Enum sets

R6RS enumeration compatibility

11.47 `srfi.209` - Enums and enum sets