Index: doc/user/user.tex
===================================================================
--- doc/user/user.tex	(revision 07bc165d7e469d80da5970e552dd0bd4b84156a7)
+++ doc/user/user.tex	(revision 40e636a3e71c878c7a10447ffe19e38fab7a8677)
@@ -11,6 +11,6 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Sun Jul 10 12:52:09 2016
-%% Update Count     : 1200
+%% Last Modified On : Wed Jul 13 08:14:39 2016
+%% Update Count     : 1247
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -294,5 +294,5 @@
 \item
 \Indexc{-nodebug}\index{compilation option!-nodebug@©-nodebug©}
-The program is linked with the non-debugging version of the unikernel or multikernel, so the execution of the program is faster.
+The program is linked with the non-debugging version of the runtime system, so the execution of the program is faster.
 \Emph{However, no runtime checks or ©assert©s are performed so errors usually result in abnormal program termination.}
 
@@ -721,6 +721,9 @@
 ®&®crc = &cx;					§\C{// error, cannot change crc}§
 \end{lstlisting}
-Hence, for type ©& const©, there is no pointer assignment, so ©&rc = &x© is disallowed, and \emph{the address value cannot be ©0© unless an arbitrary pointer is assigned to the reference}.
-In effect, the compiler is managing the addresses for type ©& const© not the programmer, and by a programming discipline of only using references with references, address errors can be prevented.
+Hence, for type ©& const©, there is no pointer assignment, so ©&rc = &x© is disallowed, and \emph{the address value cannot be ©0© unless an arbitrary pointer is assigned to the reference}, e.g.:
+\begin{lstlisting}
+int & const r = *0;				§\C{// where 0 is the int * zero}§
+\end{lstlisting}
+Otherwise, the compiler is managing the addresses for type ©& const© not the programmer, and by a programming discipline of only using references with references, address errors can be prevented.
 
 \Index{Initialization} is different than \Index{assignment} because initialization occurs on the empty (uninitialized) storage on an object, while assignment occurs on possibly initialized storage of an object.
@@ -735,8 +738,8 @@
 \begin{lstlisting}
 int & f( int & rp );			§\C{// reference parameter and return}§
-z = f( x ) + f( y );			§\C{// reference operator added}§
+z = f( x ) + f( y );			§\C{// reference operator added, temporaries needed for call results}§
 \end{lstlisting}
 Within routine ©f©, it is possible to change the argument by changing the corresponding parameter, and parameter ©rp© can be locally reassigned within ©f©.
-The return reference from ©f© is copied into a compiler generated temporary, which is treated as an initialization.
+Since ©?+?© takes its arguments by value, the references returned from ©f© are used to initialize compiler generated temporaries with value semantics that copy from the references.
 
 When a pointer/reference parameter has a ©const© value (immutable), it is possible to pass literals and expressions.
@@ -1646,4 +1649,6 @@
 \end{lstlisting}
 The ability to fall-through to the next clause \emph{is} a useful form of control flow, specifically when a sequence of case actions compound:
+\begin{quote2}
+\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
 \begin{lstlisting}
 switch ( argc ) {
@@ -1658,4 +1663,19 @@
 }
 \end{lstlisting}
+&
+\begin{lstlisting}
+
+if ( argc == 3 ) {
+	// open output file
+	®// open input file
+®} else if ( argc == 2 ) {
+	®// open input file
+
+®} else {
+	// usage message
+}
+\end{lstlisting}
+\end{tabular}
+\end{quote2}
 In this example, case 2 is always done if case 3 is done.
 This control flow is difficult to simulate with if statements or a ©switch© statement without fall-through as code must be duplicated or placed in a separate routine.
@@ -1672,5 +1692,5 @@
 \end{lstlisting}
 However, this situation is handled in other languages without fall-through by allowing a list of case values.
-While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is not intuitive to most programmers and is different from virtually all other programming languages with a ©switch© statement.
+While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive to many programmers and is different from virtually all other programming languages with a ©switch© statement.
 Hence, default fall-through semantics results in a large number of programming errors as programmers often forget the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
 
@@ -1682,18 +1702,14 @@
 	if ( j < k ) {
 		...
-	  case 1:		// transfer into "if" statement
-		if ( j < m ) {
-			...
-		  case 2:	// transfer into "if" statement
-			...
-		}
-	}
-  case 3:
+	  ®case 1:®		// transfer into "if" statement
+		...
+	} // if
+  case 2:
 	while ( j < 5 ) {
 		...
-	  case 4:		// transfer into "while" statement
+	  ®case 3:®		// transfer into "while" statement
 		...
-	}
-}
+	} // while
+} // switch
 \end{lstlisting}
 The problem with this usage is branching into control structures, which is known to cause both comprehension and technical difficulties.
@@ -1734,16 +1750,21 @@
 \begin{lstlisting}
 switch ( x ) {
-	int y = 1;			§\C{// unreachable initialization}§
-	x = 7;				§\C{// unreachable code}§
+	®int y = 1;®				§\C{// unreachable initialization}§
+	®x = 7;®					§\C{// unreachable code without label/branch}§
   case 3: ...
-	y = 3;
 	...
+	®int z = 0;®				§\C{// unreachable initialization, cannot appear after case}§
+	z = 2;
+  case 3:
+	®x = z;®					§\C{// without fall through, z is uninitialized}§
 }
 \end{lstlisting}
 While the declaration of the local variable ©y© is useful and its scope is across all ©case© clauses, the initialization for such a variable is defined to never be executed because control always transfers over it.
-Furthermore, any statements before the first ©case© clause can only be executed if labelled and transfered to using a ©goto©, either from outside or inside of the ©switch©.
-As mentioned, transfer into control structures should be forbidden.
-Transfers from within the ©switch© body using a ©goto© are equally unpalatable.
+Furthermore, any statements before the first ©case© clause can only be executed if labelled and transferred to using a ©goto©, either from outside or inside of the ©switch©.
+As mentioned, transfer into control structures should be forbidden;
+transfers from within the ©switch© body using a ©goto© are equally unpalatable.
+As well, the declaration of ©z© is cannot occur after the ©case© because a label can only be attached to a statement, and without a fall through to case 3, ©z© is uninitialized.
 \end{enumerate}
+
 Before discussing potential language changes to deal with these problems, it is worth observing that in a typical C program:
 \begin{itemize}
@@ -1757,5 +1778,5 @@
 and there is only a medium amount of fall-through from one ©case© clause to the next, and most of these result from a list of case values executing common code, rather than a sequence of case actions that compound.
 \end{itemize}
-These observations help to put the effects of suggested changes into perspective.
+These observations help to put the suggested changes to the ©switch© into perspective.
 \begin{enumerate}
 \item
@@ -1767,43 +1788,48 @@
 still work.
 Nevertheless, reversing the default action would have a non-trivial effect on case actions that compound, such as the above example of processing shell arguments.
-Therefore, to preserve backwards compatibility, it is necessary to introduce a new kind of ©switch© statement, called ©choose©, with no fall-through semantics.
-The ©choose© statement is identical to the new ©switch© statement, except there is no implicit fall-through between case-clauses and the ©break© statement applies to the enclosing loop construct (as for the ©continue© statement in a ©switch© statement).
-It is still possible to fall-through if a case-clause ends with the new keyword ©fallthru©, e.g.:
+Therefore, to preserve backwards compatibility, it is necessary to introduce a new kind of ©switch© statement, called ©choose©, with no implicit fall-through semantics and an explicit fall-through if the last statement of a case-clause ends with the new keyword ©fallthru©, e.g.:
 \begin{lstlisting}
 ®choose® ( i ) {
-  case 3:
+  case 1:  case 2:  case 3:
 	...
-	®fallthru®;		§\C{// explicit fall through}§
-  case 5:
-	...				§\C{// implicit end of switch}§
+	®// implicit end of switch (break)
+  ®case 5:
+	...
+	®fallthru®;					§\C{// explicit fall through}§
   case 7:
 	...
-	®break®			§\C{// transfer to end of enclosing loop / switch}§
+	®break®						§\C{// explicit end of switch}§
   default:
 	j = 3;
 }
 \end{lstlisting}
-The ability to fall-through is retained because it is a sufficient C-idiom that most C programmers simply expect it, and its absence might discourage these programmers from using the ©choose© statement.
-\item
-Eliminating \Index*{Duff's device} is straightforward and only invalidates a small amount of very questionable code.
-The solution is to allow ©case© clauses to only appear at the same nesting level as the ©switch© body, as is done in most other programming languages with ©switch© statements.
+Like the ©switch© statement, the ©choose© statement retains the fall-through semantics for a list of ©case© clauses;
+the implicit ©break© is applied only at the end of the \emph{statements} following a ©case© clause.
+The explicit ©fallthru© is retained because it is a C-idiom most C programmers expect, and its absence might discourage programmers from using the ©choose© statement.
+As well, allowing an explicit ©break© from the ©choose© is a carry over from the ©switch© statement, and expected by C programmers.
+\item
+\Index*{Duff's device} is eliminated from both ©switch© and ©choose© statements, and only invalidates a small amount of very questionable code.
+Hence, the ©case© clause must appear at the same nesting level as the ©switch©/©choose© body, as is done in most other programming languages with ©switch© statements.
 \item
 The issue of ©default© at locations other than at the end of the cause clause can be solved by using good programming style, and there are a few reasonable situations involving fall-through where the ©default© clause needs to appear is locations other than at the end.
-Therefore, no language change is made for this issue.
-\item
-Dealing with unreachable code at the start of a ©switch© statement is solved by defining the declaration-list, including any associated initialization, at the start of a ©switch© statement body to be executed \emph{before} the transfer to the appropriate ©case© clause.
-This semantics is the same as for declarations at the start of a loop body, which are executed before each iteration of the loop body.
-As well, statements cannot appear before the first ©case© clause.
-The change is compatible for declarations with initialization in this context because existing code cannot assume the initialization has occurred.
-The change is incompatible for statements, but any existing code using it is highly questionable, as in:
-\begin{lstlisting}
-switch ( i ) {
-	L: x = 5;		§\C{// questionable code}§
+Therefore, no change is made for this issue.
+\item
+Dealing with unreachable code in a ©switch©/©choose© body is solved by restricting declarations and associated initialization to the start of statement body, which is executed \emph{before} the transfer to the appropriate ©case© clause.\footnote{
+Essentially, these declarations are hoisted before the statement and both declarations and statement are surrounded by a compound statement.} and precluding statements before the first ©case© clause.
+Further declaration in the statement body are disallowed.
+\begin{lstlisting}
+switch ( x ) {
+	®int i = 0;®				§\C{// allowed}§
   case 0:
 	...
-}
-\end{lstlisting}
-The statement after the ©switch© can never be executed unless it is labelled.
-If it is labelled, it must be transfered to from outside or inside the ©switch© statement, neither of which is acceptable control flow.
+	®int i = 0;®				§\C{// disallowed}§
+  case 1:
+    {
+		®int i = 0;®			§\C{// allowed in any compound statement}§
+		...
+	}
+  ...
+}
+\end{lstlisting}
 \end{enumerate}
 
@@ -1887,5 +1913,5 @@
 \section{Exception Handling}
 
-Exception handling provides two mechanim: change of control flow from a raise to a handler, and commumication from the riase to the handler.
+Exception handling provides two mechanism: change of control flow from a raise to a handler, and communication from the raise to the handler.
 \begin{lstlisting}
 exception void h( int i );
@@ -2140,5 +2166,5 @@
 A facility that let programmers declare specific constants..const Rational 12., for instance. would not be much of an improvement.
 Some facility for defining the creation of values of programmer-defined types from arbitrary integer tokens would be needed.
-The complexity of such a feature doesn.t seem worth the gain.
+The complexity of such a feature does not seem worth the gain.
 
 For example, to define the constants for a complex type, the programmer would define the following:
@@ -2668,5 +2694,5 @@
 } s;
 \end{lstlisting}
-The problem occurs in accesing these fields using the selection operation ``©.©'':
+The problem occurs in accessing these fields using the selection operation ``©.©'':
 \begin{lstlisting}
 s.0 = 0;	// ambiguity with floating constant .0
@@ -2678,5 +2704,5 @@
 ®s.§\textvisiblespace§1® = 1;
 \end{lstlisting}
-While this sytact is awkward, it is unlikely many programers will name fields of a structure 0 or 1.
+While this syntax is awkward, it is unlikely many programmers will name fields of a structure 0 or 1.
 Like the \Index*[C++]{\CC} lexical problem with closing template-syntax, e.g, ©Foo<Bar<int®>>®©, this issue can be solved with a more powerful lexer/parser.
 
@@ -2990,5 +3016,5 @@
 In \CFA, multiple definitions are not necessary.
 Within a module, all of the module's global definitions are visible throughout the module.
-For example, the following code compiles, even though isOdd was not declared before being called:
+For example, the following code compiles, even though ©isOdd© was not declared before being called:
 \begin{lstlisting}
 bool isEven(unsigned int x) {
@@ -4330,5 +4356,5 @@
 \item[Difficulty of converting:] keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism:
 \begin{lstlisting}
-int `otype` = 3;				// make keyword an indentifier
+int `otype` = 3;				// make keyword an identifier
 double `choose` = 3.5;
 \end{lstlisting}
@@ -4467,5 +4493,5 @@
 \begin{description}
 \item[Change:] comma expression is disallowed as subscript
-\item[Rationale:] safety issue to prevent subscripting error for multidimensional arrays: ©x[i,j]© instead of ©x[i][j]©, and this syntactic form then taken by \CFA for new styple arrays.
+\item[Rationale:] safety issue to prevent subscripting error for multidimensional arrays: ©x[i,j]© instead of ©x[i][j]©, and this syntactic form then taken by \CFA for new style arrays.
 \item[Effect on original feature:] change to semantics of well-defined feature.
 \item[Difficulty of converting:] semantic transformation of ©x[i,j]© to ©x[(i,j)]©
@@ -4479,5 +4505,5 @@
 \index{input/output library}
 
-The goal for the \CFA I/O is to make I/O as simple as possible in the common cases, while fully supporting polmorphism and user defined types in a consistent way.
+The goal for the \CFA I/O is to make I/O as simple as possible in the common cases, while fully supporting polymorphism and user defined types in a consistent way.
 The common case is printing out a sequence of variables separated by whitespace.
 \begin{quote2}
@@ -4516,9 +4542,9 @@
 Finally, the logical-or operator has a link with the Shell pipe-operator for moving data, although data flows in the opposite direction.
 
-The implicit seperator\index{I/O separator} character (space/blank) is a separator not a terminator.
+The implicit separator\index{I/O separator} character (space/blank) is a separator not a terminator.
 The rules for implicitly adding the separator are:
 \begin{enumerate}
 \item
-A seperator does not appear at the start or end of a line.
+A separator does not appear at the start or end of a line.
 \begin{lstlisting}[belowskip=0pt]
 sout | 1 | 2 | 3 | endl;
@@ -4528,5 +4554,5 @@
 \end{lstlisting}
 \item
-A seperator does not appear before or after a character literal or variable.
+A separator does not appear before or after a character literal or variable.
 \begin{lstlisting}
 sout | '1' | '2' | '3' | endl;
@@ -4534,5 +4560,5 @@
 \end{lstlisting}
 \item
-A seperator does not appear before or after a null (empty) C string
+A separator does not appear before or after a null (empty) C string
 \begin{lstlisting}
 sout | 1 | "" | 2 | "" | 3 | endl;
@@ -4541,5 +4567,5 @@
 which is a local mechanism to disable insertion of the separator character.
 \item
-A seperator does not appear before a C string starting with the (extended) \Index{ASCII}\index{ASCII!extended} characters: \lstinline[mathescape=off]@([{$£¥¡¿«@
+A separator does not appear before a C string starting with the (extended) \Index{ASCII}\index{ASCII!extended} characters: \lstinline[mathescape=off]@([{$£¥¡¿«@
 %$
 \begin{lstlisting}[mathescape=off]
@@ -4744,5 +4770,5 @@
 
 
-\subsection{min / max / swap}
+\subsection{min / max / clamp / swap}
 
 \begin{lstlisting}[aboveskip=0pt,belowskip=0pt]
@@ -4752,4 +4778,7 @@
 forall( otype T | { int ?>?( T, T ); } )
 T max( const T t1, const T t2 );§\indexc{max}§
+
+forall( otype T | { T min( T, T ); T max( T, T ); } )
+T clamp( T value, T min_val, T max_val );§\indexc{clamp}§
 
 forall( otype T )
@@ -5136,5 +5165,5 @@
 When creating and computing with rational numbers, results are constantly reduced to keep the numerator and denominator as small as possible.
 
-\begin{lstlisting}[aboveskip=0pt,belowskip=0pt]
+\begin{lstlisting}[belowskip=0pt]
 // implementation
 struct Rational {§\indexc{Rational}§
