source: doc/theses/jiada_liang_MMath/CFAenum.tex @ 35897fb

\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.
Any enumeration extensions must be intuitive to C programmers both in syntax and semantics.
The following sections detail all of my new contributions to enumerations in \CFA.


\section{Aliasing}

C already provides @const@-style aliasing using the unnamed enumerator \see{\VRef{s:TypeName}}, even if the name @enum@ is misleading (@const@ would be better).
Given the existence of this form, it is straightforward to extend it with types other than integers.
\begin{cfa}
enum E { Size = 20u, PI = 3.14159L, Jack = L"John" };
\end{cfa}
which matches with @const@ aliasing in other programming languages.
Here, the type of the enumerator is the type of the initialization constant, \eg @typeof(20u)@ for @Size@ implies @unsigned int@.
Auto-initialization is restricted to the case where all constants are @int@, matching with C.
As seen in \VRef{s:EnumeratorTyping}, this feature is just a shorthand for multiple typed-enumeration declarations.


\section{Enumerator Unscoping}
\label{s:EnumeratorUnscoping}

In C, unscoped enumerators presents a \newterm{naming problem} when multiple enumeration types appear in the same scope with duplicate enumerator names.
There is no mechanism in C to resolve these naming conflicts other than renaming one of the duplicates, which may be impossible.

