Index: doc/proposals/enum.tex =================================================================== --- doc/proposals/enum.tex (revision e71b09ae00f2abd7047a70e3eaf09175d9b787f0) +++ doc/proposals/enum.tex (revision bd674421bdcbbd7f54eef5135c34f20906db12b0) @@ -121,9 +121,9 @@ Naming values is a common practice in mathematics and engineering, e.g., $\pi$, $\tau$ (2$\pi$), $\phi$ (golden ratio), MHz (1E6), etc. Naming is also commonly used to represent many other numerical phenomenon, such as days of the week, months of a year, floors of a building (basement), time (noon, New Years). -Many programming languages capture this important capability through a mechanism called an \newterm{enumeration}. +Many programming languages capture this important software-engineering capability through a mechanism called an \newterm{enumeration}. An enumeration is similar to other programming-language types by providing a set of constrained values, but adds the ability to name \emph{all} the values in its set. Note, all enumeration names must be unique but different names can represent the same value (eight note, quaver), which are synonyms. -Specifically, an enumerated type is a type whose values are restricted to a fixed set of named constants. +Specifically, an enumerated type restricts its values to a fixed set of named constants. Fundamentally, all types are restricted to a fixed set of values because of the underlying von Neumann architecture, and hence, to a corresponding set of constants, e.g., @3@, @3.5@, @3.5+2.1i@, @'c'@, @"abc"@, etc. However, the values for basic types are not named, other than the programming-language supplied constants. @@ -132,5 +132,5 @@ \section{C-Style Enum} -The C-Style enumeration has the following syntax and semantics. +The C-Style enumeration has the following syntax and semantics, and is representative of enumerations in many other programming languages (see Section~\ref{s:RelatedWork}). \begin{lstlisting}[label=lst:weekday] enum Weekday { Monday, Tuesday, Wednesday, Thursday@ = 10@, Friday, Saturday, Sunday }; @@ -139,31 +139,35 @@ \end{lstlisting} Here, the enumeration type @Weekday@ defines the ordered \newterm{enumerator}s @Monday@, @Tuesday@, @Wednesday@, @Thursday@, @Friday@, @Saturday@ and @Sunday@. -The successor of @Tuesday@ is @Monday@ and the predecessor of @Tuesday@ is @Wednesday@. -A C enumeration is implemented by an integral type, with consecutive enumerator values assigned by the compiler starting at zero or the next explicitly initialized value. -For example, @Monday@ to @Wednesday@ have values 0--2 implicitly set by the compiler, @Thursday@ is explicitly set to @10@, and @Friday@ to @Sunday@ have values 11--13 implicitly set by the compiler. - -There are 3 attributes for an enumeration: \newterm{position}, \newterm{label}, and \newterm{value}: +By convention, the successor of @Tuesday@ is @Monday@ and the predecessor of @Tuesday@ is @Wednesday@, independent of the associated enumerator constants. +Because an enumerator is a constant, it cannot appear in a mutable context, e.g. @Mon = Sun@ is meaningless, and has no address, it is an rvalue\footnote{ +The term rvalue defines an expression that can only appear on the right-hand side of an assignment.}. +Enumerators without explicitly designated constants are auto-initialized by the compiler: from left to right, starting at zero or the next explicitly initialized constant, incrementing by @1@. +For example, @Monday@ to @Wednesday@ are implicitly assigned with constants 0--2, @Thursday@ is explicitly set to constant @10@, and @Friday@ to @Sunday@ are implicitly assigned with constants 11--13. +Hence, there are 3 universal enumeration attributes: \newterm{position}, \newterm{label}, and \newterm{value}: \begin{cquote} \small\sf\setlength{\tabcolsep}{3pt} \begin{tabular}{rccccccccccc} -@enum@ Weekday \{ & Monday, & Tuesday, & Wednesday, & Thursday=10, & Friday, & Saturday, & Sunday \}; \\ -\it position & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\ -\it label & Monday & Tuesday & Wednesday & Thursday & Friday & Saturday & Sunday \\ -\it value & 0 & 1 & 2 & {\color{red}10}& 11 & 12 & 13 +@enum@ Weekday \{ & Monday, & Tuesday, & Wednesday, & Thursday = 10,& Friday, & Saturday, & Sunday \}; \\ +\it\color{red}position & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\ +\it\color{red}label & Monday & Tuesday & Wednesday & Thursday & Friday & Saturday & Sunday \\ +\it\color{red}value & 0 & 1 & 2 & {\color{red}10}& 11 & 12 & 13 \end{tabular} \end{cquote} - -The enumerators of an enumeration are unscoped, i.e., enumerators declared inside of an @enum@ are visible in the enclosing scope of the @enum@ type. +Finally, C enumerators are \newterm{unscoped}, i.e., enumerators declared inside of an @enum@ are visible in the enclosing scope of the @enum@ type. + +In theory, a C enumeration \emph{variable} is an implementation-defined integral type large enough to hold all enumerated values. +In practice, since integral constants in C have type @int@ (unless qualified with a size suffix), C uses @int@ as the underlying type for enumeration variables. Furthermore, there is an implicit bidirectional conversion between an enumeration and integral types. \begin{lstlisting}[label=lst:enum_scope] { enum Weekday { ... }; $\C{// enumerators implicitly projected into local scope}$ - Weekday weekday = Monday; + Weekday weekday = Monday; $\C{// weekday == 0}$ weekday = Friday; $\C{// weekday == 11}$ - int i = Sunday $\C{// i == 13}$ - weekday = 10000; $\C{// undefined behaviour}$ + int i = Sunday $\C{// implicit conversion to int, i == 13}$ + weekday = 10000; $\C{// UNDEFINED! implicit conversion to Weekday}$ } int j = Wednesday; $\C{// ERROR! Wednesday is not declared in this scope}$ \end{lstlisting} +The implicit conversion from @int@ to an enumeration type is an unnecessary source of error. \section{\CFA-Style Enum} @@ -175,16 +179,128 @@ \CFA extends the enumeration by parameterizing the enumeration with a type for the enumerators, allowing enumerators to be assigned any values from the declared type. -\begin{lstlisting}[label=lst:color] -enum( @char@ ) Currency { Dollar = '$\textdollar$', Euro = '$\texteuro$', Pound = '$\textsterling$' }; -enum( @double@ ) Planet { Venus = 4.87, Earth = 5.97, Mars = 0.642 }; // mass -enum( @char *@ ) Colour { Red = "red", Green = "green", Blue = "blue" }; -enum( @Currency@ ) Europe { Euro = '$\texteuro$', Pound = '$\textsterling$' }; // intersection -\end{lstlisting} -The types of the enumerators are @char@, @double@, and @char *@ and each enumerator is initialized with corresponding type values. -% Only types with a defined ordering can be automatically initialized (see Section~\ref{s:AutoInitializable}). - -% An instance of \CFA-enum (denoted as @@) is a label for the defined enum name. -% The label can be retrieved by calling the function @label( )@. -% Similarly, the @value()@ function returns the value used to initialize the \CFA-enum. +Figure~\ref{f:EumeratorTyping} shows a series of examples illustrating that all \CFA types can be use with an enumeration and each type's constants used to set the enumerators. + +Typed enumerates deals with \emph{harmonizing} problem between an enumeration and its companion data. +The following example is from the \CFA compiler, written in \CC. +\begin{lstlisting} +enum integral_types { chr, schar, uschar, sshort, ushort, sint, usint, ..., NO_OF_ITYPES }; +char * integral_names[NO_OF_ITYPES] = { + "char", "signed char", "unsigned char", + "signed short int", "unsigned short int", + "signed int", "unsigned int", + ... +}; +\end{lstlisting} +The \emph{harmonizing} problem occurs because the enumeration declaration is in one header file and the names are declared in another translation unit. +It is up to the programmer to ensure changes made in one location are harmonized with the other location (by identifying this requirement within a comment). +The typed enumeration largely solves this problem by combining and managing the two data types. +\begin{lstlisting} +enum( char * ) integral_types { + chr = "char", schar = "signed char", uschar = "unsigned char", + sshort = "signed short int", ushort = "unsigned short int", + sint = "signed int", usint = "unsigned int", + ... +}; +\end{lstlisting} + +% \begin{lstlisting}[label=lst:color] +% struct S { int i, j; }; +% enum( S ) s { A = { 3, 4 }, B = { 7, 8 } }; +% enum( @char@ ) Currency { Dollar = '$\textdollar$', Euro = '$\texteuro$', Pound = '$\textsterling$' }; +% enum( @double@ ) Planet { Venus = 4.87, Earth = 5.97, Mars = 0.642 }; // mass +% enum( @char *@ ) Colour { Red = "red", Green = "green", Blue = "blue" }; +% enum( @Currency@ ) Europe { Euro = '$\texteuro$', Pound = '$\textsterling$' }; // intersection +% \end{lstlisting} + +\begin{figure} +\begin{lstlisting} +// integral + enum( @char@ ) Currency { Dollar = '$\textdollar$', Euro = '$\texteuro$', Pound = '$\textsterling$' }; + enum( @signed char@ ) srgb { Red = -1, Green = 0, Blue = 1 }; + enum( @long long int@ ) BigNum { X = 123_456_789_012_345, Y = 345_012_789_456_123 }; +// non-integral + enum( @double@ ) Math { PI_2 = 1.570796, PI = 3.141597, E = 2.718282 }; + enum( @_Complex@ ) Plane { X = 1.5+3.4i, Y = 7+3i, Z = 0+0.5i }; +// pointer + enum( @char *@ ) Names { Fred = "Fred", Mary = "Mary", Jane = "Jane" }; + int i, j, k; + enum( @int *@ ) ptr { I = &i, J = &j, K = &k }; + enum( @int &@ ) ref { I = i, J = j, K = k }; +// tuple + enum( @[int, int]@ ) { T = [ 1, 2 ] }; +// function + void f() {...} void g() {...} + enum( @void (*)()@ ) funs { F = f, G = g }; +// aggregate + struct Person { char * name; int age, height; }; + enum( @Person@ ) friends { Liz = { "Elizabeth", 22, 170 }, Beth = Liz, Jon = { "Jonathan", 35, 190 } }; +\end{lstlisting} +\caption{Enumerator Typing} +\label{f:EumeratorTyping} +\end{figure} + +\subsection{Pure Enumerators} + +An empty type, @enum()@, implies the enumerators are pure symbols without values; +hence, there is no default conversion to @int@. + +\begin{lstlisting} +enum() Mode { O_RDONLY, O_WRONLY, O_CREAT, O_TRUNC, O_APPEND }; +Mode iomode = O_RDONLY; +int i = iomode; $\C{\color{red}// disallowed}$ +sout | O_TRUNC; $\C{\color{red}// disallowed}$ +\end{lstlisting} + +\subsection{Enumerator Subset} + +If follows from enumerator typing that the type of the enumerators can be another enumerator. +\begin{lstlisting} +enum( char ) Letter { A = 'A', B = 'B', C = 'C', ..., Z = 'Z' }; +enum( Letter ) Greek { Alph = A, Beta = B, ..., Zeta = Z }; // alphabet intersection +Letter letter = A; +Greak greek = Alph; +letter = Alph; $\C{// allowed}$ +greek = A; $\C{\color{red}// disallowed}$ +\end{lstlisting} +Enumeration @Greek@ may have more or less enumerators than @Letter@, but the enumerator values must be from @Letter@. +Therefore, @Greek@ enumerators are a subset of type @Letter@ and are type compatible with enumeration @Letter@, but @Letter@ enumerators are not type compatible with enumeration @Greek@. + +\subsection{Enumeration Inheritance} + +\CFA Plan-9 inheritance may be used with enumerations. +\begin{lstlisting} +enum( char * ) Name2 { @inline Name@, Jack = "Jack", Jill = "Jill" }; +enum /* inferred */ Name3 { @inline Name2@, Sue = "Sue", Tom = "Tom" }; +\end{lstlisting} +Enumeration @Name2@ inherits all the enumerators and their values from enumeration @Name@ by containment, and a @Name@ enumeration is a subtype of enumeration @Name2@. +Note, enumerators must be unique in inheritance but enumerator values may be repeated. + +The enumeration type for the inheriting type must be the same as the inherited type; +hence the enumeration type may be omitted for the inheriting enumeration and it is inferred from the inherited enumeration, as for @Name3@. +When inheriting from integral types, automatic numbering may be used, so the inheritance placement left to right is important. + +Specifically, the inheritance relationship for Names is: +\begin{lstlisting} +Name $\(\subset\)$ Name2 $\(\subset\)$ Name3 $\(\subset\)$ const char * // enum type of Name +\end{lstlisting} +For the given function prototypes, the following calls are valid. +\begin{cquote} +\begin{tabular}{ll} +\begin{lstlisting} +void f( Name ); +void g( Name2 ); +void h( Name3 ); +void j( const char * ); +\end{lstlisting} +& +\begin{lstlisting} +f( Fred ); +g( Fred ); g( Jill ); +h( Fred ); h( Jill ); h( Sue ); +j( Fred ); j( Jill ); j( Sue ); j( "Will" ); +\end{lstlisting} +\end{tabular} +\end{cquote} +Note, the validity of calls is the same for call-by-reference as for call-by-value, and const restrictions are the same as for other types. \subsection{Enumerator Scoping} @@ -220,4 +336,8 @@ Enumeration Greek may have more or less enumerators than Letter, but the enumerator values must be from Letter. Therefore, Greek enumerators are a subset of type Letter and are type compatible with enumeration Letter, but Letter enumerators are not type compatible with enumeration Greek. + +% An instance of \CFA-enum (denoted as @@) is a label for the defined enum name. +% The label can be retrieved by calling the function @label( )@. +% Similarly, the @value()@ function returns the value used to initialize the \CFA-enum. \subsubsection{\lstinline{enumerate()}} @@ -926,28 +1046,193 @@ \section{Related Work} - -Enumerations exist in many popular programming languages, e.g., Pascal, Ada, \Csharp, \CC, Go, Java, Modula-3, Rust, Swift, Python, and Algebraic data type in functional programming. -There are a large set of overlapping features for all the languages, but each language has its own unique restrictions and extensions. - -\subsection{Pascal} +\label{s:RelatedWork} + +Enumerations exist in many popular programming languages, e.g., Pascal, Ada, \Csharp, \CC, Go, Java, Modula-3, Rust, Swift, Python, and the algebraic data-type in functional programming. +There are a large set of overlapping features among these languages, but each language has its own unique restrictions and extensions. + +\subsection{(Free) Pascal} + +Free Pascal is a modern object-oriented version of the classic Pascal programming language. +It allows a C-style enumeration type, where enumerators must be in assigned in ascending numerical order with a constant expression and the range can be non-consecutive. +\begin{lstlisting}[language=pascal,{moredelim=**[is][\color{red}]{@}{@}}] +Type EnumType = ( one, two, three, forty @= 40@, fortyone ); +\end{lstlisting} +Pseudo-functions @Pred@ and @Succ@ can only be used if the range is consecutive. +The underlying type is an implementation-defined integral type large enough to hold all enumerated values; it does not have to be the smallest possible type. +The size underlying integral type can be explicitly specified using compiler directive @$PACKENUM@~$N$, where $N$ is the number of bytes, e.g.: +\begin{lstlisting}[language=pascal,{moredelim=**[is][\color{red}]{@}{@}}] +Type @{$\color{red}\$$PACKENUM 1}@ SmallEnum = ( one, two, three ); + @{$\color{red}\$$PACKENUM 4}@ LargeEnum = ( BigOne, BigTwo, BigThree ); +Var S : SmallEnum; { 1 byte } + L : LargeEnum; { 4 bytes} +\end{lstlisting} + \subsection{Ada} +An enumeration type is defined as a list of possible values: +\begin{lstlisting}[language=ada] +type RGB is (Red, Green, Blue); +\end{lstlisting} +Like for numeric types, where e.g., 1 is an integer literal, @Red@, @Green@ and @Blue@ are called the literals of this type. +There are no other values assignable to objects of this type. + +\paragraph{Operators and attributes} ~\newline +Apart from equality (@"="@), the only operators on enumeration types are the ordering operators: @"<"@, @"<="@, @"="@, @"/="@, @">="@, @">"@, where the order relation is given implicitly by the sequence of literals: +Each literal has a position, starting with 0 for the first, incremented by one for each successor. +This position can be queried via the @'Pos@ attribute; the inverse is @'Val@, which returns the corresponding literal. In our example: +\begin{lstlisting}[language=ada] +RGB'Pos (Red) = 0 +RGB'Val (0) = Red +\end{lstlisting} +There are two other important attributes: @Image@ and @Value@. +@Image@ returns the string representation of the value (in capital letters), @Value@ is the inverse: +\begin{lstlisting}[language=ada] +RGB'Image ( Red ) = "RED" +RGB'Value ("Red") = Red +\end{lstlisting} +These attributes are important for simple IO (there are more elaborate IO facilities in @Ada.Text_IO@ for enumeration types). +Note that, since Ada is case-insensitive, the string given to @'Value@ can be in any case. + +\paragraph{Enumeration literals} ~\newline +Literals are overloadable, i.e. you can have another type with the same literals. +\begin{lstlisting}[language=ada] +type Traffic_Light is (Red, Yellow, Green); +\end{lstlisting} +Overload resolution within the context of use of a literal normally resolves which @Red@ is meant. +Only if you have an unresolvable overloading conflict, you can qualify with special syntax which @Red@ is meant: +\begin{lstlisting}[language=ada] +RGB'(Red) +\end{lstlisting} +Like many other declarative items, enumeration literals can be renamed. +In fact, such a literal is actually a function, so it has to be renamed as such: +\begin{lstlisting}[language=ada] +function Red return P.RGB renames P.Red; +\end{lstlisting} +Here, @RGB@ is assumed to be defined in package @P@, which is visible at the place of the renaming declaration. +Renaming makes @Red@ directly visible without necessity to resort the use-clause. + +Note that redeclaration as a function does not affect the staticness of the literal. + +\paragraph{Characters as enumeration literals} ~\newline +Rather unique to Ada is the use of character literals as enumeration literals: +\begin{lstlisting}[language=ada] +type ABC is ('A', 'B', 'C'); +\end{lstlisting} +This literal @'A'@ has nothing in common with the literal @'A'@ of the predefined type @Character@ (or @Wide_Character@). + +Every type that has at least one character literal is a character type. +For every character type, string literals and the concatenation operator @"&"@ are also implicitly defined. +\begin{lstlisting}[language=ada] +type My_Character is (No_Character, 'a', Literal, 'z'); +type My_String is array (Positive range <>) of My_Character; + +S: My_String := "aa" & Literal & "za" & 'z'; +T: My_String := ('a', 'a', Literal, 'z', 'a', 'z'); +\end{lstlisting} +In this example, @S@ and @T@ have the same value. + +Ada's @Character@ type is defined that way. +See Ada Programming/Libraries/Standard. + +\paragraph{Booleans as enumeration literals} ~\newline +Also Booleans are defined as enumeration types: +\begin{lstlisting}[language=ada] +type Boolean is (False, True); +\end{lstlisting} +There is special semantics implied with this declaration in that objects and expressions of this type can be used as conditions. +Note that the literals @False@ and @True@ are not Ada keywords. + +Thus it is not sufficient to declare a type with these literals and then hope objects of this type can be used like so: +\begin{lstlisting}[language=ada] +type My_Boolean is (False, True); +Condition: My_Boolean; + +if Condition then -- wrong, won't compile +\end{lstlisting} + +If you need your own Booleans (perhaps with special size requirements), you have to derive from the predefined Boolean: +\begin{lstlisting}[language=ada] +type My_Boolean is new Boolean; +Condition: My_Boolean; + +if Condition then -- OK +\end{lstlisting} + +\paragraph{Enumeration subtypes} ~\newline +You can use range to subtype an enumeration type: +\begin{lstlisting}[language=ada] +subtype Capital_Letter is Character range 'A' .. 'Z'; +type Day_Of_Week is (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday); +subtype Working_Day is Day_Of_Week range Monday .. Friday; +\end{lstlisting} + +\paragraph{Using enumerations} ~\newline +Enumeration types being scalar subtypes, type attributes such as @First@ and @Succ@ will allow stepping through a subsequence of the values. +\begin{lstlisting}[language=ada] +case Day_Of_Week'First is + when Sunday => + ISO (False); + when Day_Of_Week'Succ(Sunday) => + ISO (True); + when Tuesday .. Saturday => + raise Program_Error; +end case; +\end{lstlisting} +A loop will automatically step through the values of the subtype's range. +Filtering week days to include only working days with an even position number: +\begin{lstlisting}[language=ada] + for Day in Working_Day loop + if Day_Of_Week'Pos(Day) mod 2 = 0 then + Work_In_Backyard; + end if; + end loop; +\end{lstlisting} +Enumeration types can be used as array index subtypes, yielding a table feature: +\begin{lstlisting}[language=ada] +type Officer_ID is range 0 .. 50; +type Schedule is array (Working_Day) of Officer_ID; +\end{lstlisting} + +\begin{lstlisting}[language=ada] +type Subtype_Name is (Id1, Id2, Id3 ... ); +\end{lstlisting} +where @Id1@, @Id2@, etc. are identifiers or characters literals. +In either case, the legal values of the type are referred to as "enumeration literals." +Each of these values has a "position number" corresponding to its position in the list such that @Id1@ has position 0, @Id2@ has position 1, and the Nth value has position N-1. + +\paragraph{Attributes of Enumeration Types} ~\newline +An enumeration type, @T@, has the following attributes: @T'First@, @T'Last@, @T'Range@, @T'Pred@, @T'Succ@, @T'Min@, @T'Max@, @T'Image@, @T'Wide_Image@, @T'Value@, @T'Wide_Value@, @T'Pos@, and @T'Val@ (pronounced "T tick first", "T tick last", etc.). +Most of these are illustrated in the example program given below, and most of them produce what you would intuitively expect based on their names. + +@T'Image@ and @T'Value@ form a complementary pair of attributes. +The former takes a value in @T@ and returns a String representation of that value. +The latter takes a @String@ that is a representation of a value in @T@ and returns that value. + +@T'Pos@ and @T'Val@ form another complementary pair. +The former takes a value in @T@ and returns its position number. +The latter takes a position number and returns the corresponding value of type @T@. + + \subsection{\Csharp} \subsection{\CC} -Because \CC is backwards compatible with C, it inherited C's enumerations, except there is no implicit conversion from an integral value to an enumeration; -hence, the values in a \CC enumeration can only be its enumerators. - -\CC{11} extended enumeration with a scoped enumeration, \lstinline[language=c++]{enum class} (or \lstinline[language=c++]{enum struct}), where the enumerators are local to the enumeration and are accessed using type qualification, e.g., @Weekday::Monday@. +\CC is backwards compatible with C, so it inherited C's enumerations, except there is no implicit conversion from an integral value to an enumeration; +hence, the values in a \CC enumeration can only be its enumerators (without a cast). +There is no mechanism to iterate through an enumeration. + +\CC{11} added a scoped enumeration, \lstinline[language=c++]{enum class} (or \lstinline[language=c++]{enum struct}), so the enumerators are local to the enumeration and must be accessed using type qualification, e.g., @Weekday::Monday@. \CC{20} supports unscoped access with a \lstinline[language=c++]{using enum} declaration. -For both unscoped and scoped enumerations, the underlying type is an implementation-defined integral type that is large enough to hold all enumerated values; it does not have to be the smallest possible type. -The underlying integral type can be explicitly specified: +For both unscoped and scoped enumerations, the underlying type is an implementation-defined integral type large enough to hold all enumerated values; it does not have to be the smallest possible type. +In \CC{11}, the underlying integral type can be explicitly specified: \begin{lstlisting}[language=c++,{moredelim=**[is][\color{red}]{@}{@}}] enum class RGB : @long@ { Red, Green, Blue }; enum class rgb : @char@ { Red = 'r', Green = 'g', Blue = 'b' }; enum class srgb : @signed char@ { Red = -1, Green = 0, Blue = 1 }; +RGB colour1 = @RGB::@Red; +rgb colour2 = @rgb::@Red; +srgb colour3 = @srgb::@Red; \end{lstlisting}