Index: doc/theses/jiada_liang_MMath/CFAenum.tex =================================================================== --- doc/theses/jiada_liang_MMath/CFAenum.tex (revision 013935109d49125650e7608973f7bb888294a557) +++ doc/theses/jiada_liang_MMath/CFAenum.tex (revision 7d9a805bca3ecf953e60e8edbb7a5e2294e8a984) @@ -1,6 +1,6 @@ -\chapter{\CFA-Style Enum} - - -\CFA supports C-Style enumeration using the same syntax and semantics for backwards compatibility. +\chapter{\CFA Enumeration} + + +\CFA supports C enumeration using the same syntax and semantics for backwards compatibility. \CFA also extends C-Style enumeration by adding a number of new features that bring enumerations inline with other modern programming languages. @@ -16,16 +16,18 @@ Finally, qualification is provided to disambiguate any ambiguous situations. \begin{cfa} -enum C1 { First, Second, Third, Fourth }; -enum C2 { @Fourth@, @Third@, @Second@, @First@ }; -C1 p() { return Third; } $\C{// correctly resolved duplicate names}$ -C2 p() { return Fourth; } +enum E1 { First, Second, Third, Fourth }; +enum E2 { @Fourth@, @Third@, @Second@, @First@ }; +E1 p() { return Third; } $\C{// correctly resolved duplicate names}$ +E2 p() { return Fourth; } void foo() { - C1 e1 = First; C2 e2 = First; + E1 e1 = First; E2 e2 = First; e1 = Second; e2 = Second; e1 = p(); e2 = p(); $\C{// correctly resolved function call}$ - int i = @C1.@First + @C2.@First; $\C{// ambiguous without qualification}$ -} -\end{cfa} -\CFA overloading allows programmers to use the most meaningful names without fear of unresolvable clashes from included files, which are correctable with qualification. + int i = @E1.@First + @E2.@First; $\C{// disambiguate with qualification}$ + int j = @(E1)@First + @(E2)@First; $\C{// disambiguate with cast}$ +} +\end{cfa} +\CFA overloading allows programmers to use the most meaningful names without fear of name clashes from include files. +Either the type system implicitly disambiguates or the programmer explicitly disambiguates using qualification or casting. @@ -34,23 +36,22 @@ An enumeration can be scoped, so the enumerator constants are not projected into the enclosing scope, using @'!'@. \begin{cfa} -enum Weekday @!@ { /* as above */ }; -enum( char * ) Names @!@ { /* as above */ }; +enum Weekday @!@ { Mon, Tue, Wed, Thu = 10, Fri, Sat, Sun }; +enum RGB @!@ { Red, Green, Blue }; \end{cfa} Now the enumerators \emph{must} be qualified with the associated enumeration. \begin{cfa} -Weekday weekday = @Weekday@.Monday; -Names names = @Names.@Fred; -names = @Names.@Jane; +Weekday weekday = @Weekday@.Mon; +weekday = @Weekday@.Sat; +RGB rgb = RGB.Red; +rgb = RGB.Blue; \end{cfa} It is possible to toggle back to unscoping using the \CFA @with@ clause/statement (see also \CC \lstinline[language=c++]{using enum} in Section~\ref{s:C++RelatedWork}). \begin{cfa} -Weekday weekday; -with ( @Weekday@, @Names@ ) { $\C{// type names}$ - Names names = @Fred@; - names = @Jane@; - weekday = Saturday; -} -\end{cfa} -As in Section~\ref{s:EnumeratorNameResolution}, opening multiple unscoped enumerations can result in duplicate enumeration names, but \CFA type resolution and falling back to explicit qualification handles name resolution. +with ( @Weekday@, @RGB@ ) { $\C{// type names}$ + weekday = @Sun@; $\C{// no qualification}$ + rgb = @Green@; +} +\end{cfa} +As in Section~\ref{s:EnumeratorNameResolution}, opening multiple unscoped enumerations can result in duplicate enumeration names, but \CFA implicit type resolution and explicit qualification/casting handles name resolution. \section{Enumerator Typing} @@ -80,5 +81,5 @@ \begin{cfa} // integral - enum( @char@ ) Currency { Dollar = '$\textdollar$', Euro = '$\texteuro$', Pound = '$\textsterling$' }; + enum( @char@ ) Currency { Dollar = '$\textdollar$', Cent = '$\textcent$', Yen = '$\textyen$', Pound = '$\textsterling$', Euro = 'E' }; 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 }; @@ -87,5 +88,5 @@ 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" }; + enum( @const char *@ ) Name { Fred = "FRED", Mary = "MARY", Jane = "JANE" }; int i, j, k; enum( @int *@ ) ptr { I = &i, J = &j, K = &k }; @@ -98,5 +99,6 @@ // aggregate struct Person { char * name; int age, height; }; -@***@enum( @Person@ ) friends { @Liz@ = { "ELIZABETH", 22, 170 }, @Beth@ = Liz, Jon = { "JONATHAN", 35, 190 } }; +@***@enum( @Person@ ) friends { @Liz@ = { "ELIZABETH", 22, 170 }, @Beth@ = Liz, + Jon = { "JONATHAN", 35, 190 } }; \end{cfa} \caption{Enumerator Typing} @@ -140,7 +142,7 @@ \begin{cfa} enum() Mode { O_RDONLY, O_WRONLY, O_CREAT, O_TRUNC, O_APPEND }; -@***@Mode iomode = O_RDONLY; -bool b = iomode == O_RDONLY || iomode < O_APPEND; -int i = iomode; $\C{\color{red}// disallowed}$ +Mode iomode = O_RDONLY; +bool b = iomode == O_RDONLY || iomode < O_APPEND; $\C{// ordering}$ +@***@@int i = iomode;@ $\C{// disallow conversion to int}$ \end{cfa} @@ -149,6 +151,6 @@ If follows from enumerator typing that the enumerator type can be another enumerator. \begin{cfa} -enum( @char@ ) Currency { Dollar = '$\textdollar$', Euro = '$\texteuro$', Pound = '$\textsterling$' }; -enum( @Currency@ ) Europe { Euro = Currency.Euro, Pound = Currency.Pound }; // intersection +enum( @char@ ) Currency { Dollar = '$\textdollar$', Cent = '$\textcent$', Yen = '$\textyen$', Pound = '$\textsterling$', Euro = 'E' }; +enum( Currency ) Europe { Euro = Currency.Euro, Pound = Currency.Pound }; enum( char ) Letter { A = 'A', B = 'B', C = 'C', ..., Z = 'Z' }; enum( @Letter@ ) Greek { Alph = A, Beta = B, ..., Zeta = Z }; // intersection @@ -158,7 +160,7 @@ \begin{cfa} Letter letter = A; -@***@Greak greek = Beta; -letter = Beta; $\C{// allowed, letter == B}$ -greek = A; $\C{\color{red}// disallowed}$ +Greak greek = Beta; +letter = Beta; $\C{// allowed, greek == B}$ +@greek = A;@ $\C{// disallowed}$ \end{cfa} @@ -277,2 +279,46 @@ p(variable_d); // 3 \end{cfa} + + +\section{Planet Example} + +\VRef[Figure]{f:PlanetExample} shows an archetypal enumeration example illustrating all of the \CFA enumeration features. +Enumeration @Planet@ is a typed enumeration of type @MR@. +Each of the planet enumerators is initialized to a specific mass/radius, @MR@, value. +The unnamed enumeration projects the gravitational-constant enumerator @G@. +The program main iterates through the planets computing the weight on each planet for a given earth weight. + +\begin{figure} +\begin{cfa} +struct MR { double mass, radius; }; +enum( MR ) Planet { + // mass radius + MERCURY = { 3.303_E23, 2.4397_E6 }, + VENUS = { 4.869_E24, 6.0518_E6 }, + EARTH = { 5.976_E24, 6.3781_E6 }, + MARS = { 6.421_E23, 3.3972_E6 }, + JUPITER = { 1.898_E27, 7.1492_E7 }, + SATURN = { 5.688_E26, 6.0268_E7 }, + URANUS = { 8.686_E25, 2.5559_E7 }, + NEPTUNE = { 1.024_E26, 2.4746_E7 }, +}; +enum( double ) { G = 6.6743E-11 }; // universal gravitational constant (m3 kg-1 s-2) + +static double surfaceGravity( Planet p ) with( p ) { + return G * mass / ( radius * radius ); +} +static double surfaceWeight( Planet p, double otherMass ) { + return otherMass * surfaceGravity( p ); +} +int main( int argc, char * argv[] ) { + if ( argc != 2 ) exit | "Usage: " | argv[0] | "earth-weight"; + double earthWeight = convert( argv[1] ); + double mass = earthWeight / surfaceGravity( EARTH ); + for ( p; Planet ) { + sout | "Your weight on" | labelE(p) | "is" | surfaceWeight( p, mass ); + } +} +\end{cfa} +\caption{Planet Example} +\label{f:PlanetExample} +\end{figure} Index: doc/theses/jiada_liang_MMath/background.tex =================================================================== --- doc/theses/jiada_liang_MMath/background.tex (revision 013935109d49125650e7608973f7bb888294a557) +++ doc/theses/jiada_liang_MMath/background.tex (revision 7d9a805bca3ecf953e60e8edbb7a5e2294e8a984) @@ -1,24 +1,69 @@ \chapter{Background} +\lstnewenvironment{clang}[1][]{\lstset{language=[ANSI]C,escapechar=\$,moredelim=**[is][\color{red}]{@}{@},}\lstset{#1}}{} + +\CFA is a backwards-compatible extension of the C programming language. +Therefore, it must support C-style enumerations and any enumeration extensions must be intuitive to C programmers both in syntax and semantics. + +It is common for C programmers to ``believe'' there are three equivalent forms of named constants. +\begin{clang} +#define Mon 0 +static const int Mon = 0; +enum { Mon }; +\end{clang} +\begin{enumerate}[leftmargin=*] +\item +For @#define@, the programmer has to explicitly manage the constant name and value. +Furthermore, these C preprocessor macro names are outside of the C type-system, and hence cannot be overloaded, and can incorrectly change random text in a program. +\item +The same explicit management is true for the @const@ declaration, and the @const@ variable cannot appear in constant-expression locations, like @case@ labels, array dimensions,\footnote{ +C allows variable-length array-declarations (VLA), so this case does work, but it fails in \CC, which does not support VLAs, unless it is \lstinline{g++}.} immediate operands of assembler instructions, and occupy storage. +\begin{clang} +$\$$ nm test.o +0000000000000018 r Mon +\end{clang} +\item +Only the @enum@ form is managed by the compiler, is part of the language type-system, and works in all C constant-expression locations. +\end{enumerate} -\section{C-Style Enum} +\section{C \lstinline{const}} -The C-Style enumeration has the following syntax and semantics. -\begin{cfa} -enum Weekday { Monday, Tuesday, Wednesday, Thursday@ = 10@, Friday, Saturday, Sunday }; -\end{cfa} +As noted, C has the equivalent of Pascal typed @const@ declarations \see{\VRef{s:Pascal}}, with static and dynamic initialization. +\begin{clang} +static const int one = 0 + 1; $\C{// static intialization}$ +static const void * NIL = NULL; +static const double PI = 3.14159; +static const char Plus = '+'; +static const char * Fred = "Fred"; +static const int Mon = 0, Tue = Mon + 1, Wed = Tue + 1, Thu = Wed + 1, Fri = Thu + 1, + Sat = Fri + 1, Sun = Sat + 1; +void foo() { + const int r = random(); $\C{// dynamic intialization}$ + int sa[Sun]; $\C{// VLA, local scope only}$ +} +\end{clang} +Statically initialized identifiers may appear in any constant-expression context, \eg @case@. +Dynamically initialized identifiers may appear as array dimensions in @g++@, which allows variable-sized arrays. + + +\section{C Enumeration} + +The C enumeration has the following syntax and semantics. +\begin{clang} +enum Weekday { Mon, Tue, Wed, Thu@ = 10@, Fri, Sat, Sun, }; +\end{clang} Enumerators without an explicitly designated constant value are \Newterm{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@. +For example, @Mon@ to @Wed@ are implicitly assigned with constants @0@--@2@, @Thu@ is explicitly set to constant @10@, and @Fri@ to @Sun@ are implicitly assigned with constants @11@--@13@. Initialization may occur in any order. -\begin{cfa} -enum Weekday { Thursday@ = 10@, Friday, Saturday, Sunday, Monday@ = 0@, Tuesday, Wednesday }; -\end{cfa} +\begin{clang} +enum Weekday { Thu@ = 10@, Fri, Sat, Sun, Mon@ = 0@, Tue, Wed }; +\end{clang} Note, the comma in the enumerator list can be a terminator or a separator, allowing the list to end with a dangling comma. -\begin{cfa} +\begin{clang} enum Weekday { - Thursday = 10, Friday, Saturday, Sunday, - Monday = 0, Tuesday, Wednesday@,@ // terminating comma + Thu = 10, Fri, Sat, Sun, + Mon = 0, Tue, Wed@,@ // terminating comma }; -\end{cfa} +\end{clang} This feature allow enumerator lines to be interchanged without moving a comma.\footnote{ A terminating comma appears in other C syntax, \eg the initializer list.} @@ -28,25 +73,13 @@ In practice, since integral constants are used, which have type @int@ (unless qualified with a size suffix), C uses @int@ as the underlying type for enumeration variables. Finally, there is an implicit bidirectional conversion between an enumeration and its integral type. -\begin{cfa} +\begin{clang} { enum Weekday { /* as above */ }; $\C{// enumerators implicitly projected into local scope}$ - Weekday weekday = Monday; $\C{// weekday == 0}$ - weekday = Friday; $\C{// weekday == 11}$ - int i = Sunday; $\C{// implicit conversion to int, i == 13}$ + Weekday weekday = Mon; $\C{// weekday == 0}$ + weekday = Fri; $\C{// weekday == 11}$ + int i = Sun; $\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{cfa} +int j = Wed; $\C{// ERROR! Wed is not declared in this scope}$ +\end{clang} The implicit conversion from @int@ to an enumeration type is an unnecessary source of error. - -It is common for C programmers to ``believe'' there are 3 equivalent forms of constant enumeration. -\begin{cfa} -#define Monday 0 -static const int Monday = 0; -enum { Monday }; -\end{cfa} -For @#define@, the programmer has to play compiler and explicitly manage the enumeration values; -furthermore, these are independent constants outside of any language type mechanism. -The same explicit management is true for @const@ declarations, and the @const@ variable cannot appear in constant-expression locations, like @case@ labels, array dimensions,\footnote{ -C allows variable-length array-declarations (VLA), so this case does work, but it fails in \CC, which does not support VLAs, unless it is \lstinline{g++}.} and immediate operands of assembler instructions. -Only the @enum@ form is managed by the compiler, is part of the language type-system, and works in all C constant-expression locations. Index: doc/theses/jiada_liang_MMath/implementation.tex =================================================================== --- doc/theses/jiada_liang_MMath/implementation.tex (revision 013935109d49125650e7608973f7bb888294a557) +++ doc/theses/jiada_liang_MMath/implementation.tex (revision 7d9a805bca3ecf953e60e8edbb7a5e2294e8a984) @@ -548,5 +548,5 @@ \begin{cfa} enum(int) Weekday { - Monday=10, Tuesday, ... + Mon = 10, Tue, ... }; Index: doc/theses/jiada_liang_MMath/intro.tex =================================================================== --- doc/theses/jiada_liang_MMath/intro.tex (revision 013935109d49125650e7608973f7bb888294a557) +++ doc/theses/jiada_liang_MMath/intro.tex (revision 7d9a805bca3ecf953e60e8edbb7a5e2294e8a984) @@ -4,5 +4,5 @@ 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), specific times (noon, New Years). 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. +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 the set. Note, all enumeration names must be unique but different names can represent the same value (eight note, quaver), which are synonyms. @@ -11,5 +11,5 @@ Fundamentally, all enumeration systems have an \Newterm{enumeration} type with an associated set of \Newterm{enumerator} names. -An enumeration has three universal attributes, \Newterm{position}, \Newterm{label}, and \Newterm{value}, as shown by this representative enumeration, where position and value can be different. +An enumeration has three universal attributes, \Newterm{label}, \Newterm{position}, and \Newterm{value}, as shown by this representative enumeration, where position and value can be different. \begin{cquote} \small\sf\setlength{\tabcolsep}{3pt} @@ -17,14 +17,21 @@ \it\color{red}enumeration & \multicolumn{7}{c}{\it\color{red}enumerators} \\ $\downarrow$\hspace*{25pt} & \multicolumn{7}{c}{$\downarrow$} \\ -@enum@ Weekday \{ & Monday, & Tuesday, & Wednesday, & Thursday,& 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 & 3 & 4 & 5 & 6 +@enum@ Weekday \{ & Mon, & Tue, & Wed, & Thu, & Fri, & Sat, & Sun \}; \\ +\it\color{red}label & Mon & Tue & Wed & Thu & Fri & Sat & Sun \\ +\it\color{red}position & 0 & 1 & 2 & 3 & 4 & 5 & 6 \\ +\it\color{red}value & 0 & 1 & 2 & 3 & 4 & 5 & 6 \end{tabular} \end{cquote} -Here, the \Newterm{enumeration} @Weekday@ defines the ordered \Newterm{enumerator}s @Monday@, @Tuesday@, @Wednesday@, @Thursday@, @Friday@, @Saturday@ and @Sunday@. -By convention, the successor of @Tuesday@ is @Monday@ and the predecessor of @Tuesday@ is @Wednesday@, independent of the associated enumerator constant values. -Because an enumerator is a constant, it cannot appear in a mutable context, \eg @Mon = Sun@ is meaningless, and an enumerator has no address, it is an \Newterm{rvalue}\footnote{ -The term rvalue defines an expression that can only appear on the right-hand side of an assignment.}. +Here, the \Newterm{enumeration} @Weekday@ defines the ordered \Newterm{enumerator}s @Mon@, @Tue@, @Wed@, @Thu@, @Fri@, @Sat@ and @Sun@. +By convention, the successor of @Tue@ is @Mon@ and the predecessor of @Tue@ is @Wed@, independent of the associated enumerator constant values, implying an ordering among the enumerators. +As well, the value can be explicitly set so it is different from the position. +Because an enumerator is a constant, it cannot appear in a mutable context, \eg @Mon = Sun@ is meaningless, and an enumerator has no address, \ie it is an \Newterm{rvalue}\footnote{ +The term rvalue defines an expression that can only appear on the right-hand side of an assignment expression.}. + +On the surface, enumerations seem like a simple type. +However, when extended with features available in other language types, enumerations become a complex. + +The goal of this work is to to extend the simple and unsafe enumeration type in the C programming-language into a sophisticated and safe type in the \CFA programming-language, while maintain backwards compatibility with C. \section{Contributions} + Index: doc/theses/jiada_liang_MMath/relatedwork.tex =================================================================== --- doc/theses/jiada_liang_MMath/relatedwork.tex (revision 013935109d49125650e7608973f7bb888294a557) +++ doc/theses/jiada_liang_MMath/relatedwork.tex (revision 7d9a805bca3ecf953e60e8edbb7a5e2294e8a984) @@ -2,4 +2,5 @@ \label{s:RelatedWork} +\begin{comment} An algebraic data type (ADT) can be viewed as a recursive sum of product types. A sum type lists values as members. @@ -15,4 +16,5 @@ Enumerated types are a special case of product/sum types with non-mutable fields, \ie initialized (constructed) once at the type's declaration, possible restricted to compile-time initialization. Values of algebraic types are access by subscripting, field qualification, or type (pattern) matching. +\end{comment} Enumeration types exist in many popular programming languages, both past and present, \eg Pascal~\cite{Pascal}, Ada~\cite{Ada}, \Csharp~\cite{Csharp}, OCaml~\cite{OCaml} \CC, Go~\cite{Go}, Java~\cite{Java}, Modula-3~\cite{Modula-3}, Rust~\cite{Rust}, Swift~\cite{Swift}, Python~\cite{Python}. @@ -20,4 +22,5 @@ \section{Pascal} +\label{s:Pascal} \lstnewenvironment{pascal}[1][]{\lstset{language=pascal,escapechar=\$,moredelim=**[is][\color{red}]{@}{@},}\lstset{#1}}{} @@ -27,5 +30,5 @@ PI = 3.14159; Plus = '+'; Fred = 'Fred'; \end{pascal} -Here, there is no enumeration because there is no specific type (pseudo enumeration). +This mechanism is not an enumeration because there is no specific type (pseudo enumeration). Hence, there is no notion of a (possibly ordered) set, modulo the \lstinline[language=pascal]{set of} type. The type of each constant name (enumerator) is inferred from the constant-expression type. @@ -81,16 +84,16 @@ with Ada.Text_IO; use Ada.Text_IO; procedure test is - type RGB is ( @Red@, Green, Blue ); - type Traffic_Light is ( @Red@, Yellow, Green ); -- overload - procedure @Red@( Colour : RGB ) is begin -- overload - Put_Line( "Colour is " & RGB'Image( Colour ) ); - end Red; - procedure @Red@( TL : Traffic_Light ) is begin -- overload - Put_Line( "Light is " & Traffic_Light'Image( TL ) ); - end Red; + type RGB is ( @Red@, Green, Blue ); + type Traffic_Light is ( @Red@, Yellow, Green ); -- overload + procedure @Red@( Colour : RGB ) is begin -- overload + Put_Line( "Colour is " & RGB'Image( Colour ) ); + end Red; + procedure @Red@( TL : Traffic_Light ) is begin -- overload + Put_Line( "Light is " & Traffic_Light'Image( TL ) ); + end Red; begin - @Red@( Blue ); -- RGB - @Red@( Yellow ); -- Traffic_Light - @Red@( @RGB'(Red)@ ); -- ambiguous without cast + @Red@( Blue ); -- RGB + @Red@( Yellow ); -- Traffic_Light + @Red@( @RGB'(Red)@ ); -- ambiguous without cast end test; \end{ada} @@ -224,6 +227,27 @@ \lstnewenvironment{c++}[1][]{\lstset{language=[GNU]C++,escapechar=\$,moredelim=**[is][\color{red}]{@}{@},}\lstset{#1}}{} -\CC is largely backwards compatible with C, so it inherited C's enumerations. -However, the following non-backwards compatible changes have been made. +\CC has the equivalent of Pascal typed @const@ declarations \see{\VRef{s:Pascal}}, with static and dynamic initialization. +\begin{c++} +const auto one = 0 + 1; $\C{// static intialization}$ +const auto NULL = nullptr; +const auto PI = 3.14159; +const auto Plus = '+'; +const auto Fred = "Fred"; +const auto Mon = 0, Tue = Mon + 1, Wed = Tue + 1, Thu = Wed + 1, Fri = Thu + 1, + Sat = Fri + 1, Sun = Sat + 1; +int sa[Sun]; +const auto r = random(); $\C{// dynamic intialization}$ +int da[r]; $\C{// VLA}$ +\end{c++} +Statically initialized identifiers may appear in any constant-expression context, \eg @case@. +Dynamically intialized identifiers may appear as array dimensions in @g++@, which allows variable-sized arrays. +Interestingly, global \CC @const@ declarations are implicitly marked @static@ (@r@ rather than @R@). +\begin{c++} +$\$$ nm test.o +0000000000000018 @r@ Mon +\end{c++} + +\CC enumeration is largely backwards compatible with C, so it inherited C's enumerations. +However, the following non-backwards compatible changes are made. \begin{cquote} @@ -423,5 +447,5 @@ \begin{Go} const ( Mon = iota; Tue; Wed; // 0, 1, 2 - @Thu = 10@; Fri; Sat; Sun ) // 10, 10, 10, 10 + @Thu = 10@; Fri; Sat; Sun ) // 10, 10, 10, 10 \end{Go} Auto-incrementing can be restarted with an expression containing \emph{one} \lstinline[language=Go]{iota}. @@ -429,5 +453,5 @@ const ( V1 = iota; V2; @V3 = 7;@ V4 = @iota@; V5 ) // 0 1 7 3 4 const ( Mon = iota; Tue; Wed; // 0, 1, 2 - @Thu = 10;@ Fri = @iota - Wed + Thu - 1@; Sat; Sun ) // 10, 11, 12, 13 + @Thu = 10;@ Fri = @iota - Wed + Thu - 1@; Sat; Sun ) // 10, 11, 12, 13 \end{Go} Note, \lstinline[language=Go]{iota} is advanced for an explicitly initialized enumerator, like the underscore @_@ identifier. @@ -1200,61 +1224,41 @@ \lstnewenvironment{python}[1][]{\lstset{language=Python,escapechar=\$,moredelim=**[is][\color{red}]{@}{@},}\lstset{#1}}{} -An @Enum@ is a set of symbolic names bound to unique values. -They are similar to global variables, but they offer a more useful @repr()@, grouping, type-safety, and a few other features. - -They are most useful when you have a variable that can take one of a limited selection of values. For example, the days of the week: -\begin{python} ->>> from enum import Enum ->>> class Weekday(Enum): -... MONDAY = 1 -... TUESDAY = 2 -... WEDNESDAY = 3 -... THURSDAY = 4 -... FRIDAY = 5 -... SATURDAY = 6 -... SUNDAY = 7 -\end{python} -Or perhaps the RGB primary colors: -\begin{python} ->>> from enum import Enum ->>> class Color(Enum): -... RED = 1 -... GREEN = 2 -... BLUE = 3 -\end{python} -As you can see, creating an @Enum@ is as simple as writing a class that inherits from @Enum@ itself. - -Note: Case of Enum Members - -Because Enums are used to represent constants, and to help avoid issues with name clashes between mixin-class methods/attributes and enum names, we strongly recommend using @UPPER_CASE@ names for members, and will be using that style in our examples. +A Python enumeration is a set of symbolic names bound to \emph{unique} values. +They are similar to global variables, but offer a more useful @repr()@, grouping, type-safety, and additional features. +Enumerations inherits from the @Enum@ class, \eg: +\begin{python} +class Weekday(@Enum@): Mon = 1; Tue = 2; Wed = 3; Thu = 4; Fri = 5; Sat = 6; Sun = 7 +class RGB(@Enum@): Red = 1; Green = 2; Blue = 3 +\end{python} Depending on the nature of the enum a member's value may or may not be important, but either way that value can be used to get the corresponding member: \begin{python} ->>> Weekday(3) - +print( repr( Weekday( 3 ) ) ) + \end{python} As you can see, the @repr()@ of a member shows the enum name, the member name, and the value. The @str()@ of a member shows only the enum name and member name: \begin{python} -print(Weekday.THURSDAY) -Weekday.THURSDAY +print( str( Weekday.Thu ), Weekday.Thu ) +Weekday.Thu Weekday.Thu \end{python} The type of an enumeration member is the enum it belongs to: \begin{python} ->>> type(Weekday.MONDAY) +print( type( Weekday.Thu ) ) -isinstance(Weekday.FRIDAY, Weekday) +print( isinstance(Weekday.Fri, Weekday) ) True \end{python} Enum members have an attribute that contains just their name: \begin{python} ->>> print(Weekday.TUESDAY.name) +print(Weekday.TUESDAY.name) TUESDAY \end{python} Likewise, they have an attribute for their value: \begin{python} ->>> Weekday.WEDNESDAY.value +Weekday.WEDNESDAY.value 3 \end{python} + Unlike many languages that treat enumerations solely as name/value pairs, Python @Enum@s can have behavior added. For example, @datetime.date@ has two methods for returning the weekday: @weekday()@ and @isoweekday()@. @@ -1262,22 +1266,8 @@ Rather than keep track of that ourselves we can add a method to the @Weekday@ enum to extract the day from the date instance and return the matching enum member: \begin{python} +class Weekday(Enum): Mon = 1; Tue = 2; Wed = 3; Thu = 10; Fri = 15; Sat = 16; Sun = 17 $@$classmethod def from_date(cls, date): - return cls(date.isoweekday()) -\end{python} -The complete Weekday enum now looks like this: -\begin{python} ->>> class Weekday(Enum): -... MONDAY = 1 -... TUESDAY = 2 -... WEDNESDAY = 3 -... THURSDAY = 4 -... FRIDAY = 5 -... SATURDAY = 6 -... SUNDAY = 7 -... # -... $@$classmethod -... def from_date(cls, date): -... return cls(date.isoweekday()) + return cls(date.isoweekday()) \end{python} Now we can find out what today is! Observe: @@ -1291,32 +1281,18 @@ This Weekday enum is great if our variable only needs one day, but what if we need several? Maybe we're writing a function to plot chores during a week, and don't want to use a @list@ -- we could use a different type of @Enum@: \begin{python} ->>> from enum import Flag ->>> class Weekday(Flag): -... MONDAY = 1 -... TUESDAY = 2 -... WEDNESDAY = 4 -... THURSDAY = 8 -... FRIDAY = 16 -... SATURDAY = 32 -... SUNDAY = 64 +from enum import Flag +class WeekdayF(@Flag@): Mon = @1@; Tue = @2@; Wed = @4@; Thu = @8@; Fri = @16@; Sat = @32@; Sun = @64@ \end{python} We've changed two things: we're inherited from @Flag@, and the values are all powers of 2. -Just like the original @Weekday@ enum above, we can have a single selection: -\begin{python} ->>> first_week_day = Weekday.MONDAY ->>> first_week_day - -\end{python} -But @Flag@ also allows us to combine several members into a single variable: -\begin{python} ->>> weekend = Weekday.SATURDAY | Weekday.SUNDAY ->>> weekend - +@Flag@ allows combining several members into a single variable: +\begin{python} +print( repr(WeekdayF.Sat | WeekdayF.Sun) ) + \end{python} You can even iterate over a @Flag@ variable: \begin{python} ->>> for day in weekend: -... print(day) +for day in weekend: + print(day) Weekday.SATURDAY Weekday.SUNDAY @@ -1382,15 +1358,5 @@ \subsection{Duplicating enum members and values} -Having two enum members with the same name is invalid: -\begin{python} ->>> class Shape(Enum): -... SQUARE = 2 -... SQUARE = 3 -... -Traceback (most recent call last): -... -TypeError: 'SQUARE' already defined as 2 -\end{python} -However, an enum member can have other names associated with it. +An enum member can have other names associated with it. Given two entries @A@ and @B@ with the same value (and @A@ defined first), @B@ is an alias for the member @A@. By-value lookup of the value of @A@ will return the member @A@. @@ -1398,10 +1364,5 @@ By-name lookup of @B@ will also return the member @A@: \begin{python} ->>> class Shape(Enum): -... SQUARE = 2 -... DIAMOND = 1 -... CIRCLE = 3 -... ALIAS_FOR_SQUARE = 2 -... +class Shape(Enum): SQUARE = 2; DIAMOND = 1; CIRCLE = 3; ALIAS_FOR_SQUARE = 2 >>> Shape.SQUARE @@ -1419,14 +1380,7 @@ When this behavior isn't desired, you can use the @unique()@ decorator: \begin{python} ->>> from enum import Enum, unique ->>> $@$unique -... class Mistake(Enum): -... ONE = 1 -... TWO = 2 -... THREE = 3 -... FOUR = 3 -... -Traceback (most recent call last): -... +from enum import Enum, unique +$@$unique +class DupVal(Enum): ONE = 1; TWO = 2; THREE = 3; FOUR = 3 ValueError: duplicate values found in : FOUR -> THREE \end{python} @@ -1436,14 +1390,9 @@ If the exact value is unimportant you can use @auto@: \begin{python} ->>> from enum import Enum, auto ->>> class Color(Enum): -... RED = auto() -... BLUE = auto() -... GREEN = auto() -... ->>> [member.value for member in Color] -[1, 2, 3] -\end{python} -The values are chosen by \_generate\_next\_value\_(), which can be overridden: +from enum import Enum, auto +class RGBa(Enum): RED = auto(); BLUE = auto(); GREEN = auto() +\end{python} +(Like Golang @iota@.) +The values are chosen by @_generate_next_value_()@, which can be overridden: \begin{python} >>> class AutoName(Enum): @@ -1582,5 +1531,5 @@ \begin{python} class EnumName([mix-in, ...,] [data-type,] base-enum): - pass + pass \end{python} Also, subclassing an enumeration is allowed only if the enumeration does not define any members. @@ -1699,12 +1648,12 @@ \begin{python} Enum( - value='NewEnumName', - names=<...>, - *, - module='...', - qualname='...', - type=, - start=1, - ) + value='NewEnumName', + names=<...>, + *, + module='...', + qualname='...', + type=, + start=1, + ) \end{python} \begin{itemize} @@ -1935,5 +1884,5 @@ \begin{python} class IntEnum(int, Enum): - pass + pass \end{python} This demonstrates how similar derived enumerations can be defined; @@ -2070,5 +2019,5 @@ \begin{python} def __bool__(self): - return bool(self.value) + return bool(self.value) \end{python} Plain @Enum@ classes always evaluate as @True@. @@ -2414,28 +2363,39 @@ If @__new__()@ or @__init__()@ is defined, the value of the enum member will be passed to those methods: -\begin{python} ->>> class Planet(Enum): -... MERCURY = (3.303e+23, 2.4397e6) -... VENUS = (4.869e+24, 6.0518e6) -... EARTH = (5.976e+24, 6.37814e6) -... MARS = (6.421e+23, 3.3972e6) -... JUPITER = (1.9e+27, 7.1492e7) -... SATURN = (5.688e+26, 6.0268e7) -... URANUS = (8.686e+25, 2.5559e7) -... NEPTUNE = (1.024e+26, 2.4746e7) -... def __init__(self, mass, radius): -... self.mass = mass # in kilograms -... self.radius = radius # in meters -... $\@$property -... def surface_gravity(self): -... # universal gravitational constant (m3 kg-1 s-2) -... G = 6.67300E-11 -... return G * self.mass / (self.radius * self.radius) -... ->>> Planet.EARTH.value -(5.976e+24, 6378140.0) ->>> Planet.EARTH.surface_gravity -9.802652743337129 -\end{python} +\begin{figure} +\begin{python} +from enum import Enum +class Planet(Enum): + MERCURY = ( 3.303E23, 2.4397E6 ) + VENUS = ( 4.869E24, 6.0518E6 ) + EARTH = (5.976E24, 6.37814E6) + MARS = (6.421E23, 3.3972E6) + JUPITER = (1.9E27, 7.1492E7) + SATURN = (5.688E26, 6.0268E7) + URANUS = (8.686E25, 2.5559E7) + NEPTUNE = (1.024E26, 2.4746E7) + def __init__( self, mass, radius ): + self.mass = mass # in kilograms + self.radius = radius # in meters + def surface_gravity( self ): + # universal gravitational constant (m3 kg-1 s-2) + G = 6.67300E-11 + return G * self.mass / (self.radius * self.radius) +for p in Planet: + print( f"{p.name}: {p.value}" ) + +MERCURY: (3.303e+23, 2439700.0) +VENUS: (4.869e+24, 6051800.0) +EARTH: (5.976e+24, 6378140.0) +MARS: (6.421e+23, 3397200.0) +JUPITER: (1.9e+27, 71492000.0) +SATURN: (5.688e+26, 60268000.0) +URANUS: (8.686e+25, 25559000.0) +NEPTUNE: (1.024e+26, 24746000.0) +\end{python} +\caption{Python Planet Example} +\label{f:PythonPlanetExample} +\end{figure} + \subsection{TimePeriod} @@ -2464,4 +2424,6 @@ \section{OCaml} \lstnewenvironment{ocaml}[1][]{\lstset{language=OCaml,escapechar=\$,moredelim=**[is][\color{red}]{@}{@},}\lstset{#1}}{} + +% https://ocaml.org/docs/basic-data-types#enumerated-data-types OCaml provides a variant (union) type, where multiple heterogeneously-typed objects share the same storage. @@ -2553,4 +2515,76 @@ With valediction, - Gregor Richards + + +Date: Thu, 14 Mar 2024 21:45:52 -0400 +Subject: Re: OCaml "enums" do come with ordering +To: "Peter A. Buhr" +From: Gregor Richards + +On 3/14/24 21:30, Peter A. Buhr wrote: +> I've marked 3 places with your name to shows places with enum ordering. +> +> type weekday = Mon | Tue | Wed | Thu | Fri | Sat | Sun +> let day : weekday = Mon +> let take_class( d : weekday ) = +> if d <= Fri then (* Gregor *) +> Printf.printf "weekday\n" +> else if d >= Sat then (* Gregor *) +> Printf.printf "weekend\n"; +> match d with +> Mon | Wed -> Printf.printf "CS442\n" | +> Tue | Thu -> Printf.printf "CS343\n" | +> Fri -> Printf.printf "Tutorial\n" | +> _ -> Printf.printf "Take a break\n" +> +> let _ = take_class( Mon ); take_class( Sat ); +> +> type colour = Red | Green of string | Blue of int * float +> let c = Red +> let _ = match c with Red -> Printf.printf "Red, " +> let c = Green( "abc" ) +> let _ = match c with Green g -> Printf.printf "%s, " g +> let c = Blue( 1, 1.5 ) +> let _ = match c with Blue( i, f ) -> Printf.printf "%d %g\n" i f +> +> let check_colour(c: colour): string = +> if c < Green( "xyz" ) then (* Gregor *) +> Printf.printf "green\n"; +> match c with +> Red -> "Red" | +> Green g -> g | +> Blue(i, f) -> string_of_int i ^ string_of_float f +> let _ = check_colour( Red ); check_colour( Green( "xyz" ) ); +> +> type stringList = Empty | Pair of string * stringList +> let rec len_of_string_list(l: stringList): int = +> match l with +> Empty -> 0 | +> Pair(_ , r) -> 1 + len_of_string_list r +> +> let _ = for i = 1 to 10 do +> Printf.printf "%d, " i +> done +> +> (* Local Variables: *) +> (* tab-width: 4 *) +> (* compile-command: "ocaml test.ml" *) +> (* End: *) + +My functional-language familiarity is far more with Haskell than OCaml. I +mostly view OCaml through a lens of "it's Haskell but with cheating". Haskell +"enums" (ADTs) aren't ordered unless you specifically and manually put them in +the Ord typeclass by defining the comparators. Apparently, OCaml has some +other rule, which I would guess is something like "sort by tag then by order of +parameter". Having a default behavior for comparators is *bizarre*; my guess +would be that it gained this behavior in its flirtation with object +orientation, but that's just a guess (and irrelevant). + +This gives a total order, but not enumerability (which would still be +effectively impossible or even meaningless since enums are just a special case +of ADTs). + +With valediction, + - Gregor Richards \end{comment} @@ -2558,15 +2592,47 @@ \section{Comparison} -\begin{tabular}{r|ccccccccc} -feat. / lang. & Pascal & Ada & \Csharp & OCaml & Java & Modula-3 & Rust & Swift & Python \\ +\VRef[Table]{t:FeatureLanguageComparison} shows a comparison of enumeration features and programming languages. +The features are high level and may not capture nuances within a particular language +The @const@ feature is simple macros substitution and not a typed enumeration. + +\begin{table} +\caption{Enumeration Feature / Language Comparison} +\label{t:FeatureLanguageComparison} +\small +\setlength{\tabcolsep}{3pt} +\newcommand{\CM}{\checkmark} +\begin{tabular}{r|c|c|c|c|c|c|c|c|c|c|c|c|c} + &Pascal & Ada &\Csharp& OCaml & Java &Modula-3&Golang& Rust & Swift & Python& C & \CC & \CFA \\ \hline -pure & & & & & & & & & \\ -ordered & & & & & & & & & \\ -setable & & & & & & & & & \\ -auto-init & & & & & & & & & \\ -scoped & & & & & & & & & \\ -typed & & & & & & & & & \\ -switch & & & & & & & & & \\ -loop & & & & & & & & & \\ -array & & & & & & & & & \\ +@const@ & \CM & & & & & & \CM & & & & & \CM & \\ +\hline +\hline +pure & & & & & & & & & & & & & \CM \\ +\hline +typed & & & & & & & & & & & @int@ & integral & @T@ \\ +\hline +safe & & & & & & & & & & & & \CM & \CM \\ +\hline +ordered & & & & & & & & & & & \CM & \CM & \CM \\ +\hline +dup. values & & & & & & & & & & alias & \CM & \CM & \CM \\ +\hline +setable & & & & & & & & & & & \CM & \CM & \CM \\ +\hline +auto-init & & & & & & & & & & & \CM & \CM & \CM \\ +\hline +(un)scoped & & & & & & & & & & & U & U/S & U/S \\ +\hline +overload & & \CM & & & & & & & & & & \CM & \CM \\ +\hline +switch & & & & & & & & & & & \CM & \CM & \CM \\ +\hline +loop & & & & & & & & & & & & & \CM \\ +\hline +array & & & & & & & & & & & \CM & & \CM \\ +\hline +subtype & & & & & & & & & & & & & \CM \\ +\hline +inheritance & & & & & & & & & & & & & \CM \\ \end{tabular} +\end{table}