# (lispkit enum)
Library `(lispkit enum)` implements an API for enumeration types, enumeration values, and enumeration sets.
An enumeration type is defined by a list of tagged enumeration names. It encapsulates enumeration values which can be accesses either by name or ordinal value. Sets of these enumeration values are called enumeration sets. Each enumeration set is based on an enumeration type and contains a set of enumeration values.
## Declarative API
**(define-enum *****type-name (symbol ...) constructor*****)** 
\
\&#xNAN;**(define-enumeration *****type-name (symbol ...) constructor*****)**
The `define-enum` and `define-enumeration` forms defines an enumeration type and provide two macros for constructing its members and sets of its members.
*type-name* is an identifier that is bound as a syntactic keyword; *symbol ...* are the symbols that comprise the universe of the enumeration (in order).
`(`*type-name* *symbol*`)` checks whether the name of *symbol* is in the universe associated with *type-name*. If it is, `(`*type-name* *symbol*`)` is equivalent to *symbol*. It is a syntax violation if it is not.
*constructor* is an identifier that is bound to a syntactic form that, given any finite sequence of the symbols in the universe, possibly with duplicates, expands into an expression that evaluates to the enumeration set of those symbols.
`(`*constructor* *symbol ...*`)` checks whether every *symbol* ... is in the universe associated with *type-name*. It is a syntax violation if one or more is not. Otherwise `(`*constructor* *symbol ...*`)` is equivalent to `((enum-set-constructor (`*constructor-syntax*`)) '(`*symbol ...*`))`.
Here is a complete example:
```scheme
(define-enumeration color
(black white purple maroon)
color-set)
(color black) ⇒ black
(color purpel) ⇒ error: symbol not in enumeration universe
(enum-set->list (color-set)) ⇒ ()
(enum-set->list
(color-set maroon white)) ⇒ (white maroon)
```
## Enum types
**(enum-type? *****obj*****)** 
Returns `#t` if *obj* is an enum type, and `#f` otherwise.
**(make-enum-type *****list*****)** \
\&#xNAN;**(make-enum-type *****name list*****)**\
\&#xNAN;**(make-enum-type *****name list tag*****)**
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. *name* is the name of the enumeration as a string or symbol, *tag* is an arbitrary object attached to the enum type (which can be accessed via `enum-type-tag`).
The elements of *list* are either symbols or two-element lists, where each list has a symbol as the first element and any value as the second element (this is the enum's tag). Each list element causes a single enum to be generated, and the enum's name is specified by the symbol. It is an error unless all the symbols are 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.
Here are a few examples:
```scheme
(define color
(make-enum-type
'(red orange yellow green cyan blue violet)))
(define us-traffic-light
(make-enum-type '(red yellow green)))
(define pizza
(make-enum-type
'((margherita "tomato and mozzarella")
(funghi "mushrooms")
(chicago "deep-dish")
(hawaiian "pineapple and ham"))))
```
**(enum-type-type-tag *****enum-type*****)**
Returns the type tag, i.e. an uninterned symbol, representing the type of enums as defined by *enum-type*.
**(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 0.
**(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-tag *****enum-type*****)**
Returns the tag associated with *enum-type*.
**(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-tags *****enum-type*****)**
Returns a list of the values of the enums belonging to *enum-type* ordered by increasing ordinal.
**(enum-type-contains? *****enum-type enum*****)**
Returns `#t` if *enum* belongs to *enum-type*, and `#f` otherwise.
```scheme
(enum-type-contains? color
(enum-name->enum color 'red)) ⇒ #t
(enum-type-contains? pizza
(enum-name->enum color 'red)) ⇒ #f
```
**(enum-type-test-predicate *****enum-type*****)**
Returns a procedure which given an object, checks that this object is an enum that belongs to *enum-type*.
**(enum-set-type-test-predicate *****enum-type*****)**
Returns a procedure which given an object, checks that this object is an enum set whose type matches *enum-type*.
**(enum-name->enum *****enum-type symbol*****)**
If there exists an enum belonging to *enum-type* named *symbol*, returns it; otherwise return `#f`.
**(enum-name->ordinal *****enum-type symbol*****)**
Returns the ordinal of the enum belonging to *enum-type* whose name is *symbol*. It is an error if there is no such enum.
**(enum-name->tag *****enum-type symbol*****)**
Returns the value of the enum belonging to *enum-type* whose name is *symbol*. It is an error if there is no such enum.
**(enum-ordinal->enum *****enum-type exact-integer*****)**
If there exists an enum belonging to *enum-type* whose ordinal is *exact-integer*, returns it; otherwise return `#f`.
**(enum-ordinal->name *****enum-type exact-integer*****)**
Returns the name of the enum belonging to *enum-type* whose ordinal is *exact-integer*. It is an error if there is no such enum.
**(enum-ordinal->tag *****enum-type exact-integer*****)**
Returns the value of the enum belonging to *enum-type* whose ordinal is *exact-integer*. It is an error if there is no such enum.
## Enum values
**(enum? *****obj*****)**
Returns `#t` if *obj* is an enum, and `#f` otherwise.
**(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-tag *****enum*****)**
Returns the tag associated with *enum*.
**(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.
```scheme
(enum-name (enum-next color-red)) ⇒ orange
(enum-next (enum-max color)) ⇒ #f
```
**(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=? *****enum0 enum1 ...*****)**
Returns `#t` if all the arguments are the same enum in the sense of `eq?` (which is equivalent to having the same name and ordinal) and `#f` otherwise. It is an error to apply `enum=?` to enums belonging to different enum types.
```scheme
(enum=? color-red color-blue) ⇒ #f
(enum=? pizza-funghi
(enum-name->enum pizza 'funghi)) ⇒ #t
(enum=? color-red
(enum-name->enum color 'red)
color-blue) ⇒ #f
```
**(enum\\
\&#xNAN;**(enum>? *****enum0 enum1 ...*****)** \
\&#xNAN;**(enum<=? *****enum0 enum1 ...*****)** \
\&#xNAN;**(enum>=? *****enum0 enum1 ...*****)**
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 unless all of the arguments belong to the same enum type.
## Enum sets
**(enum-set? *****obj*****)**
Returns `#t` if *obj* is an enum set and `#f` otherwise.
**(enum-set *****enum-type enum ...*****)**
Returns an enum set that can contain enums of the type *enum-type* and containing the *enums*. It is an error unless all the *enums* belong to *enum-type*.
```scheme
(enum-set-contains?
(enum-set color color-red color-blue)
color-red) ⇒ #t
(enum-set-contains?
(enum-set color color-red color-blue)
color-orange) ⇒ #f
```
**(list->enum-set *****enum-type list*****)**
Returns an enum set with the specified *enum-type* that contains the members of *list*. *list* may contain enums, enum names, or enum ordinals. It is an error unless all the members refer to enums belonging to *enum-type*.
**(enum-set-copy *****enum-set*****)**
Returns a copy of *enum-set*.
**(enum-set-empty? *****enum-set*****)**
Returns `#t` if *enum-set* is empty, and `#f` otherwise.
**(enum-set-contains? *****enum-set enum*****)**
Returns `#t` if *enum* is a member of *enum-set*. It is an error if *enum* does not belong to the same enum type as the members of *enum-set*.
**(enum-set-disjoint? *****enum-set1 enum-set2*****)**
Returns `#t` if *enum-set1* and *enum-set2* do not have any enum objects in common, and `#f` otherwise.
```scheme
(define reddish
(list->enum-set
(map (lambda (name) (enum-name->enum color name))
'(red orange))))
(define ~reddish
(list->enum-set
(map (lambda (name) (enum-name->enum color name))
'(yellow green cyan blue violet))))
(enum-set-disjoint? color-set reddish) ⇒ #f
(enum-set-disjoint? reddish ~reddish) ⇒ #t
```
**(enum-set-projection *****enum-set1 enum-set2*****)**
Projects *enum-set1* into the universe of *enum-set2*, dropping any elements of *enum-set1* that do not belong to the universe of *enum-set2*. If *enum-set1* is a subset of the universe of its second, no elements are dropped, and the injection is returned.
```scheme
(let ((e1 (make-enumeration '(red green blue black)))
(e2 (make-enumeration '(red black white))))
(enum-set->list (enum-set-projection e1 e2))))
⇒ (red black)
```
**(enum-set-member? *****symbol enum-set*****)** \
\&#xNAN;**(enum-set-subset? *****enum-set1 enum-set2*****)**
The `enum-set-member?` procedure returns `#t` if its first argument is an element of its second argument, `#f` otherwise.
The `enum-set-subset?` procedure returns `#t` if the universe of *enum-set1* is a subset of the universe of *enum-set2* (considered as sets of symbols) and every element of *enum-set1* is a member of *enum-set2*. It returns `#f` otherwise.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(c (enum-set-constructor e)))
(list (enum-set-member? 'blue (c '(red blue)))
(enum-set-member? 'green (c '(red blue)))
(enum-set-subset? (c '(red blue)) e)
(enum-set-subset? (c '(red blue)) (c '(blue red)))
(enum-set-subset? (c '(red blue)) (c '(red)))
(enum-set=? (c '(red blue)) (c '(blue red)))))
⇒ (#t #f #t #t #f #t)
```
**(enum-set=? *****enum-set1 enum-set2*****)**
Returns `#t` if the members of *enum-set-1* are the same as of *enum-set-2*. It is an error if the members of the enum sets do not belong to the same type.
**(enum-set\
Returns `#t` if the members of *enum-set-1* are a proper subset of *enum-set-2*. It is an error if the members of the enum sets do not belong to the same type.
**(enum-set>? *****enum-set1 enum-set2*****)**
Returns `#t` if the members of *enum-set-1* are a proper superset of *enum-set-2*. It is an error if the members of the enum sets do not belong to the same type.
**(enum-set<=? *****enum-set1 enum-set2*****)**
Returns `#t` if the members of *enum-set-1* are a subset of *enum-set-2*. It is an error if the members of the enum sets do not belong to the same type.
**(enum-set>=? *****enum-set1 enum-set2*****)**
Returns `#t` if the members of *enum-set-1* are a superset of *enum-set-2*. It is an error if the members of the enum sets do not belong to the same type.
**(enum-set->list *****enum-set*****)**
Returns a list of the names of enums that belong to *enum-set*. The list is in increasing order of the enums.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(c (enum-set-constructor e)))
(enum-set->list (c '(blue red))))
⇒ (red blue)
```
**(enum-set->enum-list *****enum-set*****)**
Returns a list containing the enum members of *enum-set*. The list is in increasing order of the enums.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(c (enum-set-constructor e)))
(enum-set->enum-list (c '(blue red))))
⇒ (# #)
```
**(enum-set-next *****enum-set e*****)**
Returns the ordinally next enum in *enum-set* following enum *e*. *e* is either a name, ordinal, or enum value. `enum-set-next` returns `#f` if there is no next enum.
**(enum-set-type *****enum-set*****)**
Returns the enum type associated with *enum-set*.
**(enum-set-bitset *****enum-set*****)**
Returns a bit set (as defined by library `(lispkit bitset)`) representing all ordinals of *enum-set*.
**(enum-set-size *****enum-set*****)**
Returns the number of elements in *enum-set*.
**(enum-set-adjoin! *****enum-set e ...*****)**
Adds enums *e ...* to *enum-set*. Enums are defined either via a name, an ordinal, or an enum object. It is an error if the enums denoted by *e ...* do not all belong to the same enum type.
**(enum-set-adjoin-all! *****enum-set list*****)**
*list* is a list of enums. Enums are defined either via a name, an ordinal, or an enum object. `enum-set-adjoin-all!` adds all enums of *list* to *enum-set*. It is an error if the enums denoted by *list* do not all belong to the same enum type.
**(enum-set-delete! *****enum-set e ...*****)**
Removes enums *e ...* from *enum-set*. Enums are defined either via a name, an ordinal, or an enum object. It is an error if the enums denoted by *e ...* do not all belong to the same enum type.
**(enum-set-delete-all! *****enum-set list*****)**
*list* is a list of enums. Enums are defined either via a name, an ordinal, or an enum object. `enum-set-delete-all!` removes all enums of *list* from *enum-set*. It is an error if the enums denoted by *list* do not all belong to the same enum type.
**(enum-set-union *****enum-set1 enum-set2*****)** \
\&#xNAN;**(enum-set-intersection *****enum-set1 enum-set2*****)** \
\&#xNAN;**(enum-set-difference *****enum-set1 enum-set2*****)**
Arguments *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
The `enum-set-union` procedure returns the union of *enum-set1* and *enum-set2*. The `enum-set-intersection` procedure returns the intersection of *enum-set1* and *enum-set2*. The `enum-set-difference` procedure returns the difference of *enum-set1* and *enum-set2*.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(c (enum-set-constructor e)))
(list (enum-set->list (enum-set-union (c '(blue)) (c '(red))))
(enum-set->list
(enum-set-intersection (c '(red green)) (c '(red blue))))
(enum-set->list
(enum-set-difference (c '(red green)) (c '(red blue))))))
⇒ ((red blue) (red) (green))
```
**(enum-set-xor *****enum-set1 enum-set2*****)**
Procedure `enum-set-xor` returns the exclusive disjunction of *enum-set1* and *enum-set2*. Arguments *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
**(enum-set-complement *****enum-set*****)**
Returns *enum-set*'s complement with respect to its universe.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(c (enum-set-constructor e)))
(enum-set->list (enum-set-complement (c '(red)))))
⇒ (green blue)
```
**(enum-set-union! *****enum-set1 enum-set2*****)**
Creates the union of *enum-set1* and *enum-set2* and stores its result in *enum-set1*. *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
**(enum-set-intersection! *****enum-set1 enum-set2*****)**
Creates the intersection of *enum-set1* and *enum-set2* and stores its result in *enum-set1*. *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
**(enum-set-difference! *****enum-set1 enum-set2*****)**
Creates the set difference between *enum-set1* and *enum-set2* and stores its result in *enum-set1*. *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
**(enum-set-xor! *****enum-set1 enum-set2*****)**
Creates the exclusive disjunction between *enum-set1* and *enum-set2* and stores its result in *enum-set1*. *enum-set1* and *enum-set2* must be enumeration sets that have the same enumeration type.
**(enum-set-complement! *****enum-set*****)**
Replaces *enum-set* with its complement with respect to the type of *enum-set*.
**(enum-set-indexer *****enum-set*****)**
Returns a unary procedure that, given a symbol that is in the universe of *enum-set*, returns its 0-origin index within the canonical ordering of the symbols in the universe; given a value not in the universe, the unary procedure returns `#f`.
```scheme
(let* ((e (make-enumeration '(red green blue)))
(i (enum-set-indexer e)))
(list (i 'red) (i 'green) (i 'blue) (i 'yellow)))
⇒ (0 1 2 #f)
```
The `enum-set-indexer` procedure could be defined as follows using the `memq` procedure:
```scheme
(define (enum-set-indexer set)
(let* ((symbols (enum-set->list (enum-set-universe set)))
(cardinality (length symbols)))
(lambda (x)
(cond ((memq x symbols) =>
(lambda (probe) (- cardinality (length probe))))
(else #f)))))
```
**(enum-set-any? *****pred enum-set*****)**
Returns `#t` if any application of *pred* to the elements of *enum-set* returns true, and `#f` otherwise.
**(enum-set-every? *****pred enum-set*****)**
Returns `#t` if every application of *pred* to the elements of *enum-set* returns true, and `#f` otherwise.
**(enum-set-count *****pred enum-set*****)**
Returns an exact integer, the number of elements of *enum-set* that satisfy *pred*.
**(enum-set-map->list *****proc enum-set*****)**
Invokes *proc* on each member of *enum-set* in increasing ordinal order. The results are returned as a list.
**(enum-set-for-each *****proc enum-set*****)**
Invokes *proc* on each member of *enum-set* in increasing ordinal order and discards the rest.
**(enum-set-fold *****proc nil enum-set*****)**
The current state is initialized to *nil*, and *proc* is invoked on each element of *enum-set* in increasing ordinal order and the current state, setting the current state to the result. The algorithm is repeated until all the elements of *enum-set* have been processed. Then the current state is returned.
**(enum-set-filter *****pred enum-set*****)**
Returns an enum set containing the enums in *enum-set* that satisfy *pred*.
**(enum-set-remove *****pred enum-set*****)**
Returns an enum set containing the enums in *enum-set* that do not satisfy *pred*.
## R6RS Compatibility
**(make-enumeration *****symbol-list*****)**
Argument *symbol-list* must be a list of symbols. The `make-enumeration` procedure creates a new enumeration type whose universe consists of those symbols (in canonical order of their first appearance in the list) and returns that universe as an enumeration set whose universe is itself and whose enumeration type is the newly created enumeration type.
**(enum-set-universe *****enum-set*****)**
Returns the set of all symbols that comprise the universe of its argument *enum-set*, as an enumeration set.
**(enum-set-constructor *****enum-set*****)**
Returns a unary procedure that, given a list of symbols that belong to the universe of *enum-set*, returns a subset of that universe that contains exactly the symbols in the list. The values in the list must all belong to the universe.
**(enum-constructor *****enum-set*****)**
Given an enum set, `enum-constructor` returns a procedure which takes an enum name and returns the corresponding enum object.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.lisppad.app/libraries/lispkit/lispkit-enum.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.