source: doc/theses/jiada_liang_MMath/CFAenum.tex @ c329bca

\chapter{\texorpdfstring{\CFA}{Cforall} Enumeration}

\CFA extends C-Style enumeration by adding a number of new features that bring enumerations in line with other modern programming languages.
Any enumeration extensions must be intuitive to C programmers in syntax and semantics.
The following sections detail my new contributions to enumerations in \CFA.


\section{Syntax}

\CFA extends the C enumeration declaration \see{\VRef{s:CEnumeration}} by parameterizing with a type (like a generic type) and adding Plan-9 inheritance \see{\VRef{s:CFAInheritance}} using an @inline@ to another enumeration type.
\begin{cfa}[identifierstyle=\linespread{0.9}\it]
$\it enum$-specifier:
        enum @(type-specifier$\(_{opt}\)$)@ identifier$\(_{opt}\)$ { cfa-enumerator-list }
        enum @(type-specifier$\(_{opt}\)$)@ identifier$\(_{opt}\)$ { cfa-enumerator-list , }
        enum @(type-specifier$\(_{opt}\)$)@ identifier
cfa-enumerator-list:
        cfa-enumerator
        cfa-enumerator-list, cfa-enumerator
cfa-enumerator:
        enumeration-constant
        @inline $\color{red}enum$-type-name@
        enumeration-constant = constant-expression
\end{cfa}


\section{Operations}

\CFA enumerations have access to the three enumerations properties \see{\VRef{s:Terminology}}: label, order (position), and value via three overloaded functions @label@, @posn@, and @value@ \see{\VRef{c:trait} for details}.
\CFA auto-generates these functions for every \CFA enumeration.
\begin{cfa}
enum(int) E { A = 3 } e = A;
sout | A | @label@( A ) | @posn@( A ) | @value@( A );
sout | e | @label@( e ) | @posn@( e ) | @value@( e );
A A 0 3
A A 0 3
\end{cfa}
For output, the default is to print the label.
An alternate way to get an enumerator's position is to cast it to @int@.
\begin{cfa}
sout | A | label( A ) | @(int)A@ | value( A );
sout | A | label( A ) | @(int)A@ | value( A );
A A @0@ 3
A A @0@ 3
\end{cfa}
Finally, \CFA introduces an additional enumeration pseudo-function @countof@ (like @sizeof@, @typeof@) that returns the number of enumerators in an enumeration.
\begin{cfa}
enum(int) E { A, B, C, D } e;
countof( E );  // 4, type argument
countof( e );  // 4, variable argument
\end{cfa}
This built-in function replaces the C idiom for automatically computing the number of enumerators \see{\VRef{s:Usage}}.
\begin{cfa}
enum E { A, B, C, D, @N@ };  // N == 4
\end{cfa}

\section{Opaque Enumeration}
\label{s:OpaqueEnum}

