| # Section 8.11.1.1: $ENUMS |

###### abstract class $ENUMS{T} < $IS_EQ, $HASH, $IMMUTABLE, $INSTR, $ANCHORED_FMT

#### Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

types
SAME = object_type ;
$ENUMS_T = set of object_type
state
multi : $ENUMS_T
inv multi_types ==
forall obj in set multi_types & sub_type($ENUMS_T,obj)

NOTE | See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstraction models a generic enumeration coding facility. The specification defines that the numeric encoding of zero is not a valid enumeration value. The values may otherwise commence with the code number given by the offset feature.

#### create

This creation operation takes the given numeric argument value and produces a corresponding enumeration value. Note that the value which would be returned by a call to enum need not be the same as val.

create | (
| val : CARD
| ) : SAME

##### Formal Signature

create(val : CARD) res : SAME

##### Pre-condition

pre (val >= offset)
and (val < (offset + cardinality))

##### Post-condition

post card(res) = val

This creation feature provides a new enumeration value from the given numeric argument.

#### create

This variant of the enumeration creation operation takes the given string argument value and produces a corresponding enumeration value.

Note that the valid strings are required to be language and culture dependent at the time of execution of the program containing classes sub-typing from this abstraction.

create | (
| val : STR
| ) : SAME

##### Formal Signature

create(val : STR) res : SAME

##### Pre-condition

pre is_enum(val) = CONVERSION_RESULT.All_Right

##### Post-condition

post str(res) = val

This creation feature provides a new enumeration value from the given string argument.

#### offset

This feature enables the use of enumerations with externally defined numeric codes, by providing an offset value giving the 'numeric' first code in a contiguous sequence. If there is no externally defined offset then the 'default' value of 1 shall apply.

offset | : CARD

##### Formal Signature

offset(self : SAME) res : CARD

##### Pre-condition

The pre-condition is vacuously true since there are no arguments other than self to the operation.

##### Post-condition

In order for the card feature to be well-defined it is necessary that all enumeration values be representable as numeric values.

post forall elem in set dom self & res + elem <= CARD.maxval

This feature defines the numeric value to be assigned to the first enumeration when converted into a cardinal number (see card below).

#### cardinality

This feature defines the number of different values in the enumeration domain.

cardinality | : CARD

##### Formal Signature

cardinality(self : SAME) res : CARD

##### Pre-condition

The pre-condition is vacuously true since there are no arguments other than self to the operation.

##### Post-condition

In order for the card feature to be well-defined it is necessary that all enumeration values be representable as numeric values.

post res = card dom self

This feature defines the numeric value to be assigned to the first enumeration when converted into a cardinal number (see card below).

#### is_enum

This feature enables a program to test if the string argument is a valid representation of one of the values of the enumeration. The returned value is one of the following :-

- All_Right - the string is a valid representation.
- Out_of_Range - the string is not recognisable.
- Empty - the string is empty!

is_enum | (
| str : STR
| ) : CONVERSION_RESULTS

##### Formal Signature

is_enum(self : SAME, str : STR) res : CONVERSION_RESULTS

##### Pre-condition

Since this feature is a predicate there are no pre-conditions - ie the pre-condition is vacuously true.

##### Post-condition

post (res = CONVERSION_RESULTS.All_Right)
or (res = CONVERSION_RESULTS.Out_of_Range)
or (res = CONVERSION_RESULTS.Empty)

This feature enables a program to test if the string argument is a valid representation of one of the values of the enumeration.

#### enum

This feature provides an implementation-dependent numeric 'code' for the enumeration. The value provided does not have to be ordered numerically in the order of the enumerations given in any sub-typing class, nor does it have to bear any relation to the value returned by the card feature below.

enum | : CARD

##### Formal Signature

enum(self : SAME) res : CARD

##### Pre-condition

Since self is not of an optional type, the pre-condition is vacuously true.

##### Post-condition

Since the value is implementation-dependent the post-condition is nexessarily vacuously true.

This feature provides an implementation-dependent internal code for the enumeration.

#### card

This feature provides a unique numeric code value corresponding to the enumeration value. The range of possible values extends from offset up to (offset + cardinality - 1) in the order in which the enumeration values are listed below. This number may bear no relation to the code number returned by the enum operation above.

card | : CARD

##### Formal Signature

card(self : SAME) res : CARD

##### Pre-condition

Since self is not of an optional type, the pre-condition is vacuously true.

##### Post-condition

post (res >= offset)
and (res < offset + cardinality)

This feature provides a numeric value corresponding to the enumeration. The value returned increases monotonically from offset in the order in which the values in the enumeration list below are written.

| Language Index |  | Library Index |  | Non-numeric Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Tuesday, 30 May 2000. |