source: doc/theses/jiada_liang_MMath/background.tex

\chapter{Background}

\CFA is a backwards-compatible extension of the C programming language, therefore, it must support C-style enumerations.
The following covers C enumerations.

As discussed in \VRef{s:Aliasing}, 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 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, works in all C constant-expression locations, and might not occupy storage..
\end{enumerate}


\section{C \lstinline{const}}
\label{s:Cconst}

C can simulate the aliasing @const@ declarations \see{\VRef{s:Aliasing}}, with static and dynamic initialization.
\begin{clang}
static const int one = 0 + 1;                   $\C{// static initialization}$
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() % 100;           $\C{// dynamic intialization}$
        int va[r];                                                      $\C{// VLA, auto 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 on the stack.
Again, this form of aliasing is not an enumeration.


\section{C Enumeration}
\label{s:CEnumeration}

The C enumeration has the following syntax~\cite[\S~6.7.2.2]{C11}.
\begin{clang}[identifierstyle=\linespread{0.9}\it]
$\it enum$-specifier:
        enum identifier$\(_{opt}\)$ { enumerator-list }
        enum identifier$\(_{opt}\)$ { enumerator-list , }
        enum identifier
enumerator-list:
        enumerator
        enumerator-list , enumerator
enumerator:
        enumeration-constant
        enumeration-constant = constant-expression
\end{clang}
The terms \emph{enumeration} and \emph{enumerator} used in this work \see{\VRef{s:Terminology}} come from the grammar.
The C enumeration semantics are discussed using examples.


\subsection{Type Name}
\label{s:TypeName}

An \emph{unnamed} enumeration is used to provide aliasing \see{\VRef{s:Aliasing}} exactly like a @const@ declaration in other languages.
However, it is restricted to integral values.
\begin{clang}
enum { Size = 20, Max = 10, MaxPlus10 = Max + 10, @Max10Plus1@, Fred = -7 };
\end{clang}
Here, the aliased constants are: 20, 10, 20, 21, and -7.
Direct initialization is by a compile-time expression generating a constant value.
Indirect initialization (without initialization, @Max10Plus1@) is \newterm{auto-initialized}: from left to right, starting at zero or the next explicitly initialized constant, incrementing by @1@.
Because multiple independent enumerators can be combined, enumerators with the same values can occur.
The enumerators are rvalues, so assignment is disallowed.
Finally, enumerators are \newterm{unscoped}, \ie enumerators declared inside of an @enum@ are visible (projected) into the enclosing scope of the @enum@ type.
For unnamed enumeration this semantic is required because there is no type name for scoped qualification.

As noted, this kind of aliasing declaration is not an enumeration, even though it is declared using an @enum@ in C.
While the semantics is misleading, this enumeration form matches with aggregate types:
\begin{cfa}
typedef struct /* unnamed */  { ... } S;
struct /* unnamed */  { ... } x, y, z;  $\C{// questionable}$
struct S {
        union /* unnamed */ {                           $\C{// unscoped fields}$
                int i;  double d ;  char ch;
        };
};
\end{cfa}
Hence, C programmers would expect this enumeration form to exist in harmony with the aggregate form.

A \emph{named} enumeration is an enumeration:
\begin{clang}
enum @Week@ { Mon, Tue, Wed, Thu@ = 10@, Fri, Sat, Sun };
\end{clang}
and adopts the same semantics with respect to direct and auto intialization.
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@.
As well, initialization may occur in any order.
\begin{clang}
enum Week {
        Thu@ = 10@, Fri, Sat, Sun,
        Mon@ = 0@, Tue, Wed@,@                  $\C{// terminating comma}$
};
\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.\footnote{
A terminating comma appears in other C syntax, \eg the initializer list.}
This feature allow enumerator lines to be interchanged without moving a comma.
Named enumerators are also unscoped.


\subsection{Implementation}

In theory, a C enumeration \emph{variable} is an implementation-defined integral type large enough to hold all enumerator values.
In practice, C uses @int@ as the underlying type for enumeration variables, because of the restriction to integral constants, which have type @int@ (unless qualified with a size suffix).


\subsection{Usage}
\label{s:Usage}

C proves an implicit \emph{bidirectional} conversion between an enumeration and its integral type.
\begin{clang}
enum Week week = Mon;                           $\C{// week == 0}$
week = Fri;                                                     $\C{// week == 11}$
int i = Sun;                                            $\C{// implicit conversion to int, i == 13}$
@week = 10000;@                                         $\C{// UNDEFINED! implicit conversion to Week}$
\end{clang}
While converting an enumerator to underlying type is useful, the implicit conversion from the base type to an enumeration type is a common source of error.

Enumerators can appear in @switch@ and looping statements.
\begin{cfa}
enum Week { Mon, Tue, Wed, Thu, Fri, Sat, Sun };
switch ( week ) {
        case Mon: case Tue: case Wed: case Thu: case Fri:
                printf( "weekday\n" );
        case Sat: case Sun:
                printf( "weekend\n" );
}
for ( enum Week day = Mon; day <= Sun; day += 1 ) {
        printf( "day %d\n", day ); // 0-6
}
\end{cfa}
For iterating, the enumerator values \emph{must} have a consecutive ordering with a fixed step between values.
Note, it is the bidirectional conversion that allows incrementing @day@: @day@ is converted to @int@, integer @1@ is added, and the result is converted back to @Week@ for the assignment to @day@.
For safety, \CC does not support the bidirectional conversion, and hence, an unsafe cast is necessary to increment @day@: @day = (Week)(day + 1)@.

There is a C idiom to automatically know the number of enumerators in an enumeration.
\begin{cfa}
enum E { A, B, C, D, @N@ };  // N == 4
for ( enum E e = A; e < @N@; e += 1 ) ...
\end{cfa}
Here, the auto-incrementing counts the number of enumerators and puts the total into the last enumerator @N@.
@N@ is often used as the dimension for an array assocated with the enumeration.
\begin{cfa}
E array[@N@];
for ( enum E e = A; e < N; e += 1 ) {
        array[e] = e;
}
\end{cfa}
However, for typed enumerations, \see{\VRef{f:EumeratorTyping}}, this idiom fails.

This idiom leads to another C idiom using an enumeration with matching companion information.
For example, an enumeration is linked with a companion array of printable strings.
\begin{cfa}
enum Integral_Type { chr, schar, uschar, sshort, ushort, sint, usint, ..., NO_OF_ITYPES };
char * Integral_Name[@NO_OF_ITYPES@] = {
        "char", "signed char", "unsigned char",
        "signed short int", "unsigned short int",
        "signed int", "unsigned int", ...
};
enum Integral_Type integral_type = ...
printf( "%s\n", Integral_Name[@integral_type@] ); // human readable type name
\end{cfa}
However, the companion idiom results in the \emph{harmonizing} problem because an update to the enumeration @Integral_Type@ often requires a corresponding update to the companion array \snake{Integral_Name}.
The need to harmonize is at best indicated by a comment before the enumeration.
This issue is exacerbated if enumeration and companion array are in different translation units.

\bigskip
While C provides a true enumeration, it is restricted, has unsafe semantics, and does provide enumeration features in other programming languages.