The \CFA type-system allows extensive overloading, including enumerators.
Furthermore, \CFA uses the left-hand of assignment in type resolution to pinpoint the best overloaded name.
Finally, qualification and casting are provided to disambiguate any ambiguous situations.
\begin{cfa}
enum E1 { First, Second, Third, Fourth };
enum E2 { @Fourth@, @Third@, @Second@, @First@ }; $\C{// same enumerator names}$
E1 p() { return Third; }                                $\C{// correctly resolved duplicate names}$
E2 p() { return Fourth; }
void foo() {
        E1 e1 = First;   E2 e2 = First;         $\C{// initialization}$
        e1 = Second;   e2 = Second;                     $\C{// assignment}$
        e1 = p();   e2 = p();                           $\C{// function call}$
        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.
In most cases, the type system implicitly disambiguates, otherwise the programmer explicitly disambiguates using qualification or casting.


\section{Enumerator Scoping}

An enumeration can be scoped, using @'!'@, so the enumerator constants are not projected into the enclosing scope.
\begin{cfa}
enum Week @!@ { 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}
Week week = @Week.@Mon;
week = @Week.@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}
with ( @Week@, @RGB@ ) {                        $\C{// type names}$
         week = @Sun@;                                  $\C{// no qualification}$
         rgb = @Green@;
}
\end{cfa}
As in Section~\ref{s:EnumeratorUnscoping}, opening multiple scoped enumerations in a @with@ can result in duplicate enumeration names, but \CFA implicit type resolution and explicit qualification/casting handles ambiguities.


\section{Enumeration Pseudo-functions}

Pseudo-functions are function-like operators that do not result in any run-time computations, \ie like @sizeof@, @alignof@, @typeof@.
A pseudo-function call is often substituted with information extracted from the compilation symbol-table, like storage size or alignment associated with the underlying architecture.

The attributes of an enumerator are accessed by pseudo-functions @posE@, @valueE@, and @labelE@.
\begin{cfa}
int jane_pos = @posE@( Names.Jane );   $\C{// 2}$
char * jane_value = @valueE@( Names.Jane ); $\C{// "JANE"}$
char * jane_label = @labelE@( Names.Jane ); $\C{// "Jane"}$
sout | posE( Names.Jane) | labelE( Names.Jane ) | valueE( Names.Jane );
\end{cfa}
Note the ability to print all of an enumerator's properties.


\section{Enumerator Typing}
\label{s:EnumeratorTyping}

\CFA extends the enumeration declaration by parameterizing with a type (like a generic type), allowing enumerators to be assigned any values from the declared type.
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 enumerator constants.
Note, the synonyms @Liz@ and @Beth@ in the last declaration.
Because enumerators are constants, the enumeration type is implicitly @const@, so all the enumerator types in Figure~\ref{f:EumeratorTyping} are logically rewritten with @const@.

C has an implicit type conversion from an enumerator to its base type @int@.
Correspondingly, \CFA has an implicit (safe) conversion from a typed enumerator to its base type.
\begin{cfa}
char currency = Dollar;
string fred = Fred;                                             $\C{// implicit conversion from char * to \CFA string type}$
Person student = Beth;
\end{cfa}

% \begin{cfa}
% 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{cfa}

\begin{figure}
\begin{cfa}
// integral
        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 };
// 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( @const char *@ ) Name { 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 ] }; $\C{// new \CFA type}$
// 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{cfa}
\caption{Enumerator Typing}
\label{f:EumeratorTyping}
\end{figure}

An advantage of the typed enumerations is eliminating the \emph{harmonizing} problem between an enumeration and companion data \see{\VRef{s:Usage}}:
\begin{cfa}
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{cfa}
Note, the enumeration type can be a structure (see @Person@ in Figure~\ref{f:EumeratorTyping}), so it is possible to have the equivalent of multiple arrays of companion data using an array of structures.

While the enumeration type can be any C aggregate, the aggregate's \CFA constructors are not used to evaluate an enumerator's value.
\CFA enumeration constants are compile-time values (static);
calling constructors happens at runtime (dynamic).


\section{Enumeration Inheritance}

\CFA Plan-9 inheritance may be used with enumerations, where Plan-9 inheritance is containment inheritance with implicit unscoping (like a nested unnamed @struct@/@union@ in C).
\begin{cfa}
enum( char * ) Names { /* as above */ };
enum( char * ) Names2 { @inline Names@, Jack = "JACK", Jill = "JILL" };
@***@enum /* inferred */ Names3 { @inline Names2@, Sue = "SUE", Tom = "TOM" };
\end{cfa}
Enumeration @Name2@ inherits all the enumerators and their values from enumeration @Names@ by containment, and a @Names@ 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{cfa}
Names $\(\subset\)$ Names2 $\(\subset\)$ Names3 $\(\subset\)$ const char * $\C{// enum type of Names}$
\end{cfa}
For the given function prototypes, the following calls are valid.
\begin{cquote}
\begin{tabular}{ll}
\begin{cfa}
void f( Names );
void g( Names2 );
void h( Names3 );
void j( const char * );
\end{cfa}
&
\begin{cfa}
f( Fred );
g( Fred );   g( Jill );
h( Fred );   h( Jill );   h( Sue );
 j( Fred );    j( Jill );    j( Sue );    j( "WILL" );
\end{cfa}
\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.


\section{Enumerator Control Structures}

Enumerators can be used in multiple contexts.
In most programming languages, an enumerator is implicitly converted to its value (like a typed macro substitution).
However, enumerator synonyms and typed enumerations make this implicit conversion to value incorrect in some contexts.
In these contexts, a programmer's initition assumes an implicit conversion to postion.

For example, an intuitive use of enumerations is with the \CFA @switch@/@choose@ statement, where @choose@ performs an implict @break@ rather than a fall-through at the end of a @case@ clause.
\begin{cquote}
\begin{cfa}
enum Count { First, Second, Third, Fourth };
Count e;
\end{cfa}
\begin{tabular}{ll}
\begin{cfa}

choose( e ) {
        case @First@: ...;
        case @Second@: ...;
        case @Third@: ...;
        case @Fourth@: ...;
}
\end{cfa}
&
\begin{cfa}
// rewrite
choose( @value@( e ) ) {
        case @value@( First ): ...;
        case @value@( Second ): ...;
        case @value@( Third ): ...;
        case @value@( Fourth ): ...;
}
\end{cfa}
\end{tabular}
\end{cquote}
Here, the intuitive code on the left is implicitly transformed into the standard implementation on the right, using the value of the enumeration variable and enumerators.
However, this implementation is fragile, \eg if the enumeration is changed to:
\begin{cfa}
enum Count { First, Second, Third @= First@, Fourth };
\end{cfa}
which make @Third == First@ and @Fourth == Second@, causing a compilation error because of duplicase @case@ clauses.
To better match with programmer intuition, \CFA toggles between value and position semantics depneding on the language context.
For conditional clauses and switch statments, \CFA uses the robust position implementation.
\begin{cfa}
choose( @position@( e ) ) {
        case @position@( First ): ...;
        case @position@( Second ): ...;
        case @position@( Third ): ...;
        case @position@( Fourth ): ...;
}
\end{cfa}

\begin{cfa}
Count variable_a = First, variable_b = Second, variable_c = Third, variable_d = Fourth;
p(variable_a); // 0
p(variable_b); // 1
p(variable_c); // "Third"
p(variable_d); // 3
\end{cfa}


@if@ statement

@switch@ statement

looping statements


\section{Planet Example}

\VRef[Figure]{f:PlanetExample} shows an archetypal enumeration example illustrating most of the \CFA enumeration features.
@Planet@ is an enumeration of type @MR@.
Each of the planet enumerators is initialized to a specific mass/radius, @MR@, value.
The unnamed enumeration provides the gravitational-constant enumerator @G@.
Function @surfaceGravity@ uses the @with@ clause to remove @p@ qualification from fields @mass@ and @radius@.
The program main uses @SizeE@ to obtain the number of enumerators in @Planet@, and safely converts the random value into a @Planet@ enumerator.
The resulting random orbital body is used in a @choose@ statement.
The enumerators in the @case@ clause use position for testing.
The prints use @labelE@ to print the enumerators label.
Finally, a loop iterates through the planets computing the weight on each planet for a given earth weight.
The print statement does an equality comparison with an enumeration variable and enumerator.

\begin{figure}
\small
\begin{cfa}
struct MR { double mass, radius; };
enum( @MR@ ) Planet {
        //                      mass (kg)   radius (km)
        MERCURY = { 0.330_E24, 2.4397_E6 },
        VENUS      = { 4.869_E24, 6.0518_E6 },
        EARTH       = { 5.976_E24, 6.3781_E6 },
        MOON        = { 7.346_E22, 1.7380_E6 }, $\C{// not a planet}$
        MARS         = { 0.642_E24, 3.3972_E6 },
        JUPITER    = { 1898._E24, 71.492_E6 },
        SATURN     = { 568.8_E24, 60.268_E6 },
        URANUS    = { 86.86_E24, 25.559_E6 },
        NEPTUNE  = { 102.4_E24, 24.746_E6 },
};
enum( double ) { G = 6.6743_E-11 }; $\C{// universal gravitational constant (m3 kg-1 s-2)}$
static double surfaceGravity( Planet p ) @with( p )@ {
        return G * mass / ( radius \ 2u ); $\C{// exponentiation}$
}
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 );

        Planet p = @fromInt@( prng( @SizeE@(Planet) ) ); $\C{// select a random orbiting body}$
        @choose( p )@ {
          case MERCURY, VENUS, EARTH, MARS:
                sout | @labelE( p )@ | "is a rocky planet";
          @case JUPITER, SATURN, URANUS, NEPTUNE:@
                sout | labelE( p ) | "is a gas-giant planet";
          default:
                sout | labelE( p ) | "is not a planet";
        }
        for ( @p; Planet@ ) {
                sout | "Your weight on" | (@p == MOON@ ? "the" : "") | labelE(p)
                           | "is" | wd(1,1, surfaceWeight( p, mass )) | "kg";
        }
}
$\$$ planet 100
JUPITER is a gas-giant planet
Your weight on MERCURY is 37.7 kg
Your weight on VENUS is 90.5 kg
Your weight on EARTH is 100.0 kg
Your weight on the MOON is 16.6 kg
Your weight on MARS is 37.9 kg
Your weight on JUPITER is 252.8 kg
Your weight on SATURN is 106.6 kg
Your weight on URANUS is 90.5 kg
Your weight on NEPTUNE is 113.8 kg
\end{cfa}
\caption{Planet Example}
\label{f:PlanetExample}
\end{figure}

\section{Enum Trait}
A typed enum comes with traits capture enumeration charastics and helper functions. 

\begin{cfa}
forall(E) trait Bounded {
        E lowerBound();
        E upperBound();
};
\end{cfa}
\CFA enums satisfy Bounded trait thanks to the compiler implementing lowerBound() and upperBound(), with 
lowerBound() returning the first enumerator and upperBound() return the last.

\begin{cfa}
Workday day1 = lowerBound(); // Monday
Planet lastPlanet = upperBound(); // NEPTUNE
\end{cfa}

Because lowerBound() and upperBound() are overloaded with return types only, calling either functions 
in a null context cause type ambiguity if than one type implementing Bounded traits, including typed enumerations.
\begin{cfa}
Workday day1 = lowerBound(); // Okay because rhs hints lowerBound() to return a Workday
void foo(Planet p);
foo( upperBound() ); Okay because foo's parameter give type hint
// lowerBound(); // Error because both Planet and Workday implements Bounded
\end{cfa}

\begin{cfa}
forall(E | Bounded(E)) trait Serial {
        unsigned fromInstance(E e);
        E fromInt(unsigned i);
        E succ(E e);
        E pred(E e);
};
\end{cfa}
A Serial type can be mapped to a sequnce of integer. For enum types, fromInstance(E e) is equivalent to 
posE(E e). Enumerations implement fromInt(), succ(), and pred() with bound() check.
For an enum declares N enumerators, fromInt(i) returns the ith enumerator of type E if $0 \leq i < N$.
If e is the i-th enumerator, succ(e) returns the i+1-th enumerator if $e != upperBound()$ and pred(e) 
returns the i-1-th enumerator $e != lowerBound()$. \CFA compile gives an error if bound check fails.

\begin{cfa}
forall(E, T) trait TypedEnum {
        T valueE(E e);
        char * labelE(E e);
        unsigned int posE(E e);
};
\end{cfa}

The TypedEnum trait capture three basic attributes of type enums. TypedEnum asserts two types E and T, with T being the base type of enumeration E.
With an assertion on TypedEnum, we can implement functions for all type enums.

\begin{cfa}
forall( E, T | TypeEnum(E, T))
void printEnum(E e) {
        sout | "Enum "| labelE(e);
}
printEunm(MARS);
\end{cfa}

@<enum.hfa>@ overwrites comparison operators for type enums. 
\begin{cfa}
forall(E, T| TypedEnum(E, T)) {
        // comparison
        int ?==?(E l, E r);
        int ?!=?(E l, E r);
        int ?!=?(E l, zero_t);
        int ?<?(E l, E r);
        int ?<=?(E l, E r);
        int ?>?(E l, E r);
        int ?>=?(E l, E r);
}
\end{cfa}
These overloaded operators are not defined if the file is not included.
In this case, the compiler converts an enumerator to its value, and applies the operators
if they are defined for the value type T.

\begin{cfa}
// if not include <enum.hfa>
enum(int) Fruits {
        APPLE = 2, BANANA=1, CHERRY=2
};
APPLE == CHERRY; // True because they have the same Value
#include <enum.hfa>
APPLE == CHERRY; // False because they are different enumerator
\end{cfa}