Index: doc/user/user.tex =================================================================== --- doc/user/user.tex (revision 9e234f0bb739c4029df14ef999b63076154dd45a) +++ doc/user/user.tex (revision d0e80f6167054028f4628261a2c844ccd7e5668e) @@ -11,6 +11,6 @@ %% Created On : Wed Apr 6 14:53:29 2016 %% Last Modified By : Peter A. Buhr -%% Last Modified On : Sun Mar 7 21:50:24 2021 -%% Update Count : 4574 +%% Last Modified On : Sat Mar 27 09:55:55 2021 +%% Update Count : 4796 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2164,7 +2164,186 @@ +\section{Enumeration} + +An \newterm{enumeration} is a compile-time mechanism to give names to constants. +There is no runtime manifestation of an enumeration. +Their purpose is code-readability and maintenance -- changing an enum's value automatically updates all name usages during compilation. + +An enumeration defines a type containing a set of names, each called an \newterm{enumeration constant} (shortened to \newterm{enum}) with a fixed (©const©) value. +\begin{cfa} +enum Days { Mon, Tue, Wed, Thu, Fri, Sat, Sun }; // enumeration type definition, set of 7 names +Days days = Mon; // enumeration type declaration and initialization +\end{cfa} +The set of enums are injected into the scope of the definition and use the variable namespace. +Hence, enums may be overloaded with enum/variable/function names. +\begin{cfa} +enum Foo { Bar }; +enum Goo { Bar }; $\C[1.75in]{// overload Foo.Bar}$ +int Foo; $\C{// type/variable separate namespace}$ +double Bar; $\C{// overload Foo.Bar, Goo.Bar}\CRT$ +\end{cfa} +An anonymous enumeration is used to inject enums with specific values into a scope: +\begin{cfa} +enum { Prime = 103, BufferSize = 1024 }; +\end{cfa} +An enumeration is better than using the C \Index{preprocessor} +\begin{cfa} +#define Mon 0 +... +#define Sun 6 +\end{cfa} +or C constant declarations +\begin{cfa} +const int Mon = 0, ..., Sun = 6; +\end{cfa} +because the enumeration is succinct, has automatic numbering, can appear in ©case© labels, does not use storage, and is part of the language type-system. +Finally, the type of an enum is implicitly or explicitly specified and the constant value can be implicitly or explicitly specified. +Note, enum values may be repeated in an enumeration. + + +\subsection{Enum type} + +While an enumeration defines a new set-type of names, its underlying enums can be any ©const© type, and an enum's value comes from this type. +\CFA provides an automatic conversion from an enum to its base type, \eg comparing/printing an enum compares/prints its value rather than the enum name. +The default enum type is ©int©. +Hence, ©Days© is the set type ©Mon©, ©Tue©, ...\,, ©Sun©, while the type of each enum is ©int© and each enum represents a fixed integral value. +If no values are specified for an integral enum type, the enums are automatically numbered by one from left to right starting at zero. +Hence, the value of enum ©Mon© is 0, ©Tue© is 1, ...\,, ©Sun© is 6. +If a value is specified, numbering continues by one from that value. +It an enum value is an expression, the compiler performs constant-folding to obtain a constant value. + +Other integral types with associated values can be explicitly specified. +\begin{cfa} +enum( @char@ ) Letter { A @= 'A'@, B, C, I @= 'I'@, J, K }; +enum( @long long int@ ) BigNum { X = 123_456_789_012_345, Y = 345_012_789_456_123 }; +\end{cfa} +For enumeration ©Letter©, enum ©A©'s value is explicitly set to ©'A'©, with ©B© and ©C© implicitly numbered with increasing values from ©'A'©, and similarly for enums ©I©, ©J©, and ©K©. +Note, an enum is an immutable constant, \ie ©A = B© is disallowed; +by transitivity, an enum's type is implicitly ©const©. +Hence, a constant/enum cannot appear in a mutuable context nor is a constant/enum addressable (rvalue). + +Non-integral enum types have the restriction that all enums \emph{must} be explicitly specified, \ie incrementing by one for the next enum is not done even if supported by the enum type, \eg ©double©. +\begin{cfa} +// non-integral numeric +enum( double ) Math { PI_2 = 1.570796, PI = 3.141597, E = 2.718282 } +// 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 ] }; +// function +void f() {...} void g() {...} +enum( void (*)() ) funs { F = f, F = g }; +// aggregate +struct S { int i, j; }; +enum( S ) s { A = { 3, 4 }, B = { 7, 8 } }; +// enumeration +enum( Letter ) Greek { Alph = A, Beta = B, /* more enums */ }; // alphabet intersection +\end{cfa} +Enumeration ©Greek© may have more or less enums than ©Letter©, but the enum values \emph{must} be from ©Letter©. +Therefore, ©Greek© enums are a subset of type ©Letter© and are type compatible with enumeration ©Letter©, but ©Letter© enums are not type compatible with enumeration ©Greek©. + +The following examples illustrate the difference between the enumeration type and the type of its enums. +\begin{cfa} +Math m = PI; $\C[1.5in]{// allowed}$ +double d = PI; $\C{// allowed, conversion to base type}$ +m = E; $\C{// allowed}$ +m = Alph; $\C{// {\color{red}disallowed}}$ +m = 3.141597; $\C{// {\color{red}disallowed}}$ +d = E; $\C{// allowed, conversion to base type}$ +d = m; $\C{// {\color{red}disallowed}}$ +d = Alph; $\C{// {\color{red}disallowed}}$ +Letter l = A; $\C{// allowed}$ +Greek g = Alph; $\C{// allowed}$ +l = Alph; $\C{// allowed, conversion to base type}$ +g = A; $\C{// {\color{red}disallowed}}\CRT$ +\end{cfa} + +A constructor \emph{cannot} be used to initialize enums because a constructor executes at runtime. +A fallback is to substitute C-style initialization overriding the constructor with ©@=©. +\begin{cfa} +enum( struct vec3 ) Axis { Up $@$= { 1, 0, 0 }, Left $@$= ..., Front $@$= ... } +\end{cfa} +Finally, enumeration variables are assignable and comparable only if the appropriate operators are defined for its enum type. + + +\subsection{Inheritance} + +\Index{Plan-9}\index{inheritance!enumeration} inheritance may be used with enumerations. +\begin{cfa} +enum( const char * ) Name2 { @inline Name@, Jack = "Jack", Jill = "Jill" }; +enum @/* inferred */@ Name3 { @inline Name@, @inline Name2@, Sue = "Sue", Tom = "Tom" }; +\end{cfa} +Enumeration ©Name2© inherits all the enums and their values from enumeration ©Name© by containment, and a ©Name© enumeration is a subtype of enumeration ©Name2©. +Note, enums must be unique in inheritance but enum values may be repeated. +The enum type for the inheriting type must be the same as the inherited type; +hence the enum 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 ©Name©s is: +\begin{cfa} +Name $\(\subseteq\)$ Name2 $\(\subseteq\)$ Name3 $\(\subseteq\)$ const char * // enum type of Name +\end{cfa} +Hence, given +\begin{cfa} +void f( Name ); +void g( Name2 ); +void h( Name3 ); +void j( const char * ); +\end{cfa} +the following calls are valid +\begin{cfa} +f( Fred ); +g( Fred ); g( Jill ); +h( Fred ); h( Jill ); h( Sue ); +j( Fred ); j( Jill ); j( Sue ); j( 'W' ); +\end{cfa} +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. + +Enums cannot be created at runtime, so inheritence problems, such as contra-variance do not apply. +Only instances of the enum base-type may be created at runtime. + +\begin{comment} +The invariance of references, as I show at the bottom, is easy to overlook. Not shown, but on the same topic, is that returns work in the opposite direction as parameters. Hopefully our existing type rules already know both those facts, so that we'd only have to provide the rules that I suggest using the by-value parameters. + +The Fred, Jack, and Mary declarations are picked verbatim from our earlier whiteboard, just repeated here for reference. + +\begin{cfa} +// Fred is a subset of char * +enum char * Fred { A = "A", B = "B", C = "C" }; +// Jack is a subset of Fred +enum enum Fred Jack { W = A, Y = C}; +// Mary is a superset of Fred +enum Mary { inline Fred, D = "hello" }; + +// Demonstrating invariance of references + +[void] frcs( & * char x ) { char * x0 = x; x = "bye"; } +[void] frf ( & Fred x ) { Fred x0 = x; x = B; } +[void] frj ( & Jack x ) { Jack x0 = x; x = W; } +[void] frm ( & Mary x ) { Mary x0 = x; x = D; } + +char * vcs; +Fred vf; +Jack vj; +Mary vm; + +// all variant calls: bad (here are noteworthy examples) + frcs( vf ); // can't assign "bye" to vf + frm ( vf ); // can't assign D to vf + frf ( vj ); // can't assign B to vj +vf = B ; frj ( vf ); // can't assign B to frj.x0 +vcs = "bye"; frf ( vcs ); // can't assign "bye" to frf.x0 +\end{cfa} + +This example is really great. However, I think it's work explicitly doing one with ©const &©. +\end{comment} + + \section{Routine Definition} -\CFA also supports a new syntax for routine definition, as well as \Celeven and K\&R routine syntax. +\CFA supports a new syntax for routine definition, as well as \Celeven and K\&R routine syntax. The point of the new syntax is to allow returning multiple values from a routine~\cite{Galletly96,CLU}, \eg: \begin{cfa} @@ -2174,5 +2353,5 @@ \end{cfa} where routine ©f© has three output (return values) and three input parameters. -Existing C syntax cannot be extended with multiple return types because it is impossible to embed a single routine name within multiple return type specifications. +Existing C syntax cannot be extended with multiple return types because it is impossible to embed a single routine name within multiple return type-specifications. In detail, the brackets, ©[]©, enclose the result type, where each return value is named and that name is a local variable of the particular return type.\footnote{ @@ -2200,5 +2379,5 @@ int (*f(x))[ 5 ] int x; {} \end{cfa} -The string ``©int (*f(x))[ 5 ]©'' declares a K\&R style routine of type returning a pointer to an array of 5 integers, while the string ``©[ 5 ] int x©'' declares a \CFA style parameter x of type array of 5 integers. +The string ``©int (*f(x))[ 5 ]©'' declares a K\&R style routine of type returning a pointer to an array of 5 integers, while the string ``©[ 5 ] int x©'' declares a \CFA style parameter ©x© of type array of 5 integers. Since the strings overlap starting with the open bracket, ©[©, there is an ambiguous interpretation for the string. As well, \CFA-style declarations cannot be used to declare parameters for C-style routine-definitions because of the following ambiguity: @@ -4120,5 +4299,5 @@ \CFA provides a fine-grained solution where a \Index{recursive lock} is acquired and released indirectly via a manipulator ©acquire© or instantiating an \Index{RAII} type specific for the kind of stream: ©osacquire©\index{ostream@©ostream©!osacquire@©osacquire©} for output streams and ©isacquire©\index{isacquire@©isacquire©}\index{istream@©istream©!isacquire@©isacquire©} for input streams. -The common usage is manipulator ©acquire©\index{ostream@©ostream©!acquire@©acquire©} to lock a stream during a single cascaded I/O expression, where it should appear as the first item in a cascade list, \eg: +The common usage is manipulator ©acquire©\index{ostream@©ostream©!acquire@©acquire©} to lock a stream during a single cascaded I/O expression, with the manipulator appearing as the first item in a cascade list, \eg: \begin{cfa} $\emph{thread\(_1\)}$ : sout | @acquire@ | "abc " | "def "; // manipulator @@ -4142,5 +4321,5 @@ In summary, the stream lock is acquired by the ©acquire© manipulator and implicitly released at the end of the cascaded I/O expression ensuring all operations in the expression occur atomically. -To lock a stream across multiple I/O operations, declare an instance of the appropriate ©osacquire© or ©isacquire© type to implicitly acquire and release the stream lock for the object's duration, \eg: +To lock a stream across multiple I/O operations, an object of type ©osacquire© or ©isacquire© is declared to implicitly acquire/release the stream lock providing mutual exclusion for the object's duration, \eg: \begin{cfa} { // acquire sout for block duration