When an enumeration type is empty. it is an \newterm{opaque} enumeration.
\begin{cfa}
enum@()@ Mode { O_RDONLY, O_WRONLY, O_CREAT, O_TRUNC, O_APPEND };
\end{cfa}
Here, the compiler chooses the internal representation, which is hidden, so the enumerators cannot be initialized.
Compared to the C enum, opaque enums are more restrictive regarding typing and cannot be implicitly converted to integers.
\begin{cfa}
Mode mode = O_RDONLY;
int www @=@ mode;                                               $\C{// disallowed}$
\end{cfa}
Opaque enumerations have only two attribute properties, @label@ and @posn@.
\begin{cfa}
char * s = label( O_TRUNC );                    $\C{// "O\_TRUNC"}$
int open = posn( O_WRONLY );                    $\C{// 1}$
s = label( mode );                                              $\C{// "O\_RDONLY"}$
int open = posn( mode );                                $\C{// 0}$
\end{cfa}
Equality and relational operations are available.
\begin{cfa}
if ( mode @==@ O_CREAT ) ...
bool b = mode @<@ O_APPEND;
\end{cfa}


\section{Typed Enumeration}
\label{s:EnumeratorTyping}

When an enumeration type is specified, all enumerators have that type and can be initialized with constants of that type or compile-time convertible to that type.
Figure~\ref{f:EumeratorTyping} shows a series of examples illustrating that all \CFA types can be used with an enumeration, and each type's values are used to set the enumerator constants.
Note the use of 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@.

\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( @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}
% synonym feature unimplemented
\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 that 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 \emph{not} used to evaluate an enumerator's value.
\CFA enumeration constants are compile-time values (static);
calling constructors happens at runtime (dynamic).


\section{Implementation}

\CFA-cc is a transpiler translating \CFA code into C, which is compiled by a C compiler.
During transpiling, \CFA-cc breaks a \CFA enumeration definition into a definition of a C enumeration with the same name and auxiliary arrays: a label and value array for a typed enumeration.
For example:
\begin{cfa}
enum( T ) E { E1 = t1, E2 = t2, E3 = t3 };
\end{cfa}
is compiled into:
\begin{cfa}
enum E { E1, E2, E3 };
const char * E_labels[3] = { "E1", "E2", "E3" };
const T E_values[3] = { t1, t2, t3 };
\end{cfa}
The generated C enumeration has enumerator values that match \CFA enumerator positions because of C's auto-initialization.
A \CFA enumeration variable definition is the same in \CFA as C, \eg:
\begin{cfa}
enum E e = E1;
e = E2;
\end{cfa}
so these expressions remain unchanged by \CFA-cc.
Therefore, a \CFA enumeration variable has the same underlying representation as its generated C enumeration.
This semantics implies a \CFA enumeration variable uses the same storage as a C enumeration variable, that @posn@ can use as its underlying representation, and the label and value arrays take little storage.
The arrays are annotated with @linkonce@, which are replaced later by gcc attribute @section(".gnu.linkonce.NAME")@, to prevent multiple definitions.
It should be possible to eliminate the two arrays if unused, either by \CFA if local to a translation unit and unused, or by the linker if global but unreferenced.
Also, the label and value arrays are declared @static@ and initialized with constants, so the arrays are allocated in the @.data@ section and initialized before program execution.
Hence, there is no additional execution cost unless new enumeration features are used, and storage usage is minimal as the number of enumerations in a program is small as is the number of enumerators in an enumeration.

Along with the enumeration definition, \CFA-cc generates definitions of the attribute functions, @posn@, @label@ and @value@, for each enumeration:
\begin{cfa}
inline int posn( E e ) { return (int) e; }
inline const * label( E e ) { return E_labels[ (int) e ]; }
inline const * E_value( E e ) { return E_values[ (int) e ]; }
\end{cfa}
where the function calls are normally inlined by the backend C compiler into a few instructions.
These functions simplify the job of getting the enumerations types through the type system in the same way as normal functions and calls.
Note, the cast to @int@ is actually an internal reinterpreted cast added before type resolution to stop further reduction on the expression by the type resolver \see{\VRef{s:ValueConversion}} and removed in code generation.
Finally, to further mitigate \CFA enumeration costs, calls to @label@ and @value@ with an enumeration constant are unrolled into the appropriate constant expression, although this could be left to the backend C compiler.
Hence, in space and time costs, \CFA enumerations follow the C philosophy of only paying for what is used, modulo some future work to convince the linker to remove un-accessed @label@ and @value@ arrays, possibly with @weak@ attributes.


\section{Value Conversion}
\label{s:ValueConversion}
C has an implicit type conversion from an enumerator to its base type @int@.
Correspondingly, \CFA has an implicit conversion from a typed enumerator to its base type, allowing typed enumeration to be seamlessly used as the value of its base type
For example, using type @Currency@ in \VRef[Figure]{f:EumeratorTyping}:
\begin{cfa}
char currency = Dollar;         $\C{// implicit conversion to base type}$
void foo( char );
foo( Dollar );                          $\C{// implicit conversion to base type}$
\end{cfa}
The implicit conversion induces a \newterm{value cost}, which is a new category (8 tuple) in \CFA's conversion cost model \see{\VRef{s:ConversionCost}} to disambiguate function overloading over a \CFA enumeration and its base type.
\begin{cfa}
void baz( char ch );            $\C{// (1)}$
void baz( Currency cu );        $\C{// (2)}$
baz( Dollar );
\end{cfa}
While both @baz@ functions are applicable to the enumerator @Dollar@, @candidate (1)@ comes with a @value@ cost for the conversion to the enumeration's base type, while @candidate (2)@ has @zero@ cost.
Hence, \CFA chooses the exact match.
Value cost is defined to be a more significant factor than an @unsafe@ but less than the other conversion costs: @(unsafe,@ {\color{red}@value@}@, poly, safe, sign, vars, specialization,@ @reference)@.
\begin{cfa}
void bar( @int@ );
Math x = PI;                            $\C{// (1)}$
double x = 5.5;                         $\C{// (2)}$
bar( x );                                       $\C{// costs (1, 0, 0, 0, 0, 0, 0, 0) or (0, 1, 0, 0, 0, 0, 0, 0)}$
\end{cfa}
Here, the candidate (1) has a @value@ conversion cost to convert to the base type, while the candidate (2) has an @unsafe@ conversion from @double@ to @int@,
which is a more expensive conversion.
Hence, @bar( x )@ resolves @x@ as type @Math@.

% \begin{cfa}
% forall(T | @CfaEnum(T)@) void bar(T);
%
% bar(a);                                       $\C{// (3), with cost (0, 0, 1, 0, 0, 0, 0, 0)}$
% \end{cfa}
% % @Value@ is designed to be less significant than @poly@ to allow function being generic over \CFA enumeration (see ~\ref{c:trait}).
% Being generic over @CfaEnum@ traits (a pre-defined interface for \CFA enums) is a practice in \CFA to implement functions over \CFA enumerations, as will see in chapter~\ref{c:trait}.
% @Value@ is a being a more significant cost than @poly@ implies if a overloaeded function defined for @CfaEnum@ (and other generic type), \CFA always try to resolve it as a @CfaEnum@, rather to insert a @value@ conversion.


\section{Initialization}
\CFA extends C's auto-initialization scheme to \CFA enumeration. For an enumeration type with base type T, the initialization scheme is the following:
\begin{enumerate}
\item the first enumerator is initialized with @T@'s @zero_t@.
\item Every other enumerator is initialized with its previous enumerator's value "+1", where "+1" is defined in terms of overloaded operator @?+?(T, one_t)@.
\end{enumerate}

\begin{cfa}
struct S { int i; };
S ?+?( S & s, one_t ) { return s.i++; }
void ?{}( S & s, zero_t ) { s.i = 0; }
enum(S) E { A, B, C, D };
\end{cfa}

The restriction on C's enumeration initializers being constant expression is relaxed on \CFA enumeration.
Therefore, an enumerator initializer allows function calls like @?+?( S & s, one_t )@ and @?{}( S & s, zero_t )@.
It is because the values of \CFA enumerators are not stored in the compiled enumeration body but in the @value@ array, which
allows dynamic initialization.

\section{Subset}

An enumeration's type can be another enumeration.
\begin{cfa}
enum( char ) Letter { A = 'A', ..., Z = 'Z' };
enum( @Letter@ ) Greek { Alph = @A@, Beta = @B@, Gamma = @G@, ..., Zeta = @Z@ }; // alphabet intersection
\end{cfa}
Enumeration @Greek@ may have more or less enumerators than @Letter@, but its enumerator values \emph{must} be from @Letter@.
Therefore, the set of @Greek@ enumerator values in a subset of the @Letter@ enumerator values.
@Letter@ is type compatible with enumeration @Letter@ because value conversions are inserted whenever @Letter@ is used in place of @Greek@.
\begin{cfa}
Letter l = A;                                           $\C{// allowed}$
Greek g = Alph;                                         $\C{// allowed}$
l = Alph;                                                       $\C{// allowed, conversion to base type}$
g = A;                                                          $\C{// {\color{red}disallowed}}$
void foo( Letter );
foo( Beta );                                            $\C{// allowed, conversion to base type}$
void bar( Greek );
bar( A );                                                       $\C{// {\color{red}disallowed}}$
\end{cfa}
Hence, @Letter@ enumerators are not type-compatible with the @Greek@ enumeration, but the reverse is true.


\section{Inheritance}
\label{s:CFAInheritance}

\CFA Plan-9 inheritance may be used with \CFA enumerations, where Plan-9 inheritance is containment inheritance with implicit un-scoping (like a nested unnamed @struct@/@union@ in C).
Containment is nominative: an enumeration inherits all enumerators from another enumeration by declaring an @inline statement@ in its enumerator lists.
\begin{cfa}
enum( char * ) Names { /* $\see{\VRef[Figure]{f:EumeratorTyping}}$ */  };
enum( char * ) Names2 { @inline Names@, Jack = "JACK", Jill = "JILL" };
enum( char * ) Names3 { @inline Names2@, Sue = "SUE", Tom = "TOM" };
\end{cfa}
In the preceding example, @Names2@ is defined with five enumerators, three of which are from @Name@ through containment, and two are self-declared.
@Names3@ inherits all five members from @Names2@ and declares two additional enumerators.
Hence, enumeration inheritance forms a subset relationship.
Specifically, the inheritance relationship for the example above is:
\begin{cfa}
Names $\(\subset\)$ Names2 $\(\subset\)$ Names3 $\C{// enum type of Names}$
\end{cfa}

Inheritance can be nested, and a \CFA enumeration can inline enumerators from more than one \CFA enumeration, forming a tree-like hierarchy.
However, the uniqueness of the enumeration name applies to enumerators, including those from supertypes, meaning an enumeration cannot name an enumerator with the same label as its subtype's members or inherits
from multiple enumeration that has overlapping enumerator labels. Consequently, a new type cannot inherit from an enumeration and its supertype or two enumerations with a
common supertype (the diamond problem) since such would unavoidably introduce duplicate enumerator labels.

The base type must be consistent between subtype and supertype.
When an enumeration inherits enumerators from another enumeration, it copies the enumerators' @value@ and @label@, even if the @value@ is auto-initialized.
However, the underlying representation's position is the enumerator's order in the new enumeration.
\begin{cfa}
enum() E1 { B };                                                                        $\C{// B}$
enum() E2 { C, D };                                             $\C{// C D}$
enum() E3 { inline E1, inline E2, E };  $\C{// {\color{red}[\(_{E1}\)} B {\color{red}]} {\color{red}[\(_{E2}\)} C D {\color{red}]} E}$
enum() E4 { A, inline E3, F};                   $\C{// A {\color{blue}[\(_{E3}\)} {\color{red}[\(_{E1}\)} B {\color{red}]} {\color{red}[\(_{E2}\)} C D {\color{red}]} E {\color{blue}]} F}$
\end{cfa}
In this example, @B@ is at position 0 in @E1@ and @E3@, but position 1 in @E4@ as @A@ takes position 0 in @E4@.
@C@ is at position 0 in @E2@, 1 in @E3@, and 2 in @E4@.
@D@ is at position 1 in @E2@, 2 in @E3@, and 3 in @E4@.

A subtype enumeration can be casted, or implicitly converted into its supertype, with a @safe@ cost, called \newterm{enumeration conversion}.
\begin{cfa}
enum E2 e2 = C;
posn( e2 );                     $\C[1.75in]{// 0}$
enum E3 e3 = e2;        $\C{// Assignment with enumeration conversion E2 to E3}$
posn( e2 );                     $\C{// 1 cost}$
void foo( E3 e );
foo( e2 );                      $\C{// Type compatible with enumeration conversion E2 to E3}$
posn( (E3)e2 );         $\C{// Explicit cast with enumeration conversion E2 to E3}$
E3 e31 = B;                     $\C{// No conversion: E3.B}$
posn( e31 );            $\C{// 0 cost}\CRT$
\end{cfa}
The last expression is unambiguous.
While both @E2.B@ and @E3.B@ are valid candidates, @E2.B@ has an associated safe cost and @E3.B@ needs no conversion (@zero@ cost).
\CFA selects the lowest cost candidate @E3.B@.

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.


\subsection{Offset Calculation}

As discussed in \VRef{s:OpaqueEnum}, \CFA chooses position as a representation of a \CFA enumeration variable.
When a cast or implicit conversion moves an enumeration from subtype to supertype, the position can be unchanged or increased.
\CFA determines the position offset with an \newterm{offset calculation} function.

\begin{figure}
\begin{cfa}
struct Enumerator;
struct CFAEnum { vector<variant<CFAEnum, Enumerator>> members; string name; };
inline static bool operator==(CFAEnum& lhs, CFAEnum& rhs) { return lhs.name == rhs.name; }
pair<bool, int> calculateEnumOffset(CFAEnum src, CFAEnum dst) {
        int offset = 0;
        if ( src == dst ) return make_pair(true, 0);
        for ( auto v : dst.members ) {
                if ( holds_alternative<Enumerator>(v) ) {
                        offset++;
                } else {
                        auto m = get<CFAEnum>(v);
                        if ( m == src ) @return@ make_pair( true, offset );
                        auto dist = calculateEnumOffset( src, m );
                        if ( dist.first ) {
                                @return@ make_pair( true, offset + dist.second );
                        } else {
                                offset += dist.second;
                        }
                }
        }
        @return@ make_pair( false, offset );
}
\end{cfa}
\caption{Compute Offset from Subtype Enumeration to a Supertype}
\label{s:OffsetSubtypeSuperType}
\end{figure}

Figure~\ref{s:OffsetSubtypeSuperType} shows an outline of the offset calculation in \CC.
Structure @CFAEnum@ represents the \CFA enumeration with a vector of variants of @CFAEnum@ or @Enumerator@.
The algorithm takes two @CFAEnums@ parameters, @src@ and @dst@, with @src@ being the type of expression the conversion applies to, and @dst@ being the type the expression is cast to.
The algorithm iterates over the members in @dst@ to find @src@.
If a member is an enumerator of @dst@, the positions of all subsequent members are incremented by one.
If the current member is @dst@, the function returns true, indicating \emph{found} and the accumulated offset.
Otherwise, the algorithm recurses into the current @CFAEnum@ @m@ to check if its @src@ is convertible to @m@.
If @src@ is convertible to the current member @m@, this means @src@ is a subtype-of-subtype of @dst@.
The offset between @src@ and @dst@ is the sum of the offset of @m@ in @dst@ and the offset of @src@ in @m@.
If @src@ is not a subtype of @m@, the loop continues but with the offset shifted by the size of @m@.
If the loop ends, than @src@ is not convertible to @dst@, and false is returned.


\section{Control Structures}

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

For example, an intuitive use of enumerations is with the \CFA @switch@/@choose@ statement, where @choose@ performs an implicit @break@ rather than a fall-through at the end of a @case@ clause.
(For this discussion, ignore the fact that @case@ requires a compile-time constant.)
\begin{cfa}[belowskip=0pt]
enum Count { First, Second, Third, Fourth };
Count e;
\end{cfa}
\begin{cquote}
\setlength{\tabcolsep}{15pt}
\noindent
\begin{tabular}{@{}ll@{}}
\begin{cfa}[aboveskip=0pt]

choose( e ) {
        case @First@: ...;
        case @Second@: ...;
        case @Third@: ...;
        case @Fourth@: ...;
}
\end{cfa}
&
\begin{cfa}[aboveskip=0pt]
// 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}
making @Third == First@ and @Fourth == Second@, causing a compilation error because of duplicate @case@ clauses.
To better match with programmer intuition, \CFA toggles between value and position semantics depending on the language context.
For conditional clauses and switch statements, \CFA uses the robust position implementation.
\begin{cfa}
if ( @posn@( e ) < posn( Third ) ) ...
choose( @posn@( e ) ) {
        case @posn@( First ): ...;
        case @posn@( Second ): ...;
        case @posn@( Third ): ...;
        case @posn@( Fourth ): ...;
}
\end{cfa}

\CFA provides a special form of for-control for enumerating through an enumeration, where the range is a type.
\begin{cfa}
for ( cx; @Count@ ) { sout | cx | nonl; } sout | nl;
for ( cx; ~= Count ) { sout | cx | nonl; } sout | nl;
for ( cx; -~= Count ) { sout | cx | nonl; } sout | nl;
First Second Third Fourth
First Second Third Fourth
Fourth Third Second First
\end{cfa}
The enumeration type is syntax sugar for looping over all enumerators and assigning each enumerator to the loop index, whose type is inferred from the range type.
The prefix @+~=@ or @-~=@ iterate forward or backward through the inclusive enumeration range, where no prefix defaults to @+~=@.

C has an idiom for @if@ and loop predicates of comparing the predicate result ``not equal to 0''.
\begin{cfa}
if ( x + y /* != 0 */  ) ...
while ( p /* != 0 */  ) ...
\end{cfa}
This idiom extends to enumerations because there is a boolean conversion regarding the enumeration value if and only if such a conversion is available.
For example, such a conversion exists for all numerical types (integral and floating-point).
It is possible to explicitly extend this idiom to any typed enumeration by overloading the @!=@ operator.
\begin{cfa}
bool ?!=?( Name n, zero_t ) { return n != Fred; }
Name n = Mary;
if ( n ) ... // result is true
\end{cfa}
Specialize meanings are also possible.
\begin{cfa}
enum(int) ErrorCode { Normal = 0, Slow = 1, Overheat = 1000, OutOfResource = 1001 };
bool ?!=?( ErrorCode ec, zero_t ) { return ec >= Overheat; }
ErrorCode code = ...;
if ( code ) { problem(); }
\end{cfa}


\section{Dimension}

\VRef{s:EnumeratorTyping} introduces the harmonizing problem between an enumeration and secondary information.
When possible, using a typed enumeration for the secondary information is the best approach.
However, there are times when combining these two types is not possible.
For example, the secondary information might precede the enumeration and/or its type is needed directly to declare parameters of functions.
In these cases, having secondary arrays of the enumeration size are necessary.

To support some level of harmonizing in these cases, an array dimension can be defined using an enumerator type, and the enumerators used as subscripts.
\begin{cfa}
enum E1 { A, B, C, N }; // possibly predefined
enum(int) E2 { A, B, C };
float H1[N] = { [A] :$\footnotemark$ 3.4, [B] : 7.1, [C] : 0.01 }; // C
float H2[@E2@] = { [A] : 3.4, [B] : 7.1, [C] : 0.01 }; // CFA
\end{cfa}
\footnotetext{C uses symbol \lstinline{'='} for designator initialization, but \CFA changes it to \lstinline{':'} because of problems with tuple syntax.}
This approach is also necessary for a predefined typed enumeration (unchangeable) when additional secondary information needs to be added.
The array subscript operator, namely @?[?]@, is overloaded so that when a \CFA enumerator is used as an array index, it implicitly converts to its position over value to sustain data harmonization.
This behaviour can be reverted by explicit overloading:
\begin{cfa}
float ?[?]( float * arr, E2 index ) { return arr[ value( index ) ]; }
\end{cfa}
While enumerator labels @A@, @B@ and @C@ are being defined twice in different enumerations, they are unambiguous within the context.
Designators in @H1@ are unambiguous becasue @E2@ has a @value@ cost to @int@, which is more expensive than @safe@ cost from C-Enum @E1@ to @int@.
Designators in @H2@ are resolved as @E2@ because when a \CFA enumeration type is being used as an array dimension, \CFA adds the enumeration type to the initializer's resolution context.


\section{I/O}

As seen in multiple examples, \CFA enumerations can be printed and the default property printed is the enumerator's label, which is similar in other programming languages.
However, very few programming languages provide a mechanism to read in enumerator values.
Even the @boolean@ type in many languages does not have a mechanism for input using the enumerators @true@ or @false@.
\VRef[Figure]{f:EnumerationI/O} show \CFA enumeration input based on the enumerator labels.
When the enumerator labels are packed together in the input stream, the input algorithm scans for the longest matching string.
For basic types in \CFA, the rule is that the same constants used to initialize a variable in a program are available to initialize a variable using input, where string constants can be quoted or unquoted.

\begin{figure}
\begin{cquote}
\setlength{\tabcolsep}{15pt}
\begin{tabular}{@{}ll@{}}
\begin{cfa}
int main() {
        enum(int ) E { BBB = 3, AAA, AA, AB, B };
        E e;

        try {
                for () {
                        try {
                                @sin | e@;
                        } catch( missing_data * ) {
                                sout | "missing data";
                                continue; // try again
                        }
                        sout | e | "= " | value( e );
                }
        } catch( end_of_file ) {}
}
\end{cfa}
&
\begin{cfa}
$\rm input$
BBBABAAAAB
BBB AAA AA AB B

$\rm output$
BBB = 3
AB = 6
AAA = 4
AB = 6
BBB = 3
AAA = 4
AA = 5
AB = 6
B = 7

\end{cfa}
\end{tabular}
\end{cquote}
\caption{Enumeration I/O}
\label{f:EnumerationI/O}
\end{figure}


\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 planet enumerator 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 the pseudo function @countof@ to obtain the number of enumerators in @Planet@, and safely converts the random value into a @Planet@ enumerator using @fromInt@.
The resulting random orbital-body is used in a @choose@ statement.
The enumerators in the @case@ clause use the enumerator position for testing.
The prints use @label@ to print an enumerator's name.
Finally, a loop enumerates through the planets computing the weight on each planet for a given Earth mass.
The print statement does an equality comparison with an enumeration variable and enumerator (@p == MOON@).

\begin{figure}
\small
\begin{cfa}
struct MR { double mass, radius; };                     $\C[3.5in]{// planet definition}$
enum( @MR@ ) Planet {                                           $\C{// typed enumeration}$
        //                      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 },
        PLUTO       = { 1.303_E22, 1.1880_E6 }, $\C{// not a planet}$
};
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 @\@ 2 );             $\C{// no qualification, 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";  // terminate program
        double earthWeight = convert( argv[1] );
        double earthMass = earthWeight / surfaceGravity( EARTH );
        Planet rp = @fromInt@( prng( @countof@( Planet ) ) ); $\C{// select random orbiting body}$
        @choose( rp )@ {                                                $\C{// implicit breaks}$
          case MERCURY, VENUS, EARTH, MARS:
                sout | @rp@ | "is a rocky planet";
          case JUPITER, SATURN, URANUS, NEPTUNE:
                sout | rp | "is a gas-giant planet";
          default:
                sout | rp | "is not a planet";
        }
        for ( @p; Planet@ ) {                                   $\C{// enumerate}\CRT$
                sout | "Your weight on" | ( @p == MOON@ ? "the" : " " ) | p
                           | "is" | wd( 1,1,  surfaceWeight( p, earthMass ) ) | "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
Your weight on PLUTO is 6.3 kg
\end{cfa}
\caption{Planet Example}
\label{f:PlanetExample}
\end{figure}