%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -*- Mode: Latex -*- %%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Cforall Version 1.0.0 Copyright (C) 2016 University of Waterloo
%%
%% The contents of this file are covered under the licence agreement in the
%% file "LICENCE" distributed with Cforall.
%%
%% user.tex --
%%
%% Author           : Peter A. Buhr
%% Created On       : Wed Apr  6 14:53:29 2016
%% Last Modified By : Peter A. Buhr
%% Last Modified On : Sat Mar 27 09:55:55 2021
%% Update Count     : 4796
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% requires tex packages: texlive-base texlive-latex-base tex-common texlive-humanities texlive-latex-extra texlive-fonts-recommended

\documentclass[twoside,11pt]{article}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Latex packages used in the document.
\usepackage[T1]{fontenc}                                % allow Latin1 (extended ASCII) characters
\usepackage{textcomp}
\usepackage[latin1]{inputenc}

\usepackage{fullpage,times,comment}
\usepackage{epic,eepic}
\usepackage{upquote}									% switch curled `'" to straight
\usepackage{calc}
\usepackage{varioref}									% extended references
\usepackage[labelformat=simple,aboveskip=0pt,farskip=0pt]{subfig}
\renewcommand{\thesubfigure}{\alph{subfigure})}
\usepackage[flushmargin]{footmisc}						% support label/reference in footnote
\usepackage{latexsym}                                   % \Box glyph
\usepackage{mathptmx}                                   % better math font with "times"
\usepackage[usenames]{color}
\usepackage[dvips,plainpages=false,pdfpagelabels,pdfpagemode=UseNone,colorlinks=true,pagebackref=true,linkcolor=blue,citecolor=blue,urlcolor=blue,pagebackref=true,breaklinks=true]{hyperref}
\usepackage{breakurl}

\renewcommand\footnoterule{\kern -3pt\rule{0.3\linewidth}{0.15pt}\kern 2pt}

\usepackage[pagewise]{lineno}
\renewcommand{\linenumberfont}{\scriptsize\sffamily}
\usepackage[firstpage]{draftwatermark}
\SetWatermarkLightness{0.9}

% Default underscore is too low and wide. Cannot use lstlisting "literate" as replacing underscore
% removes it as a variable-name character so keywords in variables are highlighted. MUST APPEAR
% AFTER HYPERREF.
\renewcommand{\textunderscore}{\leavevmode\makebox[1.2ex][c]{\rule{1ex}{0.075ex}}}

\setlength{\topmargin}{-0.45in}							% move running title into header
\setlength{\headsep}{0.25in}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newcommand{\CFALatin}{}
% inline code ©...© (copyright symbol) emacs: C-q M-)
% red highlighting ®...® (registered trademark symbol) emacs: C-q M-.
% blue highlighting ß...ß (sharp s symbol) emacs: C-q M-_
% green highlighting ¢...¢ (cent symbol) emacs: C-q M-"
% LaTex escape §...§ (section symbol) emacs: C-q M-'
% keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
% math escape $...$ (dollar symbol)
\input{common}                                          % common CFA document macros
\CFAStyle												% use default CFA format-style
\lstset{language=CFA}									% CFA default lnaguage
\lstnewenvironment{C++}[1][]                            % use C++ style
{\lstset{language=C++,moredelim=**[is][\protect\color{red}]{@}{@},#1}}
{}

\newsavebox{\myboxA}
\newsavebox{\myboxB}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Names used in the document.
\newcommand{\Version}{\input{build/version}}
\newcommand{\Textbf}[2][red]{{\color{#1}{\textbf{#2}}}}
\newcommand{\Emph}[2][red]{{\color{#1}\textbf{\emph{#2}}}}
\newcommand{\R}[1]{\Textbf{#1}}
\newcommand{\RC}[1]{\Textbf{\LstBasicStyle{#1}}}
\newcommand{\B}[1]{{\Textbf[blue]{#1}}}
\newcommand{\G}[1]{{\Textbf[OliveGreen]{#1}}}
\newcommand{\KWC}{K-W C\xspace}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\setcounter{secnumdepth}{3}                             % number subsubsections
\setcounter{tocdepth}{3}                                % subsubsections in table of contents
\makeindex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\title{\Huge
\vspace*{1in}
\CFA (\CFL) User Manual				\\
Version 1.0						 	\\
\vspace*{0.25in}
\huge``describe not prescribe''
\vspace*{1in}
}% title

\author{
\huge \CFA Team (past and present) \medskip \\
\Large Andrew Beach, Richard Bilson, Michael Brooks, Peter A. Buhr, Thierry Delisle, \smallskip \\
\Large Glen Ditchfield, Rodolfo G. Esteves, Aaron Moss, Colby Parsons, Rob Schluntz, \smallskip \\
\Large Fangren Yu, Mubeen Zulfiqar
}% author

\date{
\today
}% date

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}
\pagestyle{headings}
% changed after setting pagestyle
\renewcommand{\sectionmark}[1]{\markboth{\thesection\quad #1}{\thesection\quad #1}}
\renewcommand{\subsectionmark}[1]{\markboth{\thesubsection\quad #1}{\thesubsection\quad #1}}
\pagenumbering{roman}
\linenumbers                                            % comment out to turn off line numbering

\maketitle
\thispagestyle{empty}
\vspace*{\fill}
\noindent
\copyright\,2016, 2018, 2021 \CFA Project \\ \\
\noindent
This work is licensed under the Creative Commons Attribution 4.0 International License.
To view a copy of this license, visit {\small\url{http://creativecommons.org/licenses/by/4.0}}.
\vspace*{1in}

\clearpage
\thispagestyle{plain}
\pdfbookmark[1]{Contents}{section}
\tableofcontents

\clearpage
\thispagestyle{plain}
\pagenumbering{arabic}


\section{Introduction}

\CFA{}\index{cforall@\CFA}\footnote{Pronounced ``\Index*{C-for-all}'', and written \CFA, CFA, or \CFL.} is a modern general-purpose concurrent programming-language, designed as an evolutionary step forward for the C programming language.
The syntax of \CFA builds from C and should look immediately familiar to C/\Index*[C++]{\CC{}} programmers.
% Any language feature that is not described here can be assumed to be using the standard \Celeven syntax.
\CFA adds many modern features that directly lead to increased \emph{\Index{safety}} and \emph{\Index{productivity}}, while maintaining interoperability with existing C programs and achieving similar performance.
Like C, \CFA is a statically typed, procedural (non-\Index{object-oriented}) language with a low-overhead runtime, meaning there is no global \Index{garbage-collection}, but \Index{regional garbage-collection}\index{garbage-collection!regional} is possible.
The primary new features include polymorphic routines and types, exceptions, concurrency, and modules.

One of the main design philosophies of \CFA is to ``\Index{describe not prescribe}'', which means \CFA tries to provide a pathway from low-level C programming to high-level \CFA programming, but it does not force programmers to ``do the right thing''.
Programmers can cautiously add \CFA extensions to their C programs in any order and at any time to incrementally move towards safer, higher-level programming.
A programmer is always free to reach back to C from \CFA, for any reason, and in many cases, new \CFA features can be locally switched back to there C counterpart.
There is no notion or requirement for \emph{rewriting} a legacy C program in \CFA;
instead, a programmer evolves a legacy program into \CFA by incrementally incorporating \CFA features.
As well, new programs can be written in \CFA using a combination of C and \CFA features.
In many ways, \CFA is to C as \Index{Scala}~\cite{Scala} is to Java, providing a vehicle for new typing and control-flow capabilities on top of a highly popular programming language allowing immediate dissemination.

\Index*[C++]{\CC{}}~\cite{c++:v1} had a similar goal 30 years ago, allowing object-oriented programming to be incrementally added to C.
However, \CC currently has the disadvantages of a strong object-oriented bias, multiple legacy design-choices that cannot be updated, and active divergence of the language model from C, requiring significant effort and training to incrementally add \CC to a C-based project.
In contrast, \CFA has 30 years of hindsight and a clean starting point.

Like \Index*[C++]{\CC{}}, there may be both an old and new ways to achieve the same effect.
For example, the following programs compare the C, \CFA, and \CC I/O mechanisms, where the programs output the same result.
\begin{center}
\begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
\multicolumn{1}{c@{\hspace{1em}}}{\textbf{C}}	& \multicolumn{1}{c}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{\CC}}	\\
\begin{cfa}
#include <stdio.h>$\indexc{stdio.h}$

int main( void ) {
	int x = 0, y = 1, z = 2;
	@printf( "%d %d %d\n", x, y, z );@
}
\end{cfa}
&
\begin{cfa}
#include <fstream>$\indexc{fstream}$

int main( void ) {
	int x = 0, y = 1, z = 2;
	@sout | x | y | z;@$\indexc{sout}$
}
\end{cfa}
&
\begin{cfa}
#include <iostream>$\indexc{iostream}$
using namespace std;
int main() {
	int x = 0, y = 1, z = 2;
	@cout<<x<<" "<<y<<" "<<z<<endl;@
}
\end{cfa}
\end{tabular}
\end{center}
While \CFA I/O \see{\VRef{s:StreamIOLibrary}} looks similar to \Index*[C++]{\CC{}}, there are important differences, such as automatic spacing between variables and an implicit newline at the end of the expression list, similar to \Index*{Python}~\cite{Python}.


\subsection{Background}

This document is a programmer reference-manual for the \CFA programming language.
The manual covers the core features of the language and runtime-system, with simple examples illustrating syntax and semantics of features.
The manual does not teach programming, \ie how to combine the new constructs to build complex programs.
The reader must have an intermediate knowledge of control flow, data structures, and concurrency issues to understand the ideas presented, as well as some experience programming in C/\CC.
Implementers should refer to the \CFA Programming Language Specification for details about the language syntax and semantics.
Changes to the syntax and additional features are expected to be included in later revisions.


\section{Why fix C?}

The C programming language is a foundational technology for modern computing with billions of lines of code implementing everything from hobby projects to commercial operating-systems.
This installation base and the programmers producing it represent a massive software-engineering investment spanning decades and likely to continue for decades more.
Even with all its problems, C continues to be popular because it allows writing software at virtually any level in a computer system without restriction.
For system programming, where direct access to hardware, storage management, and real-time issues are a requirement, C is the only language of choice.
The TIOBE index~\cite{TIOBE} for February 2021 ranks the top six most \emph{popular} programming languages as C 17.4\%, \Index*{Java} 12\%, Python 12\%, \Index*[C++]{\CC{}} 7.6\%, \Csharp 4\%, Visual Basic 3.8\% = 56.8\%, where the next 50 languages are less than 2\% each, with a long tail.
The top 4 rankings over the past 35 years are:
\begin{center}
\setlength{\tabcolsep}{10pt}
\begin{tabular}{@{}rcccccccc@{}}
		& 2021	& 2016	& 2011	& 2006	& 2001	& 1996	& 1991	& 1986	\\ \hline
\R{C}	& \R{1} & \R{2} & \R{2} & \R{1} & \R{1} & \R{1} & \R{1} & \R{1} \\
Java	& 2		& 1		& 1		& 2		& 3		& 28	& -		& -		\\
Python	& 3		& 5		& 6		& 7		& 23	& 13	& -		& -		\\
\CC		& 4		& 3		& 3		& 3		& 2		& 2		& 2		& 8		\\
\end{tabular}
\end{center}
Hence, C is still an extremely important programming language, with double the usage of \Index*[C++]{\CC{}}; in many cases, \CC is often used solely as a better C.
Love it or hate it, C has been an important and influential part of computer science for 40 years and its appeal is not diminishing.
Nevertheless, C has many problems and omissions that make it an unacceptable programming language for modern needs.

As stated, the goal of the \CFA project is to engineer modern language-features into C in an evolutionary rather than revolutionary way.
\CC~\cite{C++14,C++} is an example of a similar project;
however, it largely extended the C language, and did not address many of C's existing problems.\footnote{%
Two important existing problems addressed were changing the type of character literals from ©int© to ©char© and enumerator from ©int© to the type of its enumerators.}
\Index*{Fortran}~\cite{Fortran08}, \Index*{Ada}~\cite{Ada12}, and \Index*{Cobol}~\cite{Cobol14} are examples of programming languages that took an evolutionary approach, where modern language-features (\eg objects, concurrency) are added and problems fixed within the framework of the existing language.
\Index*{Java}~\cite{Java8}, \Index*{Go}~\cite{Go}, \Index*{Rust}~\cite{Rust} and \Index*{D}~\cite{D} are examples of the revolutionary approach for modernizing C/\CC, resulting in a new language rather than an extension of the descendent.
These languages have different syntax and semantics from C, do not interoperate directly with C, and are not systems languages because of restrictive memory-management or garbage collection.
As a result, there is a significant learning curve to move to these languages, and C legacy-code must be rewritten.
These costs can be prohibitive for many companies with a large software-base in C/\CC, and a significant number of programmers require retraining in the new programming language.

The result of this project is a language that is largely backwards compatible with \Index*[C11]{\Celeven{}}~\cite{C11}, but fixes many of the well known C problems while adding modern language-features.
To achieve these goals required a significant engineering exercise, \ie ``thinking \emph{inside} the C box''.
Considering the large body of existing C code and programmers, there is significant impetus to ensure C is transformed into a modern language.
While \Index*[C11]{\Celeven{}} made a few simple extensions to the language, nothing was added to address existing problems in the language or to augment the language with modern language-features.
While some may argue that modern language-features may make C complex and inefficient, it is clear a language without modern capabilities is insufficient for the advanced programming problems existing today.


\section{History}

The \CFA project started with \Index*{Dave Till}\index{Till, Dave}'s \Index*{K-W C}~\cite{Buhr94a,Till89}, which extended C with new declaration syntax, multiple return values from routines, and advanced assignment capabilities using the notion of tuples \see{\cite{Werther96} for similar work in \Index*[C++]{\CC{}}}.
The first \CFA implementation of these extensions was by \Index*{Rodolfo Esteves}\index{Esteves, Rodolfo}~\cite{Esteves04}.

The signature feature of \CFA is \emph{\Index{overload}able} \Index{parametric-polymorphic} functions~\cite{forceone:impl,Cormack90,Duggan96} with functions generalized using a ©forall© clause (giving the language its name):
\begin{cfa}
@forall( otype T )@ T identity( T val ) { return val; }
int forty_two = identity( 42 ); $\C{// T is bound to int, forty\_two == 42}$
\end{cfa}
% extending the C type system with parametric polymorphism and overloading, as opposed to the \Index*[C++]{\CC{}} approach of object-oriented extensions.
\CFA{}\hspace{1pt}'s polymorphism was originally formalized by \Index*{Glen Ditchfield}\index{Ditchfield, Glen}~\cite{Ditchfield92}, and first implemented by \Index*{Richard Bilson}\index{Bilson, Richard}~\cite{Bilson03}.
However, at that time, there was little interesting in extending C, so work did not continue.
As the saying goes, ``\Index*{What goes around, comes around.}'', and there is now renewed interest in the C programming language because of the legacy code-base, so the \CFA project was restarted in 2015.


\section{Interoperability}
\label{s:Interoperability}

\CFA is designed to integrate directly with existing C programs and libraries.
The most important feature of \Index{interoperability} is using the same \Index{calling convention}s, so there is no complex interface or overhead to call existing C routines.
This feature allows \CFA programmers to take advantage of the existing panoply of C libraries to access thousands of external software features.
Language developers often state that adequate \Index{library support} takes more work than designing and implementing the language itself.
Fortunately, \CFA, like \Index*[C++]{\CC{}}, starts with immediate access to all exiting C libraries, and in many cases, can easily wrap library routines with simpler and safer interfaces, at zero or very low cost.
Hence, \CFA begins by leveraging the large repository of C libraries, and than allows programmers to incrementally augment their C programs with modern \Index{backward-compatible} features.

\begin{comment}
A simple example is leveraging the existing type-unsafe (©void *©) C ©bsearch© to binary search a sorted floating array:
\begin{cfa}
void * bsearch( const void * key, const void * base, size_t dim, size_t size,
				int (* compar)( const void *, const void * ));

int comp( const void * t1, const void * t2 ) { return *(double *)t1 < *(double *)t2 ? -1 :
				*(double *)t2 < *(double *)t1 ? 1 : 0; }

double key = 5.0, vals[10] = { /* 10 sorted floating values */ };
double * val = (double *)bsearch( &key, vals, 10, sizeof(vals[0]), comp ); $\C{// search sorted array}$
\end{cfa}
which can be augmented simply with a polymorphic, type-safe, \CFA-overloaded wrappers:
\begin{cfa}
forall( otype T | { int ?<?( T, T ); } ) T * bsearch( T key, const T * arr, size_t size ) {
	int comp( const void * t1, const void * t2 ) { /* as above with double changed to T */ }
	return (T *)bsearch( &key, arr, size, sizeof(T), comp ); }

forall( otype T | { int ?<?( T, T ); } ) unsigned int bsearch( T key, const T * arr, size_t size ) {
	T * result = bsearch( key, arr, size ); $\C{// call first version}$
	return result ? result - arr : size; } $\C{// pointer subtraction includes sizeof(T)}$

double * val = bsearch( 5.0, vals, 10 ); $\C{// selection based on return type}$
int posn = bsearch( 5.0, vals, 10 );
\end{cfa}
The nested function ©comp© provides the hidden interface from typed \CFA to untyped (©void *©) C, plus the cast of the result.
Providing a hidden ©comp© function in \CC is awkward as lambdas do not use C calling-conventions and template declarations cannot appear at block scope.
As well, an alternate kind of return is made available: position versus pointer to found element.
\CC's type-system cannot disambiguate between the two versions of ©bsearch© because it does not use the return type in overload resolution, nor can \CC separately compile a templated ©bsearch©.

\CFA has replacement libraries condensing hundreds of existing C functions into tens of \CFA overloaded functions, all without rewriting the actual computations.
For example, it is possible to write a type-safe \CFA wrapper ©malloc© based on the C ©malloc©:
\begin{cfa}
forall( dtype T | sized(T) ) T * malloc( void ) { return (T *)malloc( sizeof(T) ); }
int * ip = malloc(); $\C{// select type and size from left-hand side}$
double * dp = malloc();
struct S {...} * sp = malloc();
\end{cfa}
where the return type supplies the type/size of the allocation, which is impossible in most type systems.
\end{comment}

However, it is necessary to differentiate between C and \CFA code because of name \Index{overload}ing, as for \CC.
For example, the C math-library provides the following routines for computing the absolute value of the basic types: ©abs©, ©labs©, ©llabs©, ©fabs©, ©fabsf©, ©fabsl©, ©cabsf©, ©cabs©, and ©cabsl©.
Whereas, \CFA wraps each of these routines into one overloaded name ©abs©:
\begin{cfa}
char @abs@( char );
extern "C" { int @abs@( int ); } $\C{// use default C routine for int}$
long int @abs@( long int );
long long int @abs@( long long int );
float @abs@( float );
double @abs@( double );
long double @abs@( long double );
float _Complex @abs@( float _Complex );
double _Complex @abs@( double _Complex );
long double _Complex @abs@( long double _Complex );
\end{cfa}
The problem is \Index{name clash} between the C name ©abs© and the \CFA names ©abs©, resulting in two name linkages\index{C linkage}: ©extern "C"© and ©extern "Cforall"© (default).
Overloaded names must use \newterm{name mangling}\index{mangling!name} to create unique names that are different from unmangled C names.
Hence, there is the same need as in \CC to know if a name is a C or \CFA name, so it can be correctly formed.
The only way around this problem is C's approach of creating unique names for each pairing of operation and type.

This example illustrates a core idea in \CFA: \emph{the \Index{power of a name}}.
The name ``©abs©'' evokes the notion of absolute value, and many mathematical types provide the notion of absolute value.
Hence, knowing the name ©abs© is sufficient to apply it to any type where it is applicable.
The time savings and safety of using one name uniformly versus $N$ unique names cannot be underestimated.


\section{\CFA Compilation}

The command ©cfa© is used to compile a \CFA program and is based on the \Index{GNU} \Indexc{gcc} command, \eg:
\begin{cfa}
cfa$\indexc{cfa}\index{compilation!cfa@©cfa©}$ [ gcc/$\CFA{}$-options ] [ C/$\CFA{}$ source-files ] [ assembler/loader files ]
\end{cfa}
There is no ordering among options (flags) and files, unless an option has an argument, which must appear immediately after the option possibly with or without a space separating option and argument.

\CFA has the following ©gcc© flags turned on:
\begin{description}[topsep=0pt]
\item
\Indexc{-std=gnu11}\index{compilation option!-std=gnu11@{©-std=gnu11©}}
The 2011 C standard plus GNU extensions.
\item
\Indexc[deletekeywords=inline]{-fgnu89-inline}\index{compilation option!-fgnu89-inline@{\lstinline[deletekeywords=inline]$-fgnu89-inline$}}
Use the traditional GNU semantics for inline routines in C11 mode, which allows inline routines in header files.
\end{description}

\CFA has the following new options:
\begin{description}[topsep=0pt]
\item
\Indexc{-CFA}\index{compilation option!-CFA@©-CFA©}
Only the C preprocessor (flag ©-E©) and the \CFA translator steps are performed and the transformed program is written to standard output, which makes it possible to examine the code generated by the \CFA translator.
The generated code starts with the standard \CFA \Index{prelude}.

\item
\Indexc{-XCFA}\index{compilation option!-XCFA@©-XCFA©}
Pass next flag as-is to the ©cfa-cpp© translator (see details below).

\item
\Indexc{-debug}\index{compilation option!-debug@©-debug©}
The program is linked with the debugging version of the runtime system.
The debug version performs runtime checks to aid the debugging phase of a \CFA program, but can substantially slow program execution.
The runtime checks should only be removed after the program is completely debugged.
\textbf{This option is the default.}

\item
\Indexc{-nodebug}\index{compilation option!-nodebug@©-nodebug©}
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 behaviour or termination.}

\item
\Indexc{-help}\index{compilation option!-help@©-help©}
Information about the set of \CFA compilation flags is printed.

\item
\Indexc{-nohelp}\index{compilation option!-nohelp@©-nohelp©}
Information about the set of \CFA compilation flags is not printed.
\textbf{This option is the default.}

\item
\Indexc{-quiet}\index{compilation option!-quiet@©-quiet©}
The \CFA compilation message is not printed at the beginning of a compilation.

\item
\Indexc{-noquiet}\index{compilation option!-noquiet@©-noquiet©}
The \CFA compilation message is printed at the beginning of a compilation.
\textbf{This option is the default.}

\begin{comment}
\item
\Indexc{-no-include-stdhdr}\index{compilation option!-no-include-stdhdr@©-no-include-stdhdr©}
Do not supply ©extern "C"© wrappers for \Celeven standard include files \see{\VRef{s:StandardHeaders}}.
\textbf{This option is \emph{not} the default.}
\end{comment}
\end{description}

The following preprocessor variables are available:
\begin{description}
\item
\Indexc{__CFA_MAJOR__}\index{preprocessor variables!__CFA__@{©__CFA__©}}
is available during preprocessing and its value is the major \Index{version number} of \CFA.\footnote{
The C preprocessor allows only integer values in a preprocessor variable so a value like ``\Version'' is not allowed.
Hence, the need to have three variables for the major, minor and patch version number.}

\item
\Indexc{__CFA_MINOR__}\index{preprocessor variables!__CFA_MINOR__@{©__CFA_MINOR__©}}
is available during preprocessing and its value is the minor \Index{version number} of \CFA.

\item
\Indexc{__CFA_PATCH__}\index{preprocessor variables!__CFA_PATCH__@©__CFA_PATCH__©}
is available during preprocessing and its value is the patch \Index{level number} of \CFA.

\item
\Indexc{__CFA__}\index{preprocessor variables!__CFA__@©__CFA__©},
\Indexc{__CFORALL__}\index{preprocessor variables!__CFORALL__@©__CFORALL__©}, and
\Indexc{__cforall}\index{preprocessor variables!__cforall@©__cforall©}
are always available during preprocessing and have no value.
\end{description}
These preprocessor variables allow conditional compilation of programs that must work differently in these situations.
For example, to toggle between C and \CFA extensions, use the following:
\begin{cfa}
#ifndef __CFORALL__
#include <stdio.h>$\indexc{stdio.h}$ $\C{// C header file}$
#else
#include <fstream>$\indexc{fstream}$ $\C{// \CFA header file}$
#endif
\end{cfa}
which conditionally includes the correct header file, if the program is compiled using \Indexc{gcc} or \Indexc{cfa}.

The \CFA translator has multiple steps.
The following flags control how the translator works, the stages run, and printing within a stage.
The majority of these flags are used by \CFA developers, but some are occasionally useful to programmers.
Each option must be escaped with \Indexc{-XCFA}\index{translator option!-XCFA@{©-XCFA©}} to direct it to the compiler step, similar to the ©-Xlinker© flag for the linker, \eg:
\begin{lstlisting}[language=sh]
cfa $test$.cfa -CFA -XCFA -p # print translated code without printing the standard prelude
cfa $test$.cfa -XCFA -P -XCFA parse -XCFA -n # show program parse without prelude
\end{lstlisting}
\begin{description}[topsep=5pt,itemsep=0pt,parsep=0pt]
\item
\Indexc{-c}\index{translator option!-c@{©-c©}}, \Indexc{--colors}\index{translator option!--colors@{©--colors©}} \, diagnostic color: ©never©, ©always©, \lstinline[deletekeywords=auto]{auto}
\item
\Indexc{-g}\index{translator option!-g@{©-g©}}, \Indexc{--gdb}\index{translator option!--gdb@{©--gdb©}} \, wait for gdb to attach
\item
\Indexc{-h}\index{translator option!-h@{©-h©}}, \Indexc{--help}\index{translator option!--help@{©--help©}} \, print translator help message
\item
\Indexc{-l}\index{translator option!-l@{©-l©}}, \Indexc{--libcfa}\index{translator option!--libcfa@{©--libcfa©}} \, generate ©libcfa.c©
\item
\Indexc{-L}\index{translator option!-L@{©-L©}}, \Indexc{--linemarks}\index{translator option!--linemarks@{©--linemarks©}} \, generate line marks
\item
\Indexc{-m}\index{translator option!-m@{©-m©}}, \Indexc{--no-main}\index{translator option!--no-main@{©--no-main©}} \, do not replace main
\item
\Indexc{-N}\index{translator option!-N@{©-N©}}, \Indexc{--no-linemarks}\index{translator option!--no-linemarks@{©--no-linemarks©}} \, do not generate line marks
\item
\Indexc{-n}\index{translator option!-n@{©-n©}}, \Indexc{--no-prelude}\index{translator option!--no-prelude@{©--no-prelude©}} \, do not read prelude
\item
\Indexc{-p}\index{translator option!-p@{©-p©}}, \Indexc{--prototypes}\index{translator option!--prototypes@{©--prototypes©}} \, do not generate prelude prototypes $\Rightarrow$ prelude not printed
\item
\Indexc{-d}\index{translator option!-d@{©-d©}}, \Indexc{--deterministic-out}\index{translator option!--deterministic-out@{©--deterministic-out©}} \, only print deterministic output
\item
\Indexc{-P}\index{translator option!-P@{©-P©}}, \Indexc{--print}\index{translator option!--print@{©--print©}} \, one of:
\begin{description}[topsep=0pt,itemsep=0pt,parsep=0pt]
\item
\Indexc{ascodegen}\index{translator option!-P@{©-P©}!©ascodegen©}\index{translator option!--print@{©-print©}!©ascodegen©} \, as codegen rather than AST
\item
\Indexc{asterr}\index{translator option!-P@{©-P©}!©asterr©}\index{translator option!--print@{©-print©}!©asterr©} \, AST on error
\item
\Indexc{declstats}\index{translator option!-P@{©-P©}!©declstats©}\index{translator option!--print@{©-print©}!©declstats©} \, code property statistics
\item
\Indexc{parse}\index{translator option!-P@{©-P©}!©parse©}\index{translator option!--print@{©-print©}!©parse©} \, yacc (parsing) debug information
\item
\Indexc{pretty}\index{translator option!-P@{©-P©}!©pretty©}\index{translator option!--print@{©-print©}!©pretty©} \, prettyprint for ©ascodegen© flag
\item
\Indexc{rproto}\index{translator option!-P@{©-P©}!©rproto©}\index{translator option!--print@{©-print©}!©rproto©} \, resolver-proto instance
\item
\Indexc{rsteps}\index{translator option!-P@{©-P©}!©rsteps©}\index{translator option!--print@{©-print©}!©rsteps©} \, resolver steps
\item
\Indexc{tree}\index{translator option!-P@{©-P©}!©tree©}\index{translator option!--print@{©-print©}!©tree©} \, parse tree
\item
\Indexc{ast}\index{translator option!-P@{©-P©}!©ast©}\index{translator option!--print@{©-print©}!©ast©} \, AST after parsing
\item
\Indexc{symevt}\index{translator option!-P@{©-P©}!©symevt©}\index{translator option!--print@{©-print©}!©symevt©} \, symbol table events
\item
\Indexc{altexpr}\index{translator option!-P@{©-P©}!©altexpr©}\index{translator option!--print@{©-print©}!©altexpr©} \, alternatives for expressions
\item
\Indexc{astdecl}\index{translator option!-P@{©-P©}!©astdecl©}\index{translator option!--print@{©-print©}!©astdecl©} \, AST after declaration validation pass
\item
\Indexc{resolver}\index{translator option!-P@{©-P©}!©resolver©}\index{translator option!--print@{©-print©}!©resolver©} \, before resolver step
\item
\Indexc{astexpr}\index{translator option!-P@{©-P©}!©astexpr©}\index{translator option!--print@{©-print©}!©altexpr©} \, AST after expression analysis
\item
\Indexc{ctordtor}\index{translator option!-P@{©-P©}!©ctordtor©}\index{translator option!--print@{©-print©}!©ctordtor©} \, after ctor/dtor are replaced
\item
\Indexc{tuple}\index{translator option!-P@{©-P©}!©tuple©}\index{translator option!--print@{©-print©}!©tuple©} \, after tuple expansion
\item
\Indexc{astgen}\index{translator option!-P@{©-P©}!©astgen©}\index{translator option!--print@{©-print©}!©astgen©} \, AST after instantiate generics
\item
\Indexc{box}\index{translator option!-P@{©-P©}!©box©}\index{translator option!--print@{©-print©}!©box©} \, before box step
\item
\Indexc{codegen}\index{translator option!-P@{©-P©}!©codegen©}\index{translator option!--print@{©-print©}!©codegen©} \, before code generation
\end{description}
\item
\Indexc{--prelude-dir} <directory> \, prelude directory for debug/nodebug
\item
\Indexc{-S}\index{translator option!-S@{©-S©}!©counters,heap,time,all,none©}, \Indexc{--statistics}\index{translator option!--statistics@{©--statistics©}!©counters,heap,time,all,none©} <option-list> \, enable profiling information: ©counters©, ©heap©, ©time©, ©all©, ©none©
\item
\Indexc{-t}\index{translator option!-t@{©-t©}}, \Indexc{--tree}\index{translator option!--tree@{©--tree©}} build in tree
\end{description}


\section{Backquote Identifiers}
\label{s:BackquoteIdentifiers}

\CFA introduces several new keywords \see{\VRef{s:CFAKeywords}} that can clash with existing C variable-names in legacy code.
Keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism:
\begin{cfa}
int @``@otype = 3; $\C{// make keyword an identifier}$
double @``@forall = 3.5;
\end{cfa}

Existing C programs with keyword clashes can be converted by enclosing keyword identifiers in backquotes, and eventually the identifier name can be changed to a non-keyword name.
\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in existing C header-files \see{\VRef{s:StandardHeaders}} can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©.
Several common C header-files with keyword clashes are fixed in the standard \CFA header-library, so there is a seamless programming-experience.

\begin{figure}
\begin{cfa}
// include file uses the CFA keyword "with".
#if ! defined( with )							$\C{// nesting ?}$
#define with @``@with							$\C{// make keyword an identifier}$
#define __CFA_BFD_H__
#endif
$\R{\#include\_next} <bfdlink.h>$				$\C{// must have internal check for multiple expansion}$
#if defined( with ) && defined( __CFA_BFD_H__ )	$\C{// reset only if set}$
#undef with
#undef __CFA_BFD_H__
#endif
\end{cfa}
\caption{Header-File Interposition}
\label{f:HeaderFileInterposition}
\end{figure}


\section{Constant Underscores}

Numeric constants are extended to allow \Index{underscore}s\index{constant!underscore} as a separator, \eg:
\begin{cfa}
2@_@147@_@483@_@648; $\C{// decimal constant}$
56@_@ul; $\C{// decimal unsigned long constant}$
0@_@377; $\C{// octal constant}$
0x@_@ff@_@ff; $\C{// hexadecimal constant}$
0x@_@ef3d@_@aa5c; $\C{// hexadecimal constant}$
3.141@_@592@_@654; $\C{// floating constant}$
10@_@e@_@+1@_@00; $\C{// floating constant}$
0x@_@ff@_@ff@_@p@_@3; $\C{// hexadecimal floating}$
0x@_@1.ffff@_@ffff@_@p@_@128@_@l; $\C{// hexadecimal floating long constant}$
L@_@$"\texttt{\textbackslash{x}}$@_@$\texttt{ff}$@_@$\texttt{ee}"$; $\C{// wide character constant}$
\end{cfa}
The rules for placement of underscores are:
\begin{enumerate}[topsep=5pt,itemsep=5pt,parsep=0pt]
\item
A sequence of underscores is disallowed, \eg ©12__34© is invalid.
\item
Underscores may only appear within a sequence of digits (regardless of the digit radix).
In other words, an underscore cannot start or end a sequence of digits, \eg ©_1©, ©1_© and ©_1_© are invalid (actually, the 1st and 3rd examples are identifier names).
\item
A numeric prefix may end with an underscore;
a numeric infix may begin and/or end with an underscore;
a numeric suffix may begin with an underscore.
For example, the octal ©0© or hexadecimal ©0x© prefix may end with an underscore ©0_377© or ©0x_ff©;
the exponent infix ©E© may start or end with an underscore ©1.0_E10©, ©1.0E_10© or ©1.0_E_10©;
the type suffixes ©U©, ©L©, etc. may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
\end{enumerate}
It is significantly easier to read and enter long constants when they are broken up into smaller groupings (many cultures use comma and/or period among digits for the same purpose).
This extension is backwards compatible, matches with the use of underscore in variable names, and appears in \Index*{Ada} and \Index*{Java} 8.
\CC uses the single quote (©'©) as a separator, restricted within a sequence of digits, \eg ©0xaa©©'©©ff©, ©3.141©©'©©592E1©©'©©1©.


\section{Exponentiation Operator}

C, \CC, and Java (and other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow(x,y)}, to perform the exponentiation operation.
\CFA extends the basic operators with the exponentiation operator ©?©\R{©\\©}©?©\index{?\\?@©?@\@?©} and ©?©\R{©\\©}©=?©\index{?\\=?@©@\@=?©}, as in, ©x ©\R{©\\©}© y© and ©x ©\R{©\\©}©= y©, which means $x^y$ and $x \leftarrow x^y$.
The priority of the exponentiation operator is between the cast and multiplicative operators, so that ©w * (int)x \ (int)y * z© is parenthesized as ©(w * (((int)x) \ ((int)y))) * z©.

There are exponentiation operators for integral and floating types, including the builtin \Index{complex} types.
Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication\footnote{The multiplication computation is $O(\log y)$.} (or shifting if the exponent is 2).
Overflow for a large exponent or negative exponent returns zero.
Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the exponent cannot be negative.
\begin{cfa}
sout | 1 @\@ 0 | 1 @\@ 1 | 2 @\@ 8 | -4 @\@ 3 | 5 @\@ 3 | 5 @\@ 32 | 5L @\@ 32 | 5L @\@ 64 | -4 @\@ -3 | -4.0 @\@ -3 | 4.0 @\@ 2.1
	   | (1.0f+2.0fi) @\@ (3.0f+2.0fi);
1 1 256 -64 125 @0@ 3273344365508751233 @0@ @0@ -0.015625 18.3791736799526 0.264715-1.1922i
\end{cfa}
Note, ©5 \ 32© and ©5L \ 64© overflow, and ©-4 \ -3© is a fraction but stored in an integer so all three computations generate an integral zero.
Because exponentiation has higher priority than ©+©, parenthesis are necessary for exponentiation of \Index{complex constant}s or the expression is parsed as ©1.0f+©\R{©(©}©2.0fi \ 3.0f©\R{©)©}©+2.0fi©, requiring \R{©(©}©1.0f+2.0fi©\R{©)©}© \ ©\R{©(©}©3.0f+2.0fi©\R{©)©}.

The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation version is available.
\begin{cfa}
forall( otype T | { void ?{}( T & this, one_t ); T ?*?( T, T ); } )
T ?@\@?( T ep, unsigned int y );
forall( otype T | { void ?{}( T & this, one_t ); T ?*?( T, T ); } )
T ?@\@?( T ep, unsigned long int y );
\end{cfa}
The user type ©T© must define multiplication, one (©1©), and ©*©.


\section{Control Structures}

\CFA identifies inconsistent, problematic, and missing control structures in C, and extends, modifies, and adds control structures to increase functionality and safety.


%\subsection{\texorpdfstring{\protect\lstinline@if@/\protect\lstinline@while@ Statement}{if Statement}}
\subsection{\texorpdfstring{\LstKeywordStyle{if} / \LstKeywordStyle{while} Statement}{if / while Statement}}

The ©if©/©while© expression allows declarations, similar to ©for© declaration expression.\footnote{
Declarations in the ©do©-©while© condition are not useful because they appear after the loop body.}
\begin{cfa}
if ( @int x = f()@ ) ... $\C{// x != 0}$
if ( @int x = f(), y = g()@ ) ... $\C{// x != 0 \&\& y != 0}$
if ( @int x = f(), y = g(); x < y@ ) ... $\C{// relational expression}$
if ( @struct S { int i; } x = { f() }; x.i < 4@ ) $\C{// relational expression}$

while ( @int x = f()@ ) ... $\C{// x != 0}$
while ( @int x = f(), y = g()@ ) ... $\C{// x != 0 \&\& y != 0}$
while ( @int x = f(), y = g(); x < y@ ) ... $\C{// relational expression}$
while ( @struct S { int i; } x = { f() }; x.i < 4@ ) ... $\C{// relational expression}$
\end{cfa}
Unless a relational expression is specified, each variable is compared not equal to 0, which is the standard semantics for the ©if©/©while© expression, and the results are combined using the logical ©&&© operator.
The scope of the declaration(s) is local to the ©if© statement but exist within both the \emph{then} and \emph{else} clauses.
\CC only provides a single declaration always compared ©!=© to 0.


%\section{\texorpdfstring{\protect\lstinline@case@ Clause}{case Clause}}
\subsection{\texorpdfstring{\LstKeywordStyle{case} Clause}{case Clause}}
\label{s:caseClause}

C restricts the ©case© clause of a ©switch© statement to a single value.
For multiple ©case© clauses associated with the same statement, it is necessary to have multiple ©case© clauses rather than multiple values.
Requiring a ©case© clause for each value does not seem to be in the spirit of brevity normally associated with C.
Therefore, the ©case© clause is extended with a list of values, as in:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}}	\\
\begin{cfa}
switch ( i ) {
  case @1, 3, 5@:
	...
  case @2, 4, 6@:
	...
}
\end{cfa}
&
\begin{cfa}
switch ( i ) {
  case 1: case 3 : case 5:
	...
  case 2: case 4 : case 6:
	...
}
\end{cfa}
&
\begin{cfa}

// odd values

// even values


\end{cfa}
\end{tabular}
\end{cquote}
In addition, subranges are allowed to specify case values.\footnote{
gcc has the same mechanism but awkward syntax, \lstinline@2 ...42@, because a space is required after a number, otherwise the period is a decimal point.}
\begin{cfa}
switch ( i ) {
  case @1~5:@ $\C{// 1, 2, 3, 4, 5}$
	...
  case @10~15:@ $\C{// 10, 11, 12, 13, 14, 15}$
	...
}
\end{cfa}
Lists of subranges are also allowed.
\begin{cfa}
case @1~5, 12~21, 35~42@:
\end{cfa}


%\section{\texorpdfstring{\protect\lstinline@switch@ Statement}{switch Statement}}
\subsection{\texorpdfstring{\LstKeywordStyle{switch} Statement}{switch Statement}}

C allows a number of questionable forms for the ©switch© statement:
\begin{enumerate}
\item
By default, the end of a ©case© clause\footnote{
In this section, the term \emph{case clause} refers to either a ©case© or ©default© clause.}
\emph{falls through} to the next ©case© clause in the ©switch© statement;
to exit a ©switch© statement from a ©case© clause requires explicitly terminating the clause with a transfer statement, most commonly ©break©:
\begin{cfa}
switch ( i ) {
  case 1:
	...
	// fall-through
  case 2:
	...
	break;	// exit switch statement
}
\end{cfa}
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{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\begin{cfa}
switch ( argc ) {
  case 3:
	// open output file
	// fall-through
  case 2:
	// open input file
	break;	// exit switch statement
  default:
	// usage message
}
\end{cfa}
&
\begin{cfa}

if ( argc == 3 ) {
	// open output file
	@// open input file
@} else if ( argc == 2 ) {
	@// open input file (duplicate)

@} else {
	// usage message
}
\end{cfa}
\end{tabular}
\end{cquote}
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.
C also uses fall-through to handle multiple case-values resulting in the same action:
\begin{cfa}
switch ( i ) {
  @case 1: case 3: case 5:@	// odd values
	// odd action
	break;
  @case 2: case 4: case 6:@	// even values
	// even action
	break;
}
\end{cfa}
This situation better handled without fall-through by allowing a list of case values \see{\VRef{s:caseClause}}.
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 most programming languages with a ©switch© statement.
Hence, default fall-through semantics results in a large number of programming errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.

\item
It is possible to place ©case© clauses on statements nested \emph{within} the body of the ©switch© statement:
\begin{cfa}
switch ( i ) {
  case 0:
	if ( j < k ) {
		...
	  @case 1:@		// transfer into "if" statement
		...
	} // if
  case 2:
	while ( j < 5 ) {
		...
	  @case 3:@		// transfer into "while" statement
		...
	} // while
} // switch
\end{cfa}
This usage branches into control structures, which is known to cause both comprehension and technical difficulties.
The comprehension problem results from the inability to determine how control reaches a particular point due to the number of branches leading to it.
The technical problem results from the inability to ensure declaration and initialization of variables when blocks are not entered at the beginning.
There are few arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
Nevertheless, C does have an idiom where this capability is used, known as ``\Index*{Duff's device}''~\cite{Duff83}:
\begin{cfa}
register int n = (count + 7) / 8;
switch ( count % 8 ) {
case 0: do{ *to = *from++;
case 7:		*to = *from++;
case 6:		*to = *from++;
case 5:		*to = *from++;
case 4:		*to = *from++;
case 3:		*to = *from++;
case 2:		*to = *from++;
case 1:		*to = *from++;
		} while ( --n > 0 );
}
\end{cfa}
which unrolls a loop N times (N = 8 above) and uses the ©switch© statement to deal with any iterations not a multiple of N.
While efficient, this sort of special purpose usage is questionable:
\begin{quote}
Disgusting, no? But it compiles and runs just fine. I feel a combination of pride and revulsion at this
discovery.~\cite{Duff83}
\end{quote}
\item
It is possible to place the ©default© clause anywhere in the list of labelled clauses for a ©switch© statement, rather than only at the end.
Most programming languages with a ©switch© statement require the ©default© clause to appear last in the case-clause list.
The logic for this semantics is that after checking all the ©case© clauses without success, the ©default© clause is selected;
hence, physically placing the ©default© clause at the end of the ©case© clause list matches with this semantics.
This physical placement can be compared to the physical placement of an ©else© clause at the end of a series of connected ©if©/©else© statements.

\item
It is possible to place unreachable code at the start of a ©switch© statement, as in:
\begin{cfa}
switch ( x ) {
	@int y = 1;@ $\C{// unreachable initialization}$
	@x = 7;@ $\C{// unreachable code without label/branch}$
  case 0: ...
	...
	@int z = 0;@ $\C{// unreachable initialization, cannot appear after case}$
	z = 2;
  case 1:
	@x = z;@ $\C{// without fall through, z is uninitialized}$
}
\end{cfa}
While the declaration of the local variable ©y© is useful with a scope 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 transferred to using a ©goto©, either from outside or inside of the ©switch©, where both are problematic.
As well, the declaration of ©z© 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.
The key observation is that the ©switch© statement branches into a control structure, \ie there are multiple entry points into its statement body.
\end{enumerate}

Before discussing potential language changes to deal with these problems, it is worth observing that in a typical C program:
\begin{itemize}
\item
the number of ©switch© statements is small,
\item
most ©switch© statements are well formed (\ie no \Index*{Duff's device}),
\item
the ©default© clause is usually written as the last case-clause,
\item
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 put into perspective the \CFA changes to the ©switch©.
\begin{enumerate}
\item
Eliminating default fall-through has the greatest potential for affecting existing code.
However, even if fall-through is removed, most ©switch© statements would continue to work because of the explicit transfers already present at the end of each ©case© clause, the common placement of the ©default© clause at the end of the case list, and the most common use of fall-through, \ie a list of ©case© clauses executing common code, \eg:
\begin{cfa}
case 1:  case 2:  case 3: ...
\end{cfa}
still works.
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 implicit fall-through semantics and an explicit fall-through if the last statement of a case-clause ends with the new keyword ©fallthrough©/©fallthru©, \eg:
\begin{cfa}
@choose@ ( i ) {
  case 1:  case 2:  case 3:
	...
	@// implicit end of switch (break)
  @case 5:
	...
	@fallthru@; $\C{// explicit fall through}$
  case 7:
	...
	@break@ $\C{// explicit end of switch (redundant)}$
  default:
	j = 3;
}
\end{cfa}
Like the ©switch© statement, the ©choose© statement retains the fall-through semantics for a list of ©case© clauses.
An implicit ©break© is applied only at the end of the \emph{statements} following a ©case© clause.
An 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 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 ©switch©/©choose© statement and both declarations and statement are surrounded by a compound statement.} and precluding statements before the first ©case© clause.
Further declarations at the same nesting level as the statement body are disallowed to ensure every transfer into the body is sound.
\begin{cfa}
switch ( x ) {
	@int i = 0;@ $\C{// allowed only at start}$
  case 0:
	...
	@int j = 0;@ $\C{// disallowed}$
  case 1:
	{
		@int k = 0;@ $\C{// allowed at different nesting levels}$
		...
	  @case 2:@ $\C{// disallow case in nested statements}$
	}
  ...
}
\end{cfa}
\end{enumerate}


\subsection{Non-terminating and Labelled \texorpdfstring{\LstKeywordStyle{fallthrough}}{Non-terminating and Labelled fallthrough}}

The ©fallthrough© clause may be non-terminating within a ©case© clause or have a target label to common code from multiple case clauses.
\begin{center}
\begin{tabular}{@{}lll@{}}
\begin{cfa}
choose ( ... ) {
  case 3:
	if ( ... ) {
		... @fallthru;@ // goto case 4
	} else {
		...
	}
	// implicit break
  case 4:




\end{cfa}
&
\begin{cfa}
choose ( ... ) {
  case 3:
	... @fallthrough common;@
  case 4:
	... @fallthrough common;@

  @common:@ // below fallthrough
			  // at case-clause level
	...	// common code for cases 3/4
	// implicit break
  case 4:


\end{cfa}
&
\begin{cfa}
choose ( ... ) {
  case 3:
	choose ( ... ) {
	  case 4:
		for ( ... ) {
			// multi-level transfer
			... @fallthru common;@
		}
		...
	}
	...
  @common:@ // below fallthrough
			  // at case-clause level
\end{cfa}
\end{tabular}
\end{center}
The target label must be below the ©fallthrough© and may not be nested in a control structure, and
the target label must be at the same or higher level as the containing ©case© clause and located at
the same level as a ©case© clause; the target label may be case ©default©, but only associated
with the current ©switch©/©choose© statement.

\begin{figure}
\begin{tabular}{@{}l@{\hspace{25pt}}|l@{}}
\multicolumn{1}{@{}c@{\hspace{25pt}}|}{loop control} & \multicolumn{1}{c@{}}{output} \\
\hline
\begin{cfa}
while @($\,$)@ { sout | "empty"; break; }
do { sout | "empty"; break; } while @($\,$)@;
for @($\,$)@ { sout | "empty"; break; }
for ( @0@ ) { sout | "A"; } sout | "zero";
for ( @1@ ) { sout | "A"; }
for ( @10@ ) { sout | "A"; }
for ( @= 10@ ) { sout | "A"; }
for ( @1 ~= 10 ~ 2@ ) { sout | "B"; }
for ( @10 -~= 1 ~ 2@ ) { sout | "C"; }
for ( @0.5 ~ 5.5@ ) { sout | "D"; }
for ( @5.5 -~ 0.5@ ) { sout | "E"; }
for ( @i; 10@ ) { sout | i; }
for ( @i; = 10@ ) { sout | i; }
for ( @i; 1 ~= 10 ~ 2@ ) { sout | i; }
for ( @i; 10 -~= 1 ~ 2@ ) { sout | i; }
for ( @i; 0.5 ~ 5.5@ ) { sout | i; }
for ( @i; 5.5 -~ 0.5@ ) { sout | i; }
for ( @ui; 2u ~= 10u ~ 2u@ ) { sout | ui; }
for ( @ui; 10u -~= 2u ~ 2u@ ) { sout | ui; }
enum { N = 10 };
for ( @N@ ) { sout | "N"; }
for ( @i; N@ ) { sout | i; }
for ( @i; N -~ 0@ ) { sout | i; }
const int start = 3, comp = 10, inc = 2;
for ( @i; start ~ comp ~ inc + 1@ ) { sout | i; }
for ( i; 1 ~ $\R{@}$ ) { if ( i > 10 ) break; sout | i; }
for ( i; 10 -~ $\R{@}$ ) { if ( i < 0 ) break; sout | i; }
for ( i; 2 ~ $\R{@}$ ~ 2 ) { if ( i > 10 ) break; sout | i; }
for ( i; 2.1 ~ $\R{@}$ ~ $\R{@}$ ) { if ( i > 10.5 ) break; sout | i; i += 1.7; }
for ( i; 10 -~ $\R{@}$ ~ 2 ) { if ( i < 0 ) break; sout | i; }
for ( i; 12.1 ~ $\R{@}$ ~ $\R{@}$ ) { if ( i < 2.5 ) break; sout | i; i -= 1.7; }
for ( i; 5 @:@ j; -5 ~ $@$ ) { sout | i | j; }
for ( i; 5 @:@ j; -5 -~ $@$ ) { sout | i | j; }
for ( i; 5 @:@ j; -5 ~ $@$ ~ 2 ) { sout | i | j; }
for ( i; 5 @:@ j; -5 -~ $@$ ~ 2 ) { sout | i | j; }
for ( i; 5 @:@ j; -5 ~ $@$ ) { sout | i | j; }
for ( i; 5 @:@ j; -5 -~ $@$ ) { sout | i | j; }
for ( i; 5 @:@ j; -5 ~ $@$ ~ 2 ) { sout | i | j; }
for ( i; 5 @:@ j; -5 -~ $@$ ~ 2 ) { sout | i | j; }
for ( i; 5 @:@ j; -5 -~ $@$ ~ 2 @:@ k; 1.5 ~ $@$ ) { sout | i | j | k; }
for ( i; 5 @:@ j; -5 -~ $@$ ~ 2 @:@ k; 1.5 ~ $@$ ) { sout | i | j | k; }
for ( i; 5 @:@ k; 1.5 ~ $@$ @:@ j; -5 -~ $@$ ~ 2 ) { sout | i | j | k; }
\end{cfa}
&
\begin{cfa}
empty
empty
empty
zero
A
A A A A A A A A A A
A A A A A A A A A A A
B B B B B
C C C C C
D D D D D
E E E E E
0 1 2 3 4 5 6 7 8 9
0 1 2 3 4 5 6 7 8 9 10
1 3 5 7 9
10 8 6 4 2
0.5 1.5 2.5 3.5 4.5
5.5 4.5 3.5 2.5 1.5
2 4 6 8 10
10 8 6 4 2

N N N N N N N N N N
0 1 2 3 4 5 6 7 8 9
10 9 8 7 6 5 4 3 2 1

3 6 9
1 2 3 4 5 6 7 8 9 10
10 9 8 7 6 5 4 3 2 1 0
2 4 6 8 10
2.1 3.8 5.5 7.2 8.9
10 8 6 4 2 0
12.1 10.4 8.7 7. 5.3 3.6
0 -5 1 -4 2 -3 3 -2 4 -1
0 -5 1 -6 2 -7 3 -8 4 -9
0 -5 1 -3 2 -1 3 1 4 3
0 -5 1 -7 2 -9 3 -11 4 -13
0 -5 1 -4 2 -3 3 -2 4 -1
0 -5 1 -6 2 -7 3 -8 4 -9
0 -5 1 -3 2 -1 3 1 4 3
0 -5 1 -7 2 -9 3 -11 4 -13
0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
\end{cfa}
\end{tabular}
\caption{Loop Control Examples}
\label{f:LoopControlExamples}
\end{figure}

% for ()  => for ( ;; )
% for ( 10 - t ) => for ( typeof(10 - t) ? = 0 ; ? < 10 - t; ? += 1 ) // using 0 and 1
% for ( i ; 10 - t ) => for ( typeof(10 - t) i = 0 ; i < 10 - t; i += 1 ) // using 0 and 1
% for ( T i ; 10 - t ) => for ( T i = 0 ; i < 10 - t; i += 1 ) // using 0 and 1
% for ( 3~9 ) => for ( int ? = 3 ; ? < 9; ? += 1 ) // using 1
% for ( i ; 3~9 ) => for ( int i = 3 ; i < 9; i += 1 ) // using 1
% for ( T i ; 3~9 ) => for ( T i = 3 ; i < 9; i += 1 ) // using 1


\subsection{Loop Control}

Looping a fixed number of times, possibly with a loop index, occurs frequently.
\CFA condenses simply looping to facilitate coding speed and safety.
The ©for©/©while©/©do-while© loop-control is augmented as follows \see{examples in \VRef[Figure]{f:LoopControlExamples}}:
\begin{itemize}[itemsep=0pt]
\item
©0© is the implicit start value;
\item
©1© is the implicit increment value.
\item
The up-to range uses operator ©+=© for increment;
\item
The down-to range uses operator ©-=© for decrement.
\item
The loop index is polymorphic in the type of the comparison value N (when the start value is implicit) or the start value M.
\begin{cfa}
for ( i; @5@ )					$\C[2.5in]{// typeof(5) i; 5 is comparison value}$
for ( i; @1.5@~5.5~0.5 )		$\C{// typeof(1.5) i; 1.5 is start value}$
\end{cfa}
\item
An empty conditional implies comparison value of ©1© (true).
\begin{cfa}
while ( $\R{/*empty*/}$ )		$\C{// while ( true )}$
for ( $\R{/*empty*/}$ )			$\C{// for ( ; true; )}$
do ... while ( $\R{/*empty*/}$ ) $\C{// do ... while ( true )}$
\end{cfa}
\item
A comparison N is implicit up-to exclusive range [0,N\R{)}.
\begin{cfa}
for ( @5@ )						$\C{// for ( typeof(5) i; i < 5; i += 1 )}$
\end{cfa}
\item
A comparison ©=© N is implicit up-to inclusive range [0,N\R{]}.
\begin{cfa}
for ( @=@5 )					$\C{// for ( typeof(5) i; i <= 5; i += 1 )}$
\end{cfa}
\item
The up-to range M ©~©\index{~@©~©} N means exclusive range [M,N\R{)}.
\begin{cfa}
for ( 1@~@5 )					$\C{// for ( typeof(1) i = 1; i < 5; i += 1 )}$
\end{cfa}
\item
The up-to range M ©~=©\index{~=@©~=©} N means inclusive range [M,N\R{]}.
\begin{cfa}
for ( 1@~=@5 )					$\C{// for ( typeof(1) i = 1; i <= 5; i += 1 )}$
\end{cfa}
\item
The down-to range M ©-~©\index{-~@©-~©} N means exclusive range [N,M\R{)}.
\begin{cfa}
for ( 1@-~@5 )					$\C{// for ( typeof(1) i = 5; i > 0; i -= 1 )}$
\end{cfa}
\item
The down-to range M ©-~=©\index{-~=@©-~=©} N means inclusive range [N,M\R{]}.
\begin{cfa}
for ( 1@-~=@5 )					$\C{// for ( typeof(1) i = 5; i >= 0; i -= 1 )}$
\end{cfa}
\item
©@© means put nothing in this field.
\begin{cfa}
for ( 1~$\R{@}$~2 )				$\C{// for ( typeof(1) i = 1; /*empty*/; i += 2 )}$
\end{cfa}
\item
©:© means start another index.
\begin{cfa}
for ( i; 5 @:@ j; 2~12~3 )		$\C{// for ( typeof(i) i = 1, j = 2; i < 5 \&\& j < 12; i += 1, j += 3 )}\CRT$
\end{cfa}
\end{itemize}


%\subsection{\texorpdfstring{Labelled \protect\lstinline@continue@ / \protect\lstinline@break@}{Labelled continue / break}}
\subsection{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break} Statement}{Labelled continue / break Statement}}

C ©continue© and ©break© statements, for altering control flow, are restricted to one level of nesting for a particular control structure.
This restriction forces programmers to use \Indexc{goto} to achieve the equivalent control-flow for more than one level of nesting.
To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@©continue©!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@©break©!labelled}\index{labelled!break@©break©} with a target label to support static multi-level exit\index{multi-level exit}\index{static multi-level exit}~\cite{Buhr85}, as in Java.
For both ©continue© and ©break©, the target label must be directly associated with a ©for©, ©while© or ©do© statement;
for ©break©, the target label can also be associated with a ©switch©, ©if© or compound (©{}©) statement.
\VRef[Figure]{f:MultiLevelExit} shows a comparison between labelled ©continue© and ©break© and the corresponding C equivalent using ©goto© and labels.
The innermost loop has 8 exit points, which cause continuation or termination of one or more of the 7 \Index{nested control-structure}s.

\begin{figure}
\centering
\begin{lrbox}{\myboxA}
\begin{cfa}[tabsize=3]
@Compound:@ {
	@Try:@ try {
		@For:@ for ( ... ) {
			@While:@ while ( ... ) {
				@Do:@ do {
					@If:@ if ( ... ) {
						@Switch:@ switch ( ... ) {
							case 3:
								@break Compound@;
								@break Try@;
								@break For@;      /* or */  @continue For@;
								@break While@;  /* or */  @continue While@;
								@break Do@;      /* or */  @continue Do@;
								@break If@;
								@break Switch@;
							} // switch
						} else {
							... @break If@; ...	// terminate if
						} // if
				} while ( ... ); // do
			} // while
		} // for
	} @finally@ { // always executed
	} // try
} // compound
\end{cfa}
\end{lrbox}

\begin{lrbox}{\myboxB}
\begin{cfa}[tabsize=3]
{

		@ForC:@ for ( ... ) {
			@WhileC:@ while ( ... ) {
				@DoC:@ do {
					if ( ... ) {
						switch ( ... ) {
							case 3:
								@goto Compound@;
								@goto Try@;
								@goto ForB@;      /* or */  @goto ForC@;
								@goto WhileB@;  /* or */  @goto WhileC@;
								@goto DoB@;      /* or */  @goto DoC@;
								@goto If@;
								@goto Switch@;
							} @Switch:@ ;
						} else {
							... @goto If@; ...	// terminate if
						} @If:@;
				} while ( ... ); @DoB:@ ;
			} @WhileB:@ ;
		} @ForB:@ ;


} @Compound:@ ;
\end{cfa}
\end{lrbox}

\subfloat[\CFA]{\label{f:CFibonacci}\usebox\myboxA}
\hspace{3pt}
\vrule
\hspace{3pt}
\subfloat[C]{\label{f:CFAFibonacciGen}\usebox\myboxB}
\caption{Multi-level Exit}
\label{f:MultiLevelExit}
\end{figure}

Both labelled ©continue© and ©break© are a ©goto©\index{goto@©goto©!restricted} restricted in the following ways:
\begin{itemize}
\item
They cannot create a loop, which means only the looping constructs cause looping.
This restriction means all situations resulting in repeated execution are clearly delineated.
\item
They cannot branch into a control structure.
This restriction prevents missing declarations and/or initializations at the start of a control structure resulting in undefined behaviour.
\end{itemize}
The advantage of the labelled ©continue©/©break© is allowing static multi-level exits without having to use the ©goto© statement, and tying control flow to the target control structure rather than an arbitrary point in a program via a label.
Furthermore, the location of the label at the \emph{beginning} of the target control structure informs the reader (\Index{eye candy}) that complex control-flow is occurring in the body of the control structure.
With ©goto©, the label is at the end of the control structure, which fails to convey this important clue early enough to the reader.
Finally, using an explicit target for the transfer instead of an implicit target allows new constructs to be added or removed without affecting existing constructs.
Otherwise, the implicit targets of the current ©continue© and ©break©, \ie the closest enclosing loop or ©switch©, change as certain constructs are added or removed.


%\subsection{\texorpdfstring{\protect\lstinline@with@ Statement}{with Statement}}
\subsection{\texorpdfstring{\LstKeywordStyle{with} Statement}{with Statement}}
\label{s:WithStatement}

Grouping heterogeneous data into an \newterm{aggregate} (structure/union) is a common programming practice, and aggregates may be nested:
\begin{cfa}
struct Person {								$\C{// aggregate}$
	struct Name { char first[20], last[20]; } name $\C{// nesting}$
	struct Address { ... } address			$\C{// nesting}$
	int sex;
};
\end{cfa}
Functions manipulating aggregates must repeat the aggregate name to access its containing fields.
\begin{cfa}
Person p
@p.@name; @p.@address; @p.@sex; $\C{// access containing fields}$
\end{cfa}
which extends to multiple levels of qualification for nested aggregates and multiple aggregates.
\begin{cfa}
struct Ticket { ... } t;
@p.name@.first; @p.address@.street;		$\C{// access nested fields}$
@t.@departure; @t.@cost;				$\C{// access multiple aggregate}$
\end{cfa}
Repeated aggregate qualification is tedious and makes code difficult to read.
Therefore, reducing aggregate qualification is a useful language design goal.

C allows unnamed nested aggregates that open their scope into the containing aggregate.
This feature is used to group fields for attributes and/or with ©union© aggregates.
\begin{cfa}
struct S {
	struct { int g,  h; } __attribute__(( aligned(64) ));
	int tag;
	union {
		struct { char c1,  c2; } __attribute__(( aligned(128) ));
		struct { int i1,  i2; };
		struct { double d1,  d2; };
	};
};
s.g; s.h; s.tag; s.c1; s.c2; s.i1; s.i2; s.d1; s.d2;
\end{cfa}

Object-oriented languages reduce qualification for class variables within member functions, \eg \CC:
\begin{C++}
struct S {
	char @c@;   int @i@;   double @d@;
	void f( /* S * this */ ) {				$\C{// implicit ``this'' parameter}$
		@c@;   @i@;   @d@;					$\C{// this->c; this->i; this->d;}$
	}
}
\end{C++}
In general, qualification is elided for the variables and functions in the lexical scopes visible from a member function.
However, qualification is necessary for name shadowing and explicit aggregate parameters. 
\begin{cfa}
struct T {
	char @m@;   int @i@;   double @n@;		$\C{// derived class variables}$
};
struct S : public T {
	char @c@;   int @i@;   double @d@;		$\C{// class variables}$
	void g( double @d@, T & t ) {
		d;   @t@.m;   @t@.i;   @t@.n;		$\C{// function parameter}$
		c;   i;   @this->@d;   @S::@d;		$\C{// class S variables}$
		m;   @T::@i;   n;					$\C{// class T variables}$
	}
};
\end{cfa}
Note the three different forms of qualification syntax in \CC, ©.©, ©->©, ©::©, which is confusing.

Since \CFA in not object-oriented, it has no implicit parameter with its implicit qualification.
Instead \CFA introduces a general mechanism using the ©with© statement \see{Pascal~\cite[\S~4.F]{Pascal}} to explicitly elide aggregate qualification by opening a scope containing the field identifiers.
Hence, the qualified fields become variables with the side-effect that it is simpler to write, easier to read, and optimize field references in a block.
\begin{cfa}
void f( S & this ) @with ( this )@ {		$\C{// with statement}$
	@c@;   @i@;   @d@;						$\C{// this.c, this.i, this.d}$
}
\end{cfa}
with the generality of opening multiple aggregate-parameters:
\begin{cfa}
void g( S & s, T & t ) @with ( s, t )@ {	$\C{// multiple aggregate parameters}$
	c;   @s.@i;   d;						$\C{// s.c, s.i, s.d}$
	m;   @t.@i;   n;						$\C{// t.m, t.i, t.n}$
}
\end{cfa}
where qualification is only necessary to disambiguate the shadowed variable ©i©.

In detail, the ©with© statement may appear as the body of a function or nested within a function body.
The ©with© clause takes a list of expressions, where each expression provides an aggregate type and object.
(Enumerations are already opened.)
To open a pointer type, the pointer must be dereferenced to obtain a reference to the aggregate type.
\begin{cfa}
S * sp;
with ( *sp ) { ... }
\end{cfa}
The expression object is the implicit qualifier for the open structure-fields.
\CFA's ability to overload variables \see{\VRef{s:VariableOverload}} and use the left-side of assignment in type resolution means most fields with the same name but different types are automatically disambiguated, eliminating qualification.
All expressions in the expression list are open in parallel within the compound statement.
This semantic is different from Pascal, which nests the openings from left to right.
The difference between parallel and nesting occurs for fields with the same name and type:
\begin{cfa}
struct Q { int @i@; int k; int @m@; } q, w;
struct R { int @i@; int j; double @m@; } r, w;
with ( r, q ) {
	j + k;									$\C{// unambiguous, r.j + q.k}$
	m = 5.0;								$\C{// unambiguous, q.m = 5.0}$
	m = 1;									$\C{// unambiguous, r.m = 1}$
	int a = m;								$\C{// unambiguous, a = r.i }$
	double b = m;							$\C{// unambiguous, b = q.m}$
	int c = r.i + q.i;						$\C{// disambiguate with qualification}$
	(double)m;								$\C{// disambiguate with cast}$
}
\end{cfa}
For parallel semantics, both ©r.i© and ©q.i© are visible, so ©i© is ambiguous without qualification;
for nested semantics, ©q.i© hides ©r.i©, so ©i© implies ©q.i©.
Pascal nested-semantics is possible by nesting ©with© statements.
\begin{cfa}
with ( r ) {
	i;										$\C{// unambiguous, r.i}$
	with ( q ) {
		i;									$\C{// unambiguous, q.i}$
	}
}
\end{cfa}
A cast or qualification can be used to disambiguate variables within a ©with© \emph{statement}.
A cast can be used to disambiguate among overload variables in a ©with© \emph{expression}:
\begin{cfa}
with ( w ) { ... }							$\C{// ambiguous, same name and no context}$
with ( (Q)w ) { ... }						$\C{// unambiguous, cast}$
\end{cfa}
Because there is no left-side in the ©with© expression to implicitly disambiguate between the ©w© variables, it is necessary to explicitly disambiguate by casting ©w© to type ©Q© or ©R©.

Finally, there is an interesting problem between parameters and the function-body ©with©, \eg:
\begin{cfa}
void ?{}( S & s, int i ) with ( s ) { $\C{// constructor}$
	@s.i = i;@  j = 3;  m = 5.5; $\C{// initialize fields}$
}
\end{cfa}
Here, the assignment ©s.i = i© means ©s.i = s.i©, which is meaningless, and there is no mechanism to qualify the parameter ©i©, making the assignment impossible using the function-body ©with©.
To solve this problem, parameters are treated like an initialized aggregate:
\begin{cfa}
struct Params {
	S & s;
	int i;
} params;
\end{cfa}
and implicitly opened \emph{after} a function-body open, to give them higher priority:
\begin{cfa}
void ?{}( S & s, int @i@ ) with ( s ) @with( $\emph{\R{params}}$ )@ { // syntax not allowed, illustration only
	s.i = @i@; j = 3; m = 5.5;
}
\end{cfa}
This implicit semantic matches with programmer expectation.



\section{Exception Handling}
\label{s:ExceptionHandling}

Exception handling provides two mechanism: change of control flow from a raise to a handler, and communication from the raise to the handler.
Transfer of control can be local, within a routine, or non-local, among routines.
Non-local transfer can cause stack unwinding, \ie non-local routine termination, depending on the kind of raise.
\begin{cfa}
exception_t E {}; $\C{// exception type}$
void f(...) {
	... throw E{}; ... $\C{// termination}$
	... throwResume E{}; ... $\C{// resumption}$
}
try {
	f(...);
} catch( E e ; $boolean-predicate$ ) {		$\C{// termination handler}$
	// recover and continue
} catchResume( E e ; $boolean-predicate$ ) { $\C{// resumption handler}$
	// repair and return
} finally {
	// always executed
}
\end{cfa}
The kind of raise and handler match: ©throw© with ©catch© and ©throwResume© with ©catchResume©.
Then the exception type must match along with any additional predicate must be true.
The ©catch© and ©catchResume© handlers may appear in any oder.
However, the ©finally© clause must appear at the end of the ©try© statement.


\subsection{Exception Hierarchy}

An exception type can be derived from another exception type, just like deriving a subclass from a class, providing a kind of polymorphism among exception types.
The exception-type hierarchy that is created is used to organize exception types, similar to a class hierarchy in object-oriented languages, \eg:
\begin{center}
\input{EHMHierarchy}
\end{center}
A programmer can then choose to handle an exception at different degrees of specificity along the hierarchy;
derived exception-types support a more flexible programming style.
For example, higher-level code should catch general exceptions to reduce coupling to the specific implementation at the lower levels;
unnecessary coupling may force changes in higher-level code when low-level code changes.
A consequence of derived exception-types is that multiple exceptions may match, \eg:
\begin{cfa}
catch( Arithmetic )
\end{cfa}
matches all three derived exception-types: ©DivideByZero©, ©Overflow©, and ©Underflow©.
Because the propagation mechanisms perform a simple linear search of the handler clause for a guarded block, and selects the first matching handler, the order of catch clauses in the handler clause becomes important, \eg:
\begin{cfa}
try {
	...
} catch( Overflow ) {	// must appear first
	// handle overflow
} catch( Arithmetic )
	// handle other arithmetic issues
}
\end{cfa}
\newterm{Multiple derivation} among exception is not supported.


\section{Alternative Declarations}
\label{s:AlternativeDeclarations}

C declaration syntax is notoriously confusing and error prone.
For example, many C programmers are confused by a declaration as simple as:
\begin{cquote}
\begin{tabular}{@{}ll@{}}
\begin{cfa}
int * x[5]
\end{cfa}
&
\raisebox{-0.75\totalheight}{\input{Cdecl}}
\end{tabular}
\end{cquote}
Is this an array of 5 pointers to integers or a \Index{pointer} to an array of 5 integers?
If there is any doubt, it implies \Index{productivity} and \Index{safety} issues even for basic programs.
Another example of confusion results from the fact that a routine name and its parameters are embedded within the return type, mimicking the way the return value is used at the routine's call site.
For example, a routine returning a \Index{pointer} to an array of integers is defined and used in the following way:
\begin{cfa}
int @(*@f@())[@5@]@ {...}; $\C{// definition}$
 ... @(*@f@())[@3@]@ += 1; $\C{// usage}$
\end{cfa}
Essentially, the return type is wrapped around the routine name in successive layers (like an \Index{onion}).
While attempting to make the two contexts consistent is a laudable goal, it has not worked out in practice, even though Dennis Richie believed otherwise:
\begin{quote}
In spite of its difficulties, I believe that the C's approach to declarations remains plausible, and am comfortable with it; it is a useful unifying principle.~\cite[p.~12]{Ritchie93}
\end{quote}

\CFA provides its own type, variable and routine declarations, using a different syntax.
The new declarations place qualifiers to the left of the base type, while C declarations place qualifiers to the right of the base type.
In the following example, \R{red} is the base type and \B{blue} is qualifiers.
The \CFA declarations move the qualifiers to the left of the base type, \ie move the blue to the left of the red, while the qualifiers have the same meaning but are ordered left to right to specify a variable's type.
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{C}}	\\
\begin{cfa}[moredelim={**[is][\color{blue}]{\#}{\#}}]
#[5] *# @int@ x1;
#* [5]# @int@ x2;
#[* [5] int]# f@( int p )@;
\end{cfa}
&
\begin{cfa}[moredelim={**[is][\color{blue}]{\#}{\#}}]
@int@ #*# x1 #[5]#;
@int@ #(*#x2#)[5]#;
#int (*#f@( int p )@#)[5]#;
\end{cfa}
\end{tabular}
\end{cquote}
The only exception is \Index{bit field} specification, which always appear to the right of the base type.
% Specifically, the character ©*© is used to indicate a pointer, square brackets ©[©\,©]© are used to represent an array or function return value, and parentheses ©()© are used to indicate a routine parameter.
However, unlike C, \CFA type declaration tokens are distributed across all variables in the declaration list.
For instance, variables ©x© and ©y© of type \Index{pointer} to integer are defined in \CFA as follows:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{C}}	\\
\begin{cfa}
@*@ int x, y;
\end{cfa}
&
\begin{cfa}
int @*@x, @*@y;
\end{cfa}
\end{tabular}
\end{cquote}
The downside of this semantics is the need to separate regular and \Index{pointer} declarations:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{C}}	\\
\begin{cfa}
@*@ int x;
int y;
\end{cfa}
&
\begin{cfa}
int @*@x, y;

\end{cfa}
\end{tabular}
\end{cquote}
which is \Index{prescribing} a safety benefit.
Other examples are:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}}	\\
\begin{cfa}
[ 5 ] int z;
[ 5 ] * char w;
* [ 5 ] double v;
struct s {
	int f0:3;
	* int f1;
	[ 5 ] * int f2;
};
\end{cfa}
&
\begin{cfa}
int z[ 5 ];
char * w[ 5 ];
double (* v)[ 5 ];
struct s {
	int f0:3;
	int * f1;
	int * f2[ 5 ]
};
\end{cfa}
&
\begin{cfa}
// array of 5 integers
// array of 5 pointers to char
// pointer to array of 5 doubles

// common bit field syntax



\end{cfa}
\end{tabular}
\end{cquote}

All type qualifiers, \eg ©const©, ©volatile©, etc., are used in the normal way with the new declarations and also appear left to right, \eg:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
\multicolumn{1}{c@{\hspace{1em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{1em}}}{\textbf{C}}	\\
\begin{cfa}
const * const int x;
const * [ 5 ] const int y;
\end{cfa}
&
\begin{cfa}
int const * const x;
const int (* const y)[ 5 ]
\end{cfa}
&
\begin{cfa}
// const pointer to const integer
// const pointer to array of 5 const integers
\end{cfa}
\end{tabular}
\end{cquote}
All declaration qualifiers, \eg ©extern©, ©static©, etc., are used in the normal way with the new declarations but can only appear at the start of a \CFA routine declaration,\footnote{\label{StorageClassSpecifier}
The placement of a storage-class specifier other than at the beginning of the declaration specifiers in a declaration is an obsolescent feature.~\cite[\S~6.11.5(1)]{C11}} \eg:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}}	\\
\begin{cfa}
extern [ 5 ] int x;
static * const int y;
\end{cfa}
&
\begin{cfa}
int extern x[ 5 ];
const int static * y;
\end{cfa}
&
\begin{cfa}
// externally visible array of 5 integers
// internally visible pointer to constant int
\end{cfa}
\end{tabular}
\end{cquote}

The new declaration syntax can be used in other contexts where types are required, \eg casts and the pseudo-routine ©sizeof©:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{C}}	\\
\begin{cfa}
y = (* int)x;
i = sizeof([ 5 ] * int);
\end{cfa}
&
\begin{cfa}
y = (int *)x;
i = sizeof(int * [ 5 ]);
\end{cfa}
\end{tabular}
\end{cquote}

Finally, new \CFA declarations may appear together with C declarations in the same program block, but cannot be mixed within a specific declaration.
Therefore, a programmer has the option of either continuing to use traditional C declarations or take advantage of the new style.
Clearly, both styles need to be supported for some time due to existing C-style header-files, particularly for UNIX-like systems.


\section{Pointer / Reference}
\label{s:PointerReference}

C provides a \newterm{pointer type};
\CFA adds a \newterm{reference type}.
These types may be derived from an object or routine type, called the \newterm{referenced type}.
Objects of these types contain an \newterm{address}, which is normally a location in memory, but may also address memory-mapped registers in hardware devices.
An integer constant expression with the value 0, or such an expression cast to type ©void *©, is called a \newterm{null-pointer constant}.\footnote{
One way to conceptualize the null pointer is that no variable is placed at this address, so the null-pointer address can be used to denote an uninitialized pointer/reference object;
\ie the null pointer is guaranteed to compare unequal to a pointer to any object or routine.
In general, a value with special meaning among a set of values is called a \emph{\Index{sentinel value}}, \eg ©-1© as a return code value.}
An address is \newterm{sound}, if it points to a valid memory location in scope, \ie within the program's execution-environment and has not been freed.
Dereferencing an \newterm{unsound} address, including the null pointer, is \Index{undefined}, often resulting in a \Index{memory fault}.

A program \newterm{object} is a region of data storage in the execution environment, the contents of which can represent values.
In most cases, objects are located in memory at an address, and the variable name for an object is an implicit address to the object generated by the compiler and automatically dereferenced, as in:
\begin{cquote}
\begin{tabular}{@{}ll@{\hspace{2em}}l@{}}
\begin{cfa}
int x;
x = 3;
int y;
y = x;
\end{cfa}
&
\raisebox{-0.45\totalheight}{\input{pointer1}}
&
\begin{cfa}
int * @const@ x = (int *)100
*x = 3;			// implicit dereference
int * @const@ y = (int *)104;
*y = *x;			// implicit dereference
\end{cfa}
\end{tabular}
\end{cquote}
where the right example is how the compiler logically interprets the variables in the left example.
Since a variable name only points to one address during its lifetime, it is an \Index{immutable} \Index{pointer};
hence, the implicit type of pointer variables ©x© and ©y© are constant pointers in the compiler interpretation.
In general, variable addresses are stored in instructions instead of loaded from memory, and hence may not occupy storage.
These approaches are contrasted in the following:
\begin{cquote}
\begin{tabular}{@{}l|l@{}}
\multicolumn{1}{c|}{explicit variable address} & \multicolumn{1}{c}{implicit variable address} \\
\hline
\begin{cfa}
lda		r1,100   // load address of x
ld		 r2,(r1)   // load value of x
lda		r3,104   // load address of y
st		 r2,(r3)   // store x into y
\end{cfa}
&
\begin{cfa}

ld		r2,(100)   // load value of x

st		r2,(104)   // store x into y
\end{cfa}
\end{tabular}
\end{cquote}
Finally, the immutable nature of a variable's address and the fact that there is no storage for the variable pointer means pointer assignment\index{pointer!assignment}\index{assignment!pointer} is impossible.
Therefore, the expression ©x = y© has only one meaning, ©*x = *y©, \ie manipulate values, which is why explicitly writing the dereferences is unnecessary even though it occurs implicitly as part of \Index{instruction decoding}.

A \Index{pointer}/\Index{reference} object is a generalization of an object variable-name, \ie a mutable address that can point to more than one memory location during its lifetime.
(Similarly, an integer variable can contain multiple integer literals during its lifetime versus an integer constant representing a single literal during its lifetime, and like a variable name, may not occupy storage if the literal is embedded directly into instructions.)
Hence, a pointer occupies memory to store its current address, and the pointer's value is loaded by dereferencing, \eg:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{2em}}l@{}}
\begin{cfa}
int x, y, @*@ p1, @*@ p2, @**@ p3;
p1 = @&@x;     // p1 points to x
p2 = p1;     // p2 points to x
p1 = @&@y;     // p1 points to y
p3 = &p2;  // p3 points to p2
\end{cfa}
&
\raisebox{-0.5\totalheight}{\input{pointer2.pstex_t}}
\end{tabular}
\end{cquote}

Notice, an address has a \Index{duality}\index{address!duality}: a location in memory or the value at that location.
In many cases, a compiler might be able to infer the best meaning for these two cases.
For example, \Index*{Algol68}~\cite{Algol68} infers pointer dereferencing to select the best meaning for each pointer usage
\begin{cfa}
p2 = p1 + x; $\C{// compiler infers *p2 = *p1 + x;}$
\end{cfa}
Algol68 infers the following dereferencing ©*p2 = *p1 + x©, because adding the arbitrary integer value in ©x© to the address of ©p1© and storing the resulting address into ©p2© is an unlikely operation.
Unfortunately, automatic dereferencing does not work in all cases, and so some mechanism is necessary to fix incorrect choices.

Rather than inferring dereference, most programming languages pick one implicit dereferencing semantics, and the programmer explicitly indicates the other to resolve address-duality.
In C, objects of pointer type always manipulate the pointer object's address:
\begin{cfa}
p1 = p2; $\C{// p1 = p2\ \ rather than\ \ *p1 = *p2}$
p2 = p1 + x; $\C{// p2 = p1 + x\ \ rather than\ \ *p2 = *p1 + x}$
\end{cfa}
even though the assignment to ©p2© is likely incorrect, and the programmer probably meant:
\begin{cfa}
p1 = p2; $\C{// pointer address assignment}$
@*@p2 = @*@p1 + x; $\C{// pointed-to value assignment / operation}$
\end{cfa}
The C semantics work well for situations where manipulation of addresses is the primary meaning and data is rarely accessed, such as storage management (©malloc©/©free©).

However, in most other situations, the pointed-to value is requested more often than the pointer address.
\begin{cfa}
*p2 = ((*p1 + *p2) * (**p3 - *p1)) / (**p3 - 15);
\end{cfa}
In this case, it is tedious to explicitly write the dereferencing, and error prone when pointer arithmetic is allowed.
It is better to have the compiler generate the dereferencing and have no implicit pointer arithmetic:
\begin{cfa}
p2 = ((p1 + p2) * (p3 - p1)) / (p3 - 15);
\end{cfa}

To support this common case, a reference type is introduced in \CFA, denoted by ©&©, which is the opposite dereference semantics to a pointer type, making the value at the pointed-to location the implicit semantics for dereferencing (similar but not the same as \CC \Index{reference type}s).
\begin{cfa}
int x, y, @&@ r1, @&@ r2, @&&@ r3;
@&@r1 = &x; $\C{// r1 points to x}$
@&@r2 = &r1; $\C{// r2 points to x}$
@&@r1 = &y; $\C{// r1 points to y}$
@&&@r3 = @&@&r2; $\C{// r3 points to r2}$
r2 = ((r1 + r2) * (r3 - r1)) / (r3 - 15); $\C{// implicit dereferencing}$
\end{cfa}
Except for auto-dereferencing by the compiler, this reference example is the same as the previous pointer example.
Hence, a reference behaves like the variable name for the current variable it is pointing-to.
One way to conceptualize a reference is via a rewrite rule, where the compiler inserts a dereference operator before the reference variable for each reference qualifier in a declaration, so the previous example becomes:
\begin{cfa}
@*@r2 = ((@*@r1 + @*@r2) @*@ (@**@r3 - @*@r1)) / (@**@r3 - 15);
\end{cfa}
When a reference operation appears beside a dereference operation, \eg ©&*©, they cancel out.
However, in C, the cancellation always yields a value (\Index{rvalue}).\footnote{
The unary ©&© operator yields the address of its operand.
If the operand has type ``type'', the result has type ``pointer to type''.
If the operand is the result of a unary ©*© operator, neither that operator nor the ©&© operator is evaluated and the result is as if both were omitted, except that the constraints on the operators still apply and the result is not an lvalue.~\cite[\S~6.5.3.2--3]{C11}}
For a \CFA reference type, the cancellation on the left-hand side of assignment leaves the reference as an address (\Index{lvalue}):
\begin{cfa}
(&@*@)r1 = &x; $\C{// (\&*) cancel giving address in r1 not variable pointed-to by r1}$
\end{cfa}
Similarly, the address of a reference can be obtained for assignment or computation (\Index{rvalue}):
\begin{cfa}
(&(&@*@)@*@)r3 = &(&@*@)r2; $\C{// (\&*) cancel giving address in r2, (\&(\&*)*) cancel giving address in r3}$
\end{cfa}
Cancellation\index{cancellation!pointer/reference}\index{pointer!cancellation} works to arbitrary depth.

Fundamentally, pointer and reference objects are functionally interchangeable because both contain addresses.
\begin{cfa}
int x, *p1 = &x, **p2 = &p1, ***p3 = &p2,
		 &r1 = x,    &&r2 = r1,   &&&r3 = r2;
***p3 = 3; $\C{// change x}$
r3 = 3; $\C{// change x, ***r3}$
**p3 = ...; $\C{// change p1}$
&r3 = ...; $\C{// change r1, (\&*)**r3, 1 cancellation}$
*p3 = ...; $\C{// change p2}$
&&r3 = ...; $\C{// change r2, (\&(\&*)*)*r3, 2 cancellations}$
&&&r3 = p3; $\C{// change r3 to p3, (\&(\&(\&*)*)*)r3, 3 cancellations}$
\end{cfa}
Furthermore, both types are equally performant, as the same amount of dereferencing occurs for both types.
Therefore, the choice between them is based solely on whether the address is dereferenced frequently or infrequently, which dictates the amount of implicit dereferencing aid from the compiler.

As for a pointer type, a reference type may have qualifiers:
\begin{cfa}
const int cx = 5; $\C{// cannot change cx;}$
const int & cr = cx; $\C{// cannot change what cr points to}$
@&@cr = &cx; $\C{// can change cr}$
cr = 7; $\C{// error, cannot change cx}$
int & const rc = x; $\C{// must be initialized}$
@&@rc = &x; $\C{// error, cannot change rc}$
const int & const crc = cx; $\C{// must be initialized}$
crc = 7; $\C{// error, cannot change cx}$
@&@crc = &cx; $\C{// error, cannot change crc}$
\end{cfa}
Hence, for type ©& const©, there is no pointer assignment, so ©&rc = &x© is disallowed, and \emph{the address value cannot be the null pointer unless an arbitrary pointer is coerced\index{coercion} into the reference}:
\begin{cfa}
int & const cr = *0; $\C{// where 0 is the int * zero}$
\end{cfa}
Note, constant reference-types do not prevent \Index{addressing errors} because of explicit storage-management:
\begin{cfa}
int & const cr = *malloc();
cr = 5;
free( &cr );
cr = 7; $\C{// unsound pointer dereference}$
\end{cfa}

The position of the ©const© qualifier \emph{after} the pointer/reference qualifier causes confuse for C programmers.
The ©const© qualifier cannot be moved before the pointer/reference qualifier for C style-declarations;
\CFA-style declarations \see{\VRef{s:AlternativeDeclarations}} attempt to address this issue:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}	& \multicolumn{1}{c}{\textbf{C}}	\\
\begin{cfa}
@const@ * @const@ * const int ccp;
@const@ & @const@ & const int ccr;
\end{cfa}
&
\begin{cfa}
const int * @const@ * @const@ ccp;

\end{cfa}
\end{tabular}
\end{cquote}
where the \CFA declaration is read left-to-right.

Finally, like pointers, references are usable and composable with other type operators and generators.
\begin{cfa}
int w, x, y, z, & ar[3] = { x, y, z }; $\C{// initialize array of references}$
&ar[1] = &w; $\C{// change reference array element}$
typeof( ar[1] ) p; $\C{// (gcc) is int, \ie the type of referenced object}$
typeof( &ar[1] ) q; $\C{// (gcc) is int \&, \ie the type of reference}$
sizeof( ar[1] ) == sizeof( int ); $\C{// is true, \ie the size of referenced object}$
sizeof( &ar[1] ) == sizeof( int *) $\C{// is true, \ie the size of a reference}$
\end{cfa}

In contrast to \CFA reference types, \Index*[C++]{\CC{}}'s reference types are all ©const© references, preventing changes to the reference address, so only value assignment is possible, which eliminates half of the \Index{address duality}.
Also, \CC does not allow \Index{array}s\index{array!reference} of reference\footnote{
The reason for disallowing arrays of reference is unknown, but possibly comes from references being ethereal (like a textual macro), and hence, replaceable by the referent object.}
\Index*{Java}'s reference types to objects (all Java objects are on the heap) are like C pointers, which always manipulate the address, and there is no (bit-wise) object assignment, so objects are explicitly cloned by shallow or deep copying, which eliminates half of the address duality.


\subsection{Initialization}

\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.
There are three initialization contexts in \CFA: declaration initialization, argument/parameter binding, return/temporary binding.
Because the object being initialized has no value, there is only one meaningful semantics with respect to address duality: it must mean address as there is no pointed-to value.
In contrast, the left-hand side of assignment has an address that has a duality.
Therefore, for pointer/reference initialization, the initializing value must be an address not a value.
\begin{cfa}
int * p = &x; $\C{// assign address of x}$
@int * p = x;@ $\C{// assign value of x}$
int & r = x; $\C{// must have address of x}$
\end{cfa}
Like the previous example with C pointer-arithmetic, it is unlikely assigning the value of ©x© into a pointer is meaningful (again, a warning is usually given).
Therefore, for safety, this context requires an address, so it is superfluous to require explicitly taking the address of the initialization object, even though the type is incorrect.
Note, this is strictly a convenience and safety feature for a programmer.
Hence, \CFA allows ©r© to be assigned ©x© because it infers a reference for ©x©, by implicitly inserting a address-of operator, ©&©, and it is an error to put an ©&© because the types no longer match due to the implicit dereference.
Unfortunately, C allows ©p© to be assigned with ©&x© (address) or ©x© (value), but most compilers warn about the latter assignment as being potentially incorrect.
Similarly, when a reference type is used for a parameter/return type, the call-site argument does not require a reference operator for the same reason.
\begin{cfa}
int & f( int & r ); $\C{// reference parameter and return}$
z = f( x ) + f( y ); $\C{// reference operator added, temporaries needed for call results}$
\end{cfa}
Within routine ©f©, it is possible to change the argument by changing the corresponding parameter, and parameter ©r© can be locally reassigned within ©f©.
Since operator routine ©?+?© 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.
\begin{cfa}
int temp1 = f( x ), temp2 = f( y );
z = temp1 + temp2;
\end{cfa}
This \Index{implicit referencing} is crucial for reducing the syntactic burden for programmers when using references;
otherwise references have the same syntactic  burden as pointers in these contexts.

When a pointer/reference parameter has a ©const© value (immutable), it is possible to pass literals and expressions.
\begin{cfa}
void f( @const@ int & cr );
void g( @const@ int * cp );
f( 3 );			  g( @&@3 );
f( x + y );		g( @&@(x + y) );
\end{cfa}
Here, the compiler passes the address to the literal 3 or the temporary for the expression ©x + y©, knowing the argument cannot be changed through the parameter.
The ©&© before the constant/expression for the pointer-type parameter (©g©) is a \CFA extension necessary to type match and is a common requirement before a variable in C (\eg ©scanf©).
Importantly, ©&3© may not be equal to ©&3©, where the references occur across calls because the temporaries maybe different on each call.

\CFA \emph{extends} this semantics to a mutable pointer/reference parameter, and the compiler implicitly creates the necessary temporary (copying the argument), which is subsequently pointed-to by the reference parameter and can be changed.\footnote{
If whole program analysis is possible, and shows the parameter is not assigned, \ie it is ©const©, the temporary is unnecessary.}
\begin{cfa}
void f( int & r );
void g( int * p );
f( 3 );			  g( @&@3 ); $\C{// compiler implicit generates temporaries}$
f( x + y );		g( @&@(x + y) ); $\C{// compiler implicit generates temporaries}$
\end{cfa}
Essentially, there is an implicit \Index{rvalue} to \Index{lvalue} conversion in this case.\footnote{
This conversion attempts to address the \newterm{const hell} problem, when the innocent addition of a ©const© qualifier causes a cascade of type failures, requiring an unknown number of additional ©const© qualifiers, until it is discovered a ©const© qualifier cannot be added and all the ©const© qualifiers must be removed.}
The implicit conversion allows seamless calls to any routine without having to explicitly name/copy the literal/expression to allow the call.

%\CFA attempts to handle pointers and references in a uniform, symmetric manner.
Finally, C handles \Index{routine object}s in an inconsistent way.
A routine object is both a pointer and a reference (\Index{particle and wave}).
\begin{cfa}
void f( int i );
void (* fp)( int ); $\C{// routine pointer}$
fp = f; $\C{// reference initialization}$
fp = &f; $\C{// pointer initialization}$
fp = *f; $\C{// reference initialization}$
fp(3); $\C{// reference invocation}$
(*fp)(3); $\C{// pointer invocation}$
\end{cfa}
While C's treatment of routine objects has similarity to inferring a reference type in initialization contexts, the examples are assignment not initialization, and all possible forms of assignment are possible (©f©, ©&f©, ©*f©) without regard for type.
Instead, a routine object should be referenced by a ©const© reference:
\begin{cfa}
@const@ void (@&@ fr)( int ) = f; $\C{// routine reference}$
fr = ... $\C{// error, cannot change code}$
&fr = ...; $\C{// changing routine reference}$
fr( 3 ); $\C{// reference call to f}$
(*fr)(3); $\C{// error, incorrect type}$
\end{cfa}
because the value of the routine object is a routine literal, \ie the routine code is normally immutable during execution.\footnote{
Dynamic code rewriting is possible but only in special circumstances.}
\CFA allows this additional use of references for routine objects in an attempt to give a more consistent meaning for them.


\subsection{Address-of Semantics}

In C, ©&E© is an rvalue for any expression ©E©.
\CFA extends the ©&© (address-of) operator as follows:
\begin{itemize}
\item
if ©R© is an \Index{rvalue} of type ©T &©$_1\cdots$ ©&©$_r$, where $r \ge 1$ references (©&© symbols), than ©&R© has type ©T ©\R{©*©}©&©\R{$_2$}$\cdots$ ©&©\R{$_r$}, \ie ©T© pointer with $r-1$ references (©&© symbols).

\item
if ©L© is an \Index{lvalue} of type ©T &©$_1\cdots$ ©&©$_l$, where $l \ge 0$ references (©&© symbols), than ©&L© has type ©T ©\R{©*©}©&©\R{$_1$}$\cdots$ ©&©\R{$_l$}, \ie ©T© pointer with $l$ references (©&© symbols).
\end{itemize}
The following example shows the first rule applied to different \Index{rvalue} contexts:
\begin{cfa}
int x, * px, ** ppx, *** pppx, **** ppppx;
int & rx = x, && rrx = rx, &&& rrrx = rrx ;
x = rrrx; $\C[2.0in]{// rrrx is an lvalue with type int \&\&\& (equivalent to x)}$
px = &rrrx; $\C{// starting from rrrx, \&rrrx is an rvalue with type int *\&\&\& (\&x)}$
ppx = &&rrrx; $\C{// starting from \&rrrx, \&\&rrrx is an rvalue with type int **\&\& (\&rx)}$
pppx = &&&rrrx; $\C{// starting from \&\&rrrx, \&\&\&rrrx is an rvalue with type int ***\& (\&rrx)}$
ppppx = &&&&rrrx; $\C{// starting from \&\&\&rrrx, \&\&\&\&rrrx is an rvalue with type int **** (\&rrrx)}$
\end{cfa}
The following example shows the second rule applied to different \Index{lvalue} contexts:
\begin{cfa}
int x, * px, ** ppx, *** pppx;
int & rx = x, && rrx = rx, &&& rrrx = rrx ;
rrrx = 2; $\C{// rrrx is an lvalue with type int \&\&\& (equivalent to x)}$
&rrrx = px; $\C{// starting from rrrx, \&rrrx is an rvalue with type int *\&\&\& (rx)}$
&&rrrx = ppx; $\C{// starting from \&rrrx, \&\&rrrx is an rvalue with type int **\&\& (rrx)}$
&&&rrrx = pppx; $\C{// starting from \&\&rrrx, \&\&\&rrrx is an rvalue with type int ***\& (rrrx)}\CRT$
\end{cfa}


\subsection{Conversions}

C provides a basic implicit conversion to simplify variable usage:
\begin{enumerate}
\setcounter{enumi}{-1}
\item
lvalue to rvalue conversion: ©cv T© converts to ©T©, which allows implicit variable dereferencing.
\begin{cfa}
int x;
x + 1; $\C[2.0in]{// lvalue variable (int) converts to rvalue for expression}$
\end{cfa}
An rvalue has no type qualifiers (©cv©), so the lvalue qualifiers are dropped.
\end{enumerate}
\CFA provides three new implicit conversion for reference types to simplify reference usage.
\begin{enumerate}
\item
reference to rvalue conversion: ©cv T &© converts to ©T©, which allows implicit reference dereferencing.
\begin{cfa}
int x, &r = x, f( int p );
x = @r@ + f( @r@ ); $\C{// lvalue reference converts to rvalue}$
\end{cfa}
An rvalue has no type qualifiers (©cv©), so the reference qualifiers are dropped.

\item
lvalue to reference conversion: \lstinline[deletekeywords=lvalue]@lvalue-type cv1 T@ converts to ©cv2 T &©, which allows implicitly converting variables to references.
\begin{cfa}
int x, &r = @x@, f( int & p ); $\C{// lvalue variable (int) convert to reference (int \&)}$
f( @x@ ); $\C{// lvalue variable (int) convert to reference (int \&)}$
\end{cfa}
Conversion can restrict a type, where ©cv1© $\le$ ©cv2©, \eg passing an ©int© to a ©const volatile int &©, which has low cost.
Conversion can expand a type, where ©cv1© $>$ ©cv2©, \eg passing a ©const volatile int© to an ©int &©, which has high cost (\Index{warning});
furthermore, if ©cv1© has ©const© but not ©cv2©, a temporary variable is created to preserve the immutable lvalue.

\item
rvalue to reference conversion: ©T© converts to ©cv T &©, which allows binding references to temporaries.
\begin{cfa}
int x, & f( int & p );
f( @x + 3@ );	$\C[1.5in]{// rvalue parameter (int) implicitly converts to lvalue temporary reference (int \&)}$
@&f@(...) = &x;	$\C{// rvalue result (int \&) implicitly converts to lvalue temporary reference (int \&)}\CRT$
\end{cfa}
In both case, modifications to the temporary are inaccessible (\Index{warning}).
Conversion expands the temporary-type with ©cv©, which is low cost since the temporary is inaccessible.
\end{enumerate}


\begin{comment}
From: Richard Bilson <rcbilson@gmail.com>
Date: Wed, 13 Jul 2016 01:58:58 +0000
Subject: Re: pointers / references
To: "Peter A. Buhr" <pabuhr@plg2.cs.uwaterloo.ca>

As a general comment I would say that I found the section confusing, as you move back and forth
between various real and imagined programming languages. If it were me I would rewrite into two
subsections, one that specifies precisely the syntax and semantics of reference variables and
another that provides the rationale.

I don't see any obvious problems with the syntax or semantics so far as I understand them. It's not
obvious that the description you're giving is complete, but I'm sure you'll find the special cases
as you do the implementation.

My big gripes are mostly that you're not being as precise as you need to be in your terminology, and
that you say a few things that aren't actually true even though I generally know what you mean.

20 C provides a pointer type; CFA adds a reference type. Both types contain an address, which is normally a
21 location in memory.

An address is not a location in memory; an address refers to a location in memory. Furthermore it
seems weird to me to say that a type "contains" an address; rather, objects of that type do.

21 Special addresses are used to denote certain states or access co-processor memory. By
22 convention, no variable is placed at address 0, so addresses like 0, 1, 2, 3 are often used to denote no-value
23 or other special states.

This isn't standard C at all. There has to be one null pointer representation, but it doesn't have
to be a literal zero representation and there doesn't have to be more than one such representation.

23 Often dereferencing a special state causes a memory fault, so checking is necessary
24 during execution.

I don't see the connection between the two clauses here. I feel like if a bad pointer will not cause
a memory fault then I need to do more checking, not less.

24 If the programming language assigns addresses, a program's execution is sound, \ie all
25 addresses are to valid memory locations.

You haven't said what it means to "assign" an address, but if I use my intuitive understanding of
the term I don't see how this can be true unless you're assuming automatic storage management.

1 Program variables are implicit pointers to memory locations generated by the compiler and automatically
2 dereferenced, as in:

There is no reason why a variable needs to have a location in memory, and indeed in a typical
program many variables will not. In standard terminology an object identifier refers to data in the
execution environment, but not necessarily in memory.

13 A pointer/reference is a generalization of a variable name, \ie a mutable address that can point to more
14 than one memory location during its lifetime.

I feel like you're off the reservation here. In my world there are objects of pointer type, which
seem to be what you're describing here, but also pointer values, which can be stored in an object of
pointer type but don't necessarily have to be. For example, how would you describe the value denoted
by "&main" in a C program? I would call it a (function) pointer, but that doesn't satisfy your
definition.

16 not occupy storage as the literal is embedded directly into instructions.) Hence, a pointer occupies memory
17 to store its current address, and the pointer's value is loaded by dereferencing, \eg:

As with my general objection regarding your definition of variables, there is no reason why a
pointer variable (object of pointer type) needs to occupy memory.

21 p2 = p1 + x; // compiler infers *p2 = *p1 + x;

What language are we in now?

24 pointer usage. However, in C, the following cases are ambiguous, especially with pointer arithmetic:
25 p1 = p2; // p1 = p2 or *p1 = *p2

This isn't ambiguous. it's defined to be the first option.

26 p1 = p1 + 1; // p1 = p1 + 1 or *p1 = *p1 + 1

Again, this statement is not ambiguous.

13 example. Hence, a reference behaves like the variable name for the current variable it is pointing-to. The
14 simplest way to understand a reference is to imagine the compiler inserting a dereference operator before
15 the reference variable for each reference qualifier in a declaration, \eg:

It's hard for me to understand who the audience for this part is. I think a practical programmer is
likely to be satisfied with "a reference behaves like the variable name for the current variable it
is pointing-to," maybe with some examples. Your "simplest way" doesn't strike me as simpler than
that. It feels like you're trying to provide a more precise definition for the semantics of
references, but it isn't actually precise enough to be a formal specification. If you want to
express the semantics of references using rewrite rules that's a great way to do it, but lay the
rules out clearly, and when you're showing an example of rewriting keep your
references/pointers/values separate (right now, you use \eg "r3" to mean a reference, a pointer,
and a value).

24 Cancellation works to arbitrary depth, and pointer and reference values are interchangeable because both
25 contain addresses.

Except they're not interchangeable, because they have different and incompatible types.

40 Interestingly, C++ deals with the address duality by making the pointed-to value the default, and prevent-
41 ing changes to the reference address, which eliminates half of the duality. Java deals with the address duality
42 by making address assignment the default and requiring field assignment (direct or indirect via methods),
43 \ie there is no builtin bit-wise or method-wise assignment, which eliminates half of the duality.

I can follow this but I think that's mostly because I already understand what you're trying to
say. I don't think I've ever heard the term "method-wise assignment" and I don't see you defining
it. Furthermore Java does have value assignment of basic (non-class) types, so your summary here
feels incomplete. (If it were me I'd drop this paragraph rather than try to save it.)

11 Hence, for type & const, there is no pointer assignment, so &rc = &x is disallowed, and the address value
12 cannot be 0 unless an arbitrary pointer is assigned to the reference.

Given the pains you've taken to motivate every little bit of the semantics up until now, this last
clause ("the address value cannot be 0") comes out of the blue. It seems like you could have
perfectly reasonable semantics that allowed the initialization of null references.

12 In effect, the compiler is managing the
13 addresses for type & const not the programmer, and by a programming discipline of only using references
14 with references, address errors can be prevented.

Again, is this assuming automatic storage management?

18 rary binding. For reference initialization (like pointer), the initializing value must be an address (lvalue) not
19 a value (rvalue).

This sentence appears to suggest that an address and an lvalue are the same thing.

20 int * p = &x; // both &x and x are possible interpretations

Are you saying that we should be considering "x" as a possible interpretation of the initializer
"&x"? It seems to me that this expression has only one legitimate interpretation in context.

21 int & r = x; // x unlikely interpretation, because of auto-dereferencing

You mean, we can initialize a reference using an integer value? Surely we would need some sort of
cast to induce that interpretation, no?

22 Hence, the compiler implicitly inserts a reference operator, &, before the initialization expression.

But then the expression would have pointer type, which wouldn't be compatible with the type of r.

22 Similarly,
23 when a reference is used for a parameter/return type, the call-site argument does not require a reference
24 operator.

Furthermore, it would not be correct to use a reference operator.

45 The implicit conversion allows
1 seamless calls to any routine without having to explicitly name/copy the literal/expression to allow the call.
2 While C' attempts to handle pointers and references in a uniform, symmetric manner, C handles routine
3 variables in an inconsistent way: a routine variable is both a pointer and a reference (particle and wave).

After all this talk of how expressions can have both pointer and value interpretations, you're
disparaging C because it has expressions that have both pointer and value interpretations?

On Sat, Jul 9, 2016 at 4:18 PM Peter A. Buhr <pabuhr@plg.uwaterloo.ca> wrote:
> Aaron discovered a few places where "&"s are missing and where there are too many "&", which are
> corrected in the attached updated. None of the text has changed, if you have started reading
> already.
\end{comment}


\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 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}
@[ int o1, int o2, char o3 ]@ f( int i1, char i2, char i3 ) {
	$\emph{routine body}$
}
\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.

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{
\Index*{Michael Tiemann}\index{Tiemann, Michael}, with help from \Index*{Doug Lea}\index{Lea, Doug}, provided named return values in g++, circa 1989.}
The value of each local return variable is automatically returned at routine termination.
Declaration qualifiers can only appear at the start of a routine definition, \eg:
\begin{cfa}
@extern@ [ int x ] g( int y ) {$\,$}
\end{cfa}
Lastly, if there are no output parameters or input parameters, the brackets and/or parentheses must still be specified;
in both cases the type is assumed to be void as opposed to old style C defaults of int return type and unknown parameter types, respectively, as in:
\begin{cfa}
[$\,$] g(); $\C{// no input or output parameters}$
[ void ] g( void ); $\C{// no input or output parameters}$
\end{cfa}

Routine f is called as follows:
\begin{cfa}
[ i, j, ch ] = f( 3, 'a', ch );
\end{cfa}
The list of return values from f and the grouping on the left-hand side of the assignment is called a \newterm{return list} and discussed in Section 12.

\CFA style declarations cannot be used to declare parameters for K\&R style routine definitions because of the following ambiguity:
\begin{cfa}
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.
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:
\begin{cfa}
typedef int foo;
int f( int (* foo) ); $\C{// foo is redefined as a parameter name}$
\end{cfa}
The string ``©int (* foo)©'' declares a C-style named-parameter of type pointer to an integer (the parenthesis are superfluous), while the same string declares a \CFA style unnamed parameter of type routine returning integer with unnamed parameter of type pointer to foo.
The redefinition of a type name in a parameter list is the only context in C where the character ©*© can appear to the left of a type name, and \CFA relies on all type qualifier characters appearing to the right of the type name.
The inability to use \CFA declarations in these two contexts is probably a blessing because it precludes programmers from arbitrarily switching between declarations forms within a declaration contexts.

C-style declarations can be used to declare parameters for \CFA style routine definitions, \eg:
\begin{cfa}
[ int ] f( * int, int * ); $\C{// returns an integer, accepts 2 pointers to integers}$
[ * int, int * ] f( int ); $\C{// returns 2 pointers to integers, accepts an integer}$
\end{cfa}
The reason for allowing both declaration styles in the new context is for backwards compatibility with existing preprocessor macros that generate C-style declaration-syntax, as in:
\begin{cfa}
#define ptoa( n, d ) int (*n)[ d ]
int f( ptoa( p, 5 ) ) ... $\C{// expands to int f( int (*p)[ 5 ] )}$
[ int ] f( ptoa( p, 5 ) ) ... $\C{// expands to [ int ] f( int (*p)[ 5 ] )}$
\end{cfa}
Again, programmers are highly encouraged to use one declaration form or the other, rather than mixing the forms.


\subsection{Named Return Values}

\Index{Named return values} handle the case where it is necessary to define a local variable whose value is then returned in a ©return© statement, as in:
\begin{cfa}
int f() {
	int x;
	... x = 0; ... x = y; ...
	return x;
}
\end{cfa}
Because the value in the return variable is automatically returned when a \CFA routine terminates, the ©return© statement \emph{does not} contain an expression, as in:
\newline
\begin{minipage}{\linewidth}
\begin{cfa}
@[ int x, int y ]@ f() {
	int z;
	... x = 0; ... y = z; ...
	@return;@ $\C{// implicitly return x, y}$
}
\end{cfa}
\end{minipage}
\newline
When the return is encountered, the current values of ©x© and ©y© are returned to the calling routine.
As well, ``falling off the end'' of a routine without a ©return© statement is permitted, as in:
\begin{cfa}
[ int x, int y ] f() {
	...
} $\C{// implicitly return x, y}$
\end{cfa}
In this case, the current values of ©x© and ©y© are returned to the calling routine just as if a ©return© had been encountered.

Named return values may be used in conjunction with named parameter values;
specifically, a return and parameter can have the same name.
\begin{cfa}
[ int x, int y ] f( int, x, int y ) {
	...
} $\C{// implicitly return x, y}$
\end{cfa}
This notation allows the compiler to eliminate temporary variables in nested routine calls.
\begin{cfa}
[ int x, int y ] f( int, x, int y ); $\C{// prototype declaration}$
int a, b;
[a, b] = f( f( f( a, b ) ) );
\end{cfa}
While the compiler normally ignores parameters names in prototype declarations, here they are used to eliminate temporary return-values by inferring that the results of each call are the inputs of the next call, and ultimately, the left-hand side of the assignment.
Hence, even without the body of routine ©f© (separate compilation), it is possible to perform a global optimization across routine calls.
The compiler warns about naming inconsistencies between routine prototype and definition in this case, and behaviour is \Index{undefined} if the programmer is inconsistent.


\subsection{Routine Prototype}

The syntax of the new routine prototype declaration follows directly from the new routine definition syntax;
as well, parameter names are optional, \eg:
\begin{cfa}
[ int x ] f (); $\C{// returning int with no parameters}$
[ * int ] g (int y); $\C{// returning pointer to int with int parameter}$
[ ] h ( int, char ); $\C{// returning no result with int and char parameters}$
[ * int, int ] j ( int ); $\C{// returning pointer to int and int, with int parameter}$
\end{cfa}
This syntax allows a prototype declaration to be created by cutting and pasting source text from the routine definition header (or vice versa).
Like C, it is possible to declare multiple routine-prototypes in a single declaration, where the return type is distributed across \emph{all} routine names in the declaration list \see{\VRef{s:AlternativeDeclarations}}, \eg:
\begin{cfa}
C :		const double bar1(), bar2( int ), bar3( double );
$\CFA$:	[const double] foo(), foo( int ), foo( double ) { return 3.0; }
\end{cfa}
\CFA allows the last routine in the list to define its body.

Declaration qualifiers can only appear at the start of a \CFA routine declaration,\footref{StorageClassSpecifier} \eg:
\begin{cfa}
extern [ int ] f ( int );
static [ int ] g ( int );
\end{cfa}


\section{Routine Pointers}

The syntax for pointers to \CFA routines specifies the pointer name on the right, \eg:
\begin{cfa}
* [ int x ] () fp; $\C[2.25in]{// pointer to routine returning int with no parameters}$
* [ * int ] (int y) gp; $\C{// pointer to routine returning pointer to int with int parameter}$
* [ ] (int,char) hp; $\C{// pointer to routine returning no result with int and char parameters}$
* [ * int,int ] ( int ) jp; $\C{// pointer to routine returning pointer to int and int, with int parameter}\CRT$
\end{cfa}
While parameter names are optional, \emph{a routine name cannot be specified};
for example, the following is incorrect:
\begin{cfa}
* [ int x ] f () fp; $\C{// routine name "f" is not allowed}$
\end{cfa}


\section{Named and Default Arguments}

Named\index{named arguments}\index{arguments!named} and default\index{default arguments}\index{arguments!default} arguments~\cite{Hardgrave76}\footnote{
Francez~\cite{Francez77} proposed a further extension to the named-parameter passing style, which specifies what type of communication (by value, by reference, by name) the argument is passed to the routine.}
are two mechanisms to simplify routine call.
Both mechanisms are discussed with respect to \CFA.
\begin{description}
\item[Named (or Keyword) Arguments:]
provide the ability to specify an argument to a routine call using the parameter name rather than the position of the parameter.
For example, given the routine:
\begin{cfa}
void p( int x, int y, int z ) {...}
\end{cfa}
a positional call is:
\begin{cfa}
p( 4, 7, 3 );
\end{cfa}
whereas a named (keyword) call may be:
\begin{cfa}
p( z : 3, x : 4, y : 7 );  $\C{// rewrite \(\Rightarrow\) p( 4, 7, 3 )}$
\end{cfa}
Here the order of the arguments is unimportant, and the names of the parameters are used to associate argument values with the corresponding parameters.
The compiler rewrites a named call into a positional call.
The advantages of named parameters are:
\begin{itemize}
\item
Remembering the names of the parameters may be easier than the order in the routine definition.
\item
Parameter names provide documentation at the call site (assuming the names are descriptive).
\item
Changes can be made to the order or number of parameters without affecting the call (although the call must still be recompiled).
\end{itemize}

Unfortunately, named arguments do not work in C-style programming-languages because a routine prototype is not required to specify parameter names, nor do the names in the prototype have to match with the actual definition.
For example, the following routine prototypes and definition are all valid.
\begin{cfa}
void p( int, int, int ); $\C{// equivalent prototypes}$
void p( int x, int y, int z );
void p( int y, int x, int z );
void p( int z, int y, int x );
void p( int q, int r, int s ) {} $\C{// match with this definition}$
\end{cfa}
Forcing matching parameter names in routine prototypes with corresponding routine definitions is possible, but goes against a strong tradition in C programming.
Alternatively, prototype definitions can be eliminated by using a two-pass compilation, and implicitly creating header files for exports.
The former is easy to do, while the latter is more complex.

Furthermore, named arguments do not work well in a \CFA-style programming-languages because they potentially introduces a new criteria for type matching.
For example, it is technically possible to disambiguate between these two overloaded definitions of ©f© based on named arguments at the call site:
\begin{cfa}
int f( int i, int j );
int f( int x, double y );

f( j : 3, i : 4 ); $\C{// 1st f}$
f( x : 7, y : 8.1 ); $\C{// 2nd f}$
f( 4, 5 );  $\C{// ambiguous call}$
\end{cfa}
However, named arguments compound routine resolution in conjunction with conversions:
\begin{cfa}
f( i : 3, 5.7 ); $\C{// ambiguous call ?}$
\end{cfa}
Depending on the cost associated with named arguments, this call could be resolvable or ambiguous.
Adding named argument into the routine resolution algorithm does not seem worth the complexity.
Therefore, \CFA does \emph{not} attempt to support named arguments.

\item[Default Arguments]
provide the ability to associate a default value with a parameter so it can be optionally specified in the argument list.
For example, given the routine:
\begin{cfa}
void p( int x = 1, int y = 2, int z = 3 ) {...}
\end{cfa}
the allowable positional calls are:
\begin{cfa}
p(); $\C{// rewrite \(\Rightarrow\) p( 1, 2, 3 )}$
p( 4 ); $\C{// rewrite \(\Rightarrow\) p( 4, 2, 3 )}$
p( 4, 4 ); $\C{// rewrite \(\Rightarrow\) p( 4, 4, 3 )}$
p( 4, 4, 4 ); $\C{// rewrite \(\Rightarrow\) p( 4, 4, 4 )}$
// empty arguments
p(  , 4, 4 ); $\C{// rewrite \(\Rightarrow\) p( 1, 4, 4 )}$
p( 4,  , 4 ); $\C{// rewrite \(\Rightarrow\) p( 4, 2, 4 )}$
p( 4, 4,   ); $\C{// rewrite \(\Rightarrow\) p( 4, 4, 3 )}$
p( 4,  ,   ); $\C{// rewrite \(\Rightarrow\) p( 4, 2, 3 )}$
p(  , 4,   ); $\C{// rewrite \(\Rightarrow\) p( 1, 4, 3 )}$
p(  ,  , 4 ); $\C{// rewrite \(\Rightarrow\) p( 1, 2, 4 )}$
p(  ,  ,   ); $\C{// rewrite \(\Rightarrow\) p( 1, 2, 3 )}$
\end{cfa}
Here the missing arguments are inserted from the default values in the parameter list.
The compiler rewrites missing default values into explicit positional arguments.
The advantages of default values are:
\begin{itemize}
\item
Routines with a large number of parameters are often very generalized, giving a programmer a number of different options on how a computation is performed.
For many of these kinds of routines, there are standard or default settings that work for the majority of computations.
Without default values for parameters, a programmer is forced to specify these common values all the time, resulting in long argument lists that are error prone.
\item
When a routine's interface is augmented with new parameters, it extends the interface providing generalizability\footnote{
``It should be possible for the implementor of an abstraction to increase its generality.
So long as the modified abstraction is a generalization of the original, existing uses of the abstraction will not require change.
It might be possible to modify an abstraction in a manner which is not a generalization without affecting existing uses, but, without inspecting the modules in which the uses occur, this possibility cannot be determined.
This criterion precludes the addition of parameters, unless these parameters have default or inferred values that are valid for all possible existing applications.''~\cite[p.~128]{Cormack90}}
(somewhat like the generalization provided by inheritance for classes).
That is, all existing calls are still valid, although the call must still be recompiled.
\end{itemize}
The only disadvantage of default arguments is that unintentional omission of an argument may not result in a compiler-time error.
Instead, a default value is used, which may not be the programmer's intent.

Default values may only appear in a prototype versus definition context:
\begin{cfa}
void p( int x, int y = 2, int z = 3 ); $\C{// prototype: allowed}$
void p( int, int = 2, int = 3 ); $\C{// prototype: allowed}$
void p( int x, int y = 2, int z = 3 ) {} $\C{// definition: not allowed}$
\end{cfa}
The reason for this restriction is to allow separate compilation.
Multiple prototypes with different default values is an error.
\end{description}

Ellipse (``...'') arguments present problems when used with default arguments.
The conflict occurs because both named and ellipse arguments must appear after positional arguments, giving two possibilities:
\begin{cfa}
p( /* positional */, ... , /* named */ );
p( /* positional */, /* named */, ... );
\end{cfa}
While it is possible to implement both approaches, the first possibly is more complex than the second, \eg:
\begin{cfa}
p( int x, int y, int z, ... );
p( 1, 4, 5, 6, z : 3, y : 2 ); $\C{// assume p( /* positional */, ... , /* named */ );}$
p( 1, z : 3, y : 2, 4, 5, 6 ); $\C{// assume p( /* positional */, /* named */, ... );}$
\end{cfa}
In the first call, it is necessary for the programmer to conceptually rewrite the call, changing named arguments into positional, before knowing where the ellipse arguments begin.
Hence, this approach seems significantly more difficult, and hence, confusing and error prone.
In the second call, the named arguments separate the positional and ellipse arguments, making it trivial to read the call.

The problem is exacerbated with default arguments, \eg:
\begin{cfa}
void p( int x, int y = 2, int z = 3... );
p( 1, 4, 5, 6, z : 3 ); $\C{// assume p( /* positional */, ... , /* named */ );}$
p( 1, z : 3, 4, 5, 6 ); $\C{// assume p( /* positional */, /* named */, ... );}$
\end{cfa}
The first call is an error because arguments 4 and 5 are actually positional not ellipse arguments;
therefore, argument 5 subsequently conflicts with the named argument z : 3.
In the second call, the default value for y is implicitly inserted after argument 1 and the named arguments separate the positional and ellipse arguments, making it trivial to read the call.
For these reasons, \CFA requires named arguments before ellipse arguments.
Finally, while ellipse arguments are needed for a small set of existing C routines, like ©printf©, the extended \CFA type system largely eliminates the need for ellipse arguments \see{\VRef{s:Overloading}}, making much of this discussion moot.

Default arguments and overloading \see{\VRef{s:Overloading}} are complementary.
While in theory default arguments can be simulated with overloading, as in:
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{default arguments}}	& \multicolumn{1}{c}{\textbf{overloading}}	\\
\begin{cfa}
void p( int x, int y = 2, int z = 3 ) {...}


\end{cfa}
&
\begin{cfa}
void p( int x, int y, int z ) {...}
void p( int x ) { p( x, 2, 3 ); }
void p( int x, int y ) { p( x, y, 3 ); }
\end{cfa}
\end{tabular}
\end{cquote}
the number of required overloaded routines is linear in the number of default values, which is unacceptable growth.
In general, overloading should only be used over default arguments if the body of the routine is significantly different.
Furthermore, overloading cannot handle accessing default arguments in the middle of a positional list, via a missing argument, such as:
\begin{cfa}
p( 1, /* default */, 5 ); $\C{// rewrite \(\Rightarrow\) p( 1, 2, 5 )}$
\end{cfa}

Given the \CFA restrictions above, both named and default arguments are backwards compatible.
\Index*[C++]{\CC{}} only supports default arguments;
\Index*{Ada} supports both named and default arguments.


\section{Unnamed Structure Fields}

C requires each field of a structure to have a name, except for a bit field associated with a basic type, \eg:
\begin{cfa}
struct {
	int f1; $\C{// named field}$
	int f2 : 4; $\C{// named field with bit field size}$
	int : 3; $\C{// unnamed field for basic type with bit field size}$
	int ; $\C{// disallowed, unnamed field}$
	int *; $\C{// disallowed, unnamed field}$
	int (*)( int ); $\C{// disallowed, unnamed field}$
};
\end{cfa}
This requirement is relaxed by making the field name optional for all field declarations; therefore, all the field declarations in the example are allowed.
As for unnamed bit fields, an unnamed field is used for padding a structure to a particular size.
A list of unnamed fields is also supported, \eg:
\begin{cfa}
struct {
	int , , ; $\C{// 3 unnamed fields}$
}
\end{cfa}


\section{Nesting}

Nesting of types and routines is useful for controlling name visibility (\newterm{name hiding}).


\subsection{Type Nesting}

\CFA allows \Index{type nesting}, and type qualification of the nested types \see{\VRef[Figure]{f:TypeNestingQualification}}, where as C hoists\index{type hoisting} (refactors) nested types into the enclosing scope and has no type qualification.
\begin{figure}
\centering
\begin{tabular}{@{}l@{\hspace{3em}}l|l@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{C Type Nesting}}	& \multicolumn{1}{c}{\textbf{C Implicit Hoisting}}	& \multicolumn{1}{|c}{\textbf{\CFA}}	\\
\hline
\begin{cfa}
struct S {
	enum C { R, G, B };
	struct T {
		union U { int i, j; };
		enum C c;
		short int i, j;
	};
	struct T t;
} s;

int fred() {
	s.t.c = R;
	struct T t = { R, 1, 2 };
	enum C c;
	union U u;
}
\end{cfa}
&
\begin{cfa}
enum C { R, G, B };
union U { int i, j; };
struct T {
	enum C c;
	short int i, j;
};
struct S {
	struct T t;
} s;







\end{cfa}
&
\begin{cfa}
struct S {
	enum C { R, G, B };
	struct T {
		union U { int i, j; };
		enum C c;
		short int i, j;
	};
	struct T t;
} s;

int fred() {
	s.t.c = @S.@R;	// type qualification
	struct @S.@T t = { @S.@R, 1, 2 };
	enum @S.@C c;
	union @S.T.@U u;
}
\end{cfa}
\end{tabular}
\caption{Type Nesting / Qualification}
\label{f:TypeNestingQualification}
\end{figure}
In the left example in C, types ©C©, ©U© and ©T© are implicitly hoisted outside of type ©S© into the containing block scope.
In the right example in \CFA, the types are not hoisted and accessed using the field-selection operator ``©.©'' for type qualification, as does \Index*{Java}, rather than the \CC type-selection operator ``©::©''.


\subsection{Routine Nesting}

While \CFA does not provide object programming by putting routines into structures, it does rely heavily on locally nested routines to redefine operations at or close to a call site.
For example, the C quick-sort is wrapped into the following polymorphic \CFA routine:
\begin{cfa}
forall( otype T | { int ?<?( T, T ); } )
void qsort( const T * arr, size_t dimension );
\end{cfa}
which can be used to sort in ascending and descending order by locally redefining the less-than operator into greater-than.
\begin{cfa}
const unsigned int size = 5;
int ia[size];
... $\C{// assign values to array ia}$
qsort( ia, size ); $\C{// sort ascending order using builtin ?<?}$
{
	@int ?<?( int x, int y ) { return x > y; }@ $\C{// nested routine}$
	qsort( ia, size ); $\C{// sort descending order by local redefinition}$
}
\end{cfa}

Nested routines are not first-class, meaning a nested routine cannot be returned if it has references to variables in its enclosing blocks;
the only exception is references to the external block of the translation unit, as these variables persist for the duration of the program.
The following program in undefined in \CFA (and Indexc{gcc})
\begin{cfa}
[* [int]( int )] foo() { $\C{// int (* foo())( int )}$
	int @i@ = 7;
	int bar( int p ) {
		@i@ += 1; $\C{// dependent on local variable}$
		sout | @i@;
	}
	return bar; $\C{// undefined because of local dependence}$
}
int main() {
	* [int]( int ) fp = foo(); $\C{// int (* fp)( int )}$
	sout | fp( 3 );
}
\end{cfa}
because

Currently, there are no \Index{lambda} expressions, \ie unnamed routines because routine names are very important to properly select the correct routine.


\section{Tuple}

In C and \CFA, lists of elements appear in several contexts, such as the parameter list of a routine call.
\begin{cfa}
f( @2, x, 3 + i@ ); $\C{// element list}$
\end{cfa}
A list of elements is called a \newterm{tuple}, and is different from a \Index{comma expression}.


\subsection{Multiple-Return-Value Functions}
\label{s:MRV_Functions}

In C and most programming languages, functions return at most one value;
however, many operations have multiple outcomes, some exceptional \see{\VRef{s:ExceptionHandling}}.
To emulate functions with multiple return values, \emph{\Index{aggregation}} and/or \emph{\Index{aliasing}} is used.

In the former approach, a record type is created combining all of the return values.
For example, consider C's \Indexc{div} function, which returns the quotient and remainder for a division of an integer value.
\begin{cfa}
typedef struct { int quot, rem; } div_t;	$\C[7cm]{// from include stdlib.h}$
div_t div( int num, int den );
div_t qr = div( 13, 5 ); $\C{// return quotient/remainder aggregate}$
printf( "%d %d\n", qr.quot, qr.rem ); $\C{// print quotient/remainder}$
\end{cfa}
This approach requires a name for the return type and fields, where \Index{naming} is a common programming-language issue.
That is, naming creates an association that must be managed when reading and writing code.
While effective when used sparingly, this approach does not scale when functions need to return multiple combinations of types.

In the latter approach, additional return values are passed as pointer parameters.
A pointer parameter is assigned inside the routine to emulate a return.
For example, consider C's \Indexc{modf} function, which returns the integral and fractional part of a floating value.
\begin{cfa}
double modf( double x, double * i ); $\C{// from include math.h}$
double intp, frac = modf( 13.5, &intp ); $\C{// return integral and fractional components}$
printf( "%g %g\n", intp, frac ); $\C{// print integral/fractional components}$
\end{cfa}
This approach requires allocating storage for the return values, which complicates the call site with a sequence of variable declarations leading to the call.
Also, while a disciplined use of ©const© can give clues about whether a pointer parameter is used as an \Index{out parameter}, it is not obvious from the routine signature whether the callee expects such a parameter to be initialized before the call.
Furthermore, while many C routines that accept pointers are safe for a ©NULL© argument, there are many C routines that are not null-safe.
Finally, C does not provide a mechanism to state that a parameter is going to be used as an additional return value, which makes the job of ensuring that a value is returned more difficult for the compiler.
Still, not every routine with multiple return values should be required to return an error code, and error codes are easily ignored, so this is not a satisfying solution.
As with the previous approach, this technique can simulate multiple return values, but in practice it is verbose and error prone.

\CFA allows functions to return multiple values by extending the function declaration syntax.
Multiple return values are declared as a comma-separated list of types in square brackets in the same location that the return type appears in standard C function declarations.
\begin{cfa}
[ char, int, double ] f( ... );
\end{cfa}
The ability to return multiple values from a function requires a new syntax for the return statement.
For consistency, the return statement in \CFA accepts a comma-separated list of expressions in square brackets.
\begin{cfa}
return [ c, i, d ];
\end{cfa}
The expression resolution ensures the correct form is used depending on the values being returned and the return type of the current function.
A multiple-returning function with return type ©T© can return any expression that is implicitly convertible to ©T©.

A common use of a function's output is input to another function.
\CFA allows this case, without any new syntax;
a multiple-returning function can be used in any of the contexts where an expression is allowed.
When a function call is passed as an argument to another call, the best match of actual arguments to formal parameters is evaluated given all possible expression interpretations in the current scope.
\begin{cfa}
void g( int, int ); $\C{// 1}$
void g( double, double ); $\C{// 2}$
g( div( 13, 5 ) ); $\C{// select 1}$
g( modf( 13.5 ) ); $\C{// select 2}$
\end{cfa}
In this case, there are two overloaded ©g© routines.
Both calls to ©g© expect two arguments that are matched by the two return values from ©div© and ©modf©. respectively, which are fed directly to the first and second parameters of ©g©.
As well, both calls to ©g© have exact type matches for the two different versions of ©g©, so these exact matches are chosen.
When type matches are not exact, conversions are used to find a best match.

The previous examples can be rewritten passing the multiple returned-values directly to the ©printf© function call.
\begin{cfa}
[ int, int ] div( int x, int y ); $\C{// from include stdlib}$
printf( "%d %d\n", div( 13, 5 ) ); $\C{// print quotient/remainder}$

[ double, double ] modf( double x ); $\C{// from include math}$
printf( "%g %g\n", modf( 13.5 ) ); $\C{// print integral/fractional components}$
\end{cfa}
This approach provides the benefits of compile-time checking for appropriate return statements as in aggregation, but without the required verbosity of declaring a new named type.

Finally, the addition of multiple-return-value functions necessitates a syntax for retaining the multiple values at the call-site versus their temporary existence during a call.
The simplest mechanism for retaining a return value in C is variable assignment.
By assigning the multiple return-values into multiple variables, the values can be retrieved later.
As such, \CFA allows assigning multiple values from a function into multiple variables, using a square-bracketed list of lvalue expressions on the left side.
\begin{cfa}
int quot, rem;
[ quot, rem ] = div( 13, 5 ); $\C{// assign multiple variables}$
printf( "%d %d\n", quot, rem ); $\C{// print quotient/remainder}\CRT$
\end{cfa}
Here, the multiple return-values are matched in much the same way as passing multiple return-values to multiple parameters in a call.


\subsection{Expressions}

% Change order of expression evaluation.
% http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0145r2.pdf

Multiple-return-value functions provide \CFA with a new syntax for expressing a combination of expressions in the return statement and a combination of types in a function signature.
These notions are generalized to provide \CFA with \newterm{tuple expression}s and \newterm{tuple type}s.
A tuple expression is an expression producing a fixed-size, ordered list of values of heterogeneous types.
The type of a tuple expression is the tuple of the subexpression types, or a tuple type.

In \CFA, a tuple expression is denoted by a comma-separated list of expressions enclosed in square brackets.
For example, the expression ©[5, 'x', 10.5]© has type ©[int, char, double]©.
The previous expression has 3 \emph{components}.
Each component in a tuple expression can be any \CFA expression, including another tuple expression.
The order of evaluation of the components in a tuple expression is unspecified, to allow a compiler the greatest flexibility for program optimization.
It is, however, guaranteed that each component of a tuple expression is evaluated for side-effects, even if the result is not used.
Multiple-return-value functions can equivalently be called \newterm{tuple-returning functions}.


\subsection{Variables}

The previous call of ©div© still requires the preallocation of multiple return-variables in a manner similar to the aliasing example.
In \CFA, it is possible to overcome this restriction by declaring a \newterm{tuple variable}.
\begin{cfa}
[int, int] @qr@ = div( 13, 5 ); $\C{// initialize tuple variable}$
printf( "%d %d\n", @qr@ ); $\C{// print quotient/remainder}$
\end{cfa}
It is now possible to match the multiple return-values to a single variable, in much the same way as \Index{aggregation}.
As well, the components of the tuple value are passed as separate parameters to ©printf©, allowing direct printing of tuple variables.
One way to access the individual components of a tuple variable is with assignment.
\begin{cfa}
[ quot, rem ] = qr; $\C{// assign multiple variables}$
\end{cfa}

In addition to variables of tuple type, it is also possible to have pointers to tuples, and arrays of tuples.
Tuple types can be composed of any types, except for array types, since array assignment is disallowed, which makes tuple assignment difficult when a tuple contains an array.
\begin{cfa}
[ double, int ] di;
[ double, int ] * pdi
[ double, int ] adi[10];
\end{cfa}
This examples declares a variable of type ©[double, int]©, a variable of type pointer to ©[double, int]©, and an array of ten ©[double, int]©.


\subsection{Indexing}

It is also possible to access a single component of a tuple-valued expression without creating temporary variables.
Given a tuple-valued expression $e$np and a compile-time constant integer $i$ where $0 \leq i < n$, where $n$ is the number of components in $e$, $e.i$ accesses the $i^{\:th}$ component of $e$, \eg:
\begin{cfa}
[int, double] x;
[char *, int] f();
void g(double, int);
[int, double] * p;

int y = x.0; $\C{// access int component of x}$
y = f().1; $\C{// access int component of f}$
p->0 = 5; $\C{// access int component of tuple pointed-to by p}$
g( x.1, x.0 ); $\C{// rearrange x to pass to g}$
double z = [ x, f() ].0.1; $\C{// access second component of first component of tuple expression}$
\end{cfa}
Tuple-index expressions can occur on any tuple-typed expression, including tuple-returning functions, square-bracketed tuple expressions, and other tuple-index expressions, provided the retrieved component is also a tuple.
This feature was proposed for \KWC but never implemented \cite[p.~45]{Till89}.


\subsection{Flattening and Structuring}
\label{s:FlatteningStructuring}

As evident in previous examples, tuples in \CFA do not have a rigid structure.
In function call contexts, tuples support implicit flattening and restructuring conversions.
Tuple flattening recursively expands a tuple into the list of its basic components.
Tuple structuring packages a list of expressions into a value of tuple type.
\begin{cfa}
int f(int, int);
int g([int, int]);
int h(int, [int, int]);
[int, int] x;
int y;

f(x);      // flatten
g(y, 10);  // structure
h(x, y);   // flatten & structure
\end{cfa}
In \CFA, each of these calls is valid.
In the call to ©f©, ©x© is implicitly flattened so that the components of ©x© are passed as the two arguments to ©f©.
For the call to ©g©, the values ©y© and ©10© are structured into a single argument of type ©[int, int]© to match the type of the parameter of ©g©.
Finally, in the call to ©h©, ©x© is flattened to yield an argument list of length 3, of which the first component of ©x© is passed as the first parameter of ©h©, and the second component of ©x© and ©y© are structured into the second argument of type ©[int, int]©.
The flexible structure of tuples permits a simple and expressive function-call syntax to work seamlessly with both single- and multiple-return-value functions, and with any number of arguments of arbitrarily complex structure.

In \KWC \cite{Buhr94a,Till89}, there were 4 tuple coercions: opening, closing, flattening, and structuring.
Opening coerces a tuple value into a tuple of values, while closing converts a tuple of values into a single tuple value.
Flattening coerces a nested tuple into a flat tuple, \ie it takes a tuple with tuple components and expands it into a tuple with only non-tuple components.
Structuring moves in the opposite direction, \ie it takes a flat tuple value and provides structure by introducing nested tuple components.

In \CFA, the design has been simplified to require only the two conversions previously described, which trigger only in function call and return situations.
This simplification is a primary contribution of this thesis to the design of tuples in \CFA.
Specifically, the expression resolution algorithm examines all of the possible alternatives for an expression to determine the best match.
In resolving a function call expression, each combination of function value and list of argument alternatives is examined.
Given a particular argument list and function value, the list of argument alternatives is flattened to produce a list of non-tuple valued expressions.
Then the flattened list of expressions is compared with each value in the function's parameter list.
If the parameter's type is not a tuple type, then the current argument value is unified with the parameter type, and on success the next argument and parameter are examined.
If the parameter's type is a tuple type, then the structuring conversion takes effect, recursively applying the parameter matching algorithm using the tuple's component types as the parameter list types.
Assuming a successful unification, eventually the algorithm gets to the end of the tuple type, which causes all of the matching expressions to be consumed and structured into a tuple expression.
For example, in
\begin{cfa}
int f(int, [double, int]);
f([5, 10.2], 4);
\end{cfa}
There is only a single definition of ©f©, and 3 arguments with only single interpretations.
First, the argument alternative list ©[5, 10.2], 4© is flattened to produce the argument list ©5, 10.2, 4©.
Next, the parameter matching algorithm begins, with $P =$© int© and $A =$© int©, which unifies exactly.
Moving to the next parameter and argument, $P =$© [double, int]© and $A =$© double©.
This time, the parameter is a tuple type, so the algorithm applies recursively with $P' =$© double© and $A =$© double©, which unifies exactly.
Then $P' =$© int© and $A =$© double©, which again unifies exactly.
At this point, the end of $P'$ has been reached, so the arguments ©10.2, 4© are structured into the tuple expression ©[10.2, 4]©.
Finally, the end of the parameter list $P$ has also been reached, so the final expression is ©f(5, [10.2, 4])©.


\subsection{Assignment}
\label{s:TupleAssignment}

An assignment where the left side of the assignment operator has a tuple type is called \newterm{tuple assignment}.
There are two kinds of tuple assignment depending on whether the right side of the assignment operator has a non-tuple or tuple type, called \newterm[mass assignment]{mass} and \newterm[multiple assignment]{multiple} assignment, respectively.
\begin{cfa}
int x;
double y;
[int, double] z;
[y, x] = 3.14; $\C{// mass assignment}$
[x, y] = z;							    $\C{// multiple assignment}$
z = 10;							        $\C{// mass assignment}$
z = [x, y]; $\C{// multiple assignment}$
\end{cfa}
Let $L_i$ for $i$ in $[0, n)$ represent each component of the flattened left side, $R_i$ represent each component of the flattened right side of a multiple assignment, and $R$ represent the right side of a mass assignment.

For a multiple assignment to be valid, both tuples must have the same number of elements when flattened.
For example, the following is invalid because the number of components on the left does not match the number of components on the right.
\begin{cfa}
[ int, int ] x, y, z;
[ x, y ] = z;						   $\C{// multiple assignment, invalid 4 != 2}$
\end{cfa}
Multiple assignment assigns $R_i$ to $L_i$ for each $i$.
That is, ©?=?(&$L_i$, $R_i$)© must be a well-typed expression.
In the previous example, ©[x, y] = z©, ©z© is flattened into ©z.0, z.1©, and the assignments ©x = z.0© and ©y = z.1© happen.

A mass assignment assigns the value $R$ to each $L_i$.
For a mass assignment to be valid, ©?=?(&$L_i$, $R$)© must be a well-typed expression.
These semantics differ from C cascading assignment (\eg ©a=b=c©) in that conversions are applied to $R$ in each individual assignment, which prevents data loss from the chain of conversions that can happen during a cascading assignment.
For example, ©[y, x] = 3.14© performs the assignments ©y = 3.14© and ©x = 3.14©, which results in the value ©3.14© in ©y© and the value ©3© in ©x©.
On the other hand, the C cascading assignment ©y = x = 3.14© performs the assignments ©x = 3.14© and ©y = x©, which results in the value ©3© in ©x©, and as a result the value ©3© in ©y© as well.

Both kinds of tuple assignment have parallel semantics, such that each value on the left side and right side is evaluated \emph{before} any assignments occur.
As a result, it is possible to swap the values in two variables without explicitly creating any temporary variables or calling a function.
\begin{cfa}
int x = 10, y = 20;
[ x, y ] = [ y, x ];
\end{cfa}
After executing this code, ©x© has the value ©20© and ©y© has the value ©10©.

In \CFA, tuple assignment is an expression where the result type is the type of the left side of the assignment, as in normal assignment.
That is, a tuple assignment produces the value of the left-hand side after assignment.
These semantics allow cascading tuple assignment to work out naturally in any context where a tuple is permitted.
These semantics are a change from the original tuple design in \KWC \cite{Till89}, wherein tuple assignment was a statement that allows cascading assignments as a special case.
Restricting tuple assignment to statements was an attempt to to fix what was seen as a problem with side-effects, wherein assignment can be used in many different locations, such as in function-call argument position.
While permitting assignment as an expression does introduce the potential for subtle complexities, it is impossible to remove assignment expressions from \CFA without affecting backwards compatibility.
Furthermore, there are situations where permitting assignment as an expression improves readability by keeping code succinct and reducing repetition, and complicating the definition of tuple assignment puts a greater cognitive burden on the user.
In another language, tuple assignment as a statement could be reasonable, but it would be inconsistent for tuple assignment to be the only kind of assignment that is not an expression.
In addition, \KWC permits the compiler to optimize tuple assignment as a block copy, since it does not support user-defined assignment operators.
This optimization could be implemented in \CFA, but it requires the compiler to verify that the selected assignment operator is trivial.

The following example shows multiple, mass, and cascading assignment used in one expression
\begin{cfa}
	int a, b;
	double c, d;
	[ void ] f( [ int, int ] );
	f( [ c, a ] = [ b, d ] = 1.5 ); $\C{// assignments in parameter list}$
\end{cfa}
The tuple expression begins with a mass assignment of ©1.5© into ©[b, d]©, which assigns ©1.5© into ©b©, which is truncated to ©1©, and ©1.5© into ©d©, producing the tuple ©[1, 1.5]© as a result.
That tuple is used as the right side of the multiple assignment (\ie, ©[c, a] = [1, 1.5]©) that assigns ©1© into ©c© and ©1.5© into ©a©, which is truncated to ©1©, producing the result ©[1, 1]©.
Finally, the tuple ©[1, 1]© is used as an expression in the call to ©f©.


\subsection{Construction}

Tuple construction and destruction follow the same rules and semantics as tuple assignment, except that in the case where there is no right side, the default constructor or destructor is called on each component of the tuple.
As constructors and destructors did not exist in previous versions of \CFA or in \KWC, this is a primary contribution of this thesis to the design of tuples.
\begin{cfa}
struct S;
void ?{}(S *); $\C{// (1)}$
void ?{}(S *, int); $\C{// (2)}$
void ?{}(S * double); $\C{// (3)}$
void ?{}(S *, S); $\C{// (4)}$

[S, S] x = [3, 6.28]; $\C{// uses (2), (3), specialized constructors}$
[S, S] y; $\C{// uses (1), (1), default constructor}$
[S, S] z = x.0; $\C{// uses (4), (4), copy constructor}$
\end{cfa}
In this example, ©x© is initialized by the multiple constructor calls ©?{}(&x.0, 3)© and ©?{}(&x.1, 6.28)©, while ©y© is initialized by two default constructor calls ©?{}(&y.0)© and ©?{}(&y.1)©.
©z© is initialized by mass copy constructor calls ©?{}(&z.0, x.0)© and ©?{}(&z.1, x.0)©.
Finally, ©x©, ©y©, and ©z© are destructed, \ie the calls ©^?{}(&x.0)©, ©^?{}(&x.1)©, ©^?{}(&y.0)©, ©^?{}(&y.1)©, ©^?{}(&z.0)©, and ©^?{}(&z.1)©.

It is possible to define constructors and assignment functions for tuple types that provide new semantics, if the existing semantics do not fit the needs of an application.
For example, the function ©void ?{}([T, U] *, S);© can be defined to allow a tuple variable to be constructed from a value of type ©S©.
\begin{cfa}
struct S { int x; double y; };
void ?{}([int, double] * this, S s) {
	this->0 = s.x;
	this->1 = s.y;
}
\end{cfa}
Due to the structure of generated constructors, it is possible to pass a tuple to a generated constructor for a type with a member prefix that matches the type of the tuple.
For example,
\begin{cfa}
struct S { int x; double y; int z };
[int, double] t;
S s = t;
\end{cfa}
The initialization of ©s© with ©t© works by default because ©t© is flattened into its components, which satisfies the generated field constructor ©?{}(S *, int, double)© to initialize the first two values.


\subsection{Member-Access Expression}
\label{s:MemberAccessTuple}

Tuples may be used to select multiple fields of a record by field name.
The result is a single tuple-valued expression whose type is the tuple of the types of the members.
For example,
\begin{cfa}
struct S { char x; int y; double z; } s;
s.[x, y, z];
\end{cfa}
Here, the type of ©s.[ x, y, z ]© is ©[ char, int, double ]©.
A member tuple expression has the form \emph{e}©.[x, y, z];© where \emph{e} is an expression with type ©T©, where ©T© supports member access expressions, and ©x, y, z© are all members of ©T© with types ©T$_x$©, ©T$_y$©, and ©T$_z$© respectively.
Then the type of \emph{e}©.[x, y, z]© is ©[T$_x$, T$_y$, T$_z$]©.

A member-access tuple may be used anywhere a tuple can be used, \eg:
\begin{cfa}
s.[ y, z, x ] = [ 3, 3.2, 'x' ]; $\C{// equivalent to s.x = 'x', s.y = 3, s.z = 3.2}$
f( s.[ y, z ] ); $\C{// equivalent to f( s.y, s.z )}$
\end{cfa}
Note, the fields appearing in a record-field tuple may be specified in any order;
also, it is unnecessary to specify all the fields of a struct in a multiple record-field tuple.

Since tuple-index expressions are a form of member-access expression, it is possible to use tuple-index expressions in conjunction with member-access expressions to restructure a tuple (\eg, rearrange components, drop components, duplicate components, etc.).
\begin{cfa}
[ int, int, long, double ] x;
void f( double, long );

f( x.[ 0, 3 ] ); $\C{// f( x.0, x.3 )}$
x.[ 0, 1 ] = x.[ 1, 0 ]; $\C{// [ x.0, x.1 ] = [ x.1, x.0 ]}$
[ long, int, long ] y = x.[ 2, 0, 2 ];
\end{cfa}

It is possible for a member tuple expression to contain other member access expressions, \eg:
\begin{cfa}
struct A { double i; int j; };
struct B { int * k; short l; };
struct C { int x; A y; B z; } v;
v.[ x, y.[ i, j ], z.k ];
\end{cfa}
This expression is equivalent to ©[ v.x, [ v.y.i, v.y.j ], v.z.k ]©.
That is, the aggregate expression is effectively distributed across the tuple allowing simple and easy access to multiple components in an aggregate without repetition.
It is guaranteed that the aggregate expression to the left of the ©.© in a member tuple expression is evaluated exactly once.
As such, it is safe to use member tuple expressions on the result of a function with side-effects.
\begin{cfa}
[ int, float, double ] f();
[ double, float ] x = f().[ 2, 1 ]; $\C{// f() called once}$
\end{cfa}

In \KWC, member tuple expressions are known as \emph{record field tuples} \cite{Till89}.
Since \CFA permits these tuple-access expressions using structures, unions, and tuples, \emph{member tuple expression} or \emph{field tuple expression} is more appropriate.


\subsection{Casting}

In C, the cast operator is used to explicitly convert between types.
In \CFA, the cast operator has a secondary use, which is type ascription, since it forces the expression resolution algorithm to choose the lowest cost conversion to the target type.
That is, a cast can be used to select the type of an expression when it is ambiguous, as in the call to an overloaded function.
\begin{cfa}
int f(); $\C{// (1)}$
double f(); $\C{// (2)}$

f(); $\C{// ambiguous - (1),(2) both equally viable}$
(int)f(); $\C{// choose (2)}$
\end{cfa}
Since casting is a fundamental operation in \CFA, casts need to be given a meaningful interpretation in the context of tuples.
Taking a look at standard C provides some guidance with respect to the way casts should work with tuples.
\begin{cfa}[numbers=left]
int f();
void g();

(void)f(); $\C{// valid, ignore results}$
(int)g(); $\C{// invalid, void cannot be converted to int}$

struct A { int x; };
(struct A)f(); $\C{// invalid, int cannot be converted to A}$
\end{cfa}
In C, line 4 is a valid cast, which calls ©f© and discards its result.
On the other hand, line 5 is invalid, because ©g© does not produce a result, so requesting an ©int© to materialize from nothing is nonsensical.
Finally, line 8 is also invalid, because in C casts only provide conversion between scalar types \cite[p.~91]{C11}.
For consistency, this implies that any case wherein the number of components increases as a result of the cast is invalid, while casts that have the same or fewer number of components may be valid.

Formally, a cast to tuple type is valid when $T_n \leq S_m$, where $T_n$ is the number of components in the target type and $S_m$ is the number of components in the source type, and for each $i$ in $[0, n)$, $S_i$ can be cast to $T_i$.
Excess elements ($S_j$ for all $j$ in $[n, m)$) are evaluated, but their values are discarded so that they are not included in the result expression.
This discarding naturally follows the way that a cast to void works in C.

For example,
\begin{cfa}
	[int, int, int] f();
	[int, [int, int], int] g();

	([int, double])f(); $\C{// (1) valid}$
	([int, int, int])g(); $\C{// (2) valid}$
	([void, [int, int]])g(); $\C{// (3) valid}$
	([int, int, int, int])g(); $\C{// (4) invalid}$
	([int, [int, int, int]])g(); $\C{// (5) invalid}$
\end{cfa}

(1) discards the last element of the return value and converts the second element to type double.
Since ©int© is effectively a 1-element tuple, (2) discards the second component of the second element of the return value of ©g©.
If ©g© is free of side effects, this is equivalent to ©[(int)(g().0), (int)(g().1.0), (int)(g().2)]©.
Since ©void© is effectively a 0-element tuple, (3) discards the first and third return values, which is effectively equivalent to ©[(int)(g().1.0), (int)(g().1.1)]©).
% will this always hold true? probably, as constructors should give all of the conversion power we need. if casts become function calls, what would they look like? would need a way to specify the target type, which seems awkward. Also, C++ basically only has this because classes are closed to extension, while we don't have that problem (can have floating constructors for any type).
Note that a cast is not a function call in \CFA, so flattening and structuring conversions do not occur for cast expressions.
As such, (4) is invalid because the cast target type contains 4 components, while the source type contains only 3.
Similarly, (5) is invalid because the cast ©([int, int, int])(g().1)© is invalid.
That is, it is invalid to cast ©[int, int]© to ©[int, int, int]©.


\subsection{Polymorphism}

Due to the implicit flattening and structuring conversions involved in argument passing, ©otype© and ©dtype© parameters are restricted to matching only with non-tuple types.
The integration of polymorphism, type assertions, and monomorphic specialization of tuple-assertions are a primary contribution of this thesis to the design of tuples.
\begin{cfa}
forall(otype T, dtype U)
void f(T x, U * y);

f([5, "hello"]);
\end{cfa}
In this example, ©[5, "hello"]© is flattened, so that the argument list appears as ©5, "hello"©.
The argument matching algorithm binds ©T© to ©int© and ©U© to ©const char©, and calls the function as normal.

Tuples can contain otype and dtype components.
For example, a plus operator can be written to add two triples of a type together.
\begin{cfa}
forall(otype T | { T ?+?(T, T); })
[T, T, T] ?+?([T, T, T] x, [T, T, T] y) {
	return [x.0+y.0, x.1+y.1, x.2+y.2];
}
[int, int, int] x;
int i1, i2, i3;
[i1, i2, i3] = x + ([10, 20, 30]);
\end{cfa}
Note that due to the implicit tuple conversions, this function is not restricted to the addition of two triples.
A call to this plus operator type checks as long as a total of 6 non-tuple arguments are passed after flattening, and all of the arguments have a common type that can bind to ©T©, with a pairwise ©?+?© over ©T©.
For example, these expressions also succeed and produce the same value.
\begin{cfa}
([x.0, x.1]) + ([x.2, 10, 20, 30]);  // x + ([10, 20, 30])
x.0 + ([x.1, x.2, 10, 20, 30]);      // x + ([10, 20, 30])
\end{cfa}
This presents a potential problem if structure is important, as these three expressions look like they should have different meanings.
Furthermore, these calls can be made ambiguous by introducing seemingly different functions.
\begin{cfa}
forall(otype T | { T ?+?(T, T); })
[T, T, T] ?+?([T, T] x, [T, T, T, T]);
forall(otype T | { T ?+?(T, T); })
[T, T, T] ?+?(T x, [T, T, T, T, T]);
\end{cfa}
It is also important to note that these calls could be disambiguated if the function return types were different, as they likely would be for a reasonable implementation of ©?+?©, since the return type is used in overload resolution.
Still, these semantics are a deficiency of the current argument matching algorithm, and depending on the function, differing return values may not always be appropriate.
These issues could be rectified by applying an appropriate conversion cost to the structuring and flattening conversions, which are currently 0-cost conversions in the expression resolver.
Care would be needed in this case to ensure that exact matches do not incur such a cost.
\begin{cfa}
void f([int, int], int, int);

f([0, 0], 0, 0); $\C{// no cost}$
f(0, 0, 0, 0); $\C{// cost for structuring}$
f([0, 0,], [0, 0]); $\C{// cost for flattening}$
f([0, 0, 0], 0); $\C{// cost for flattening and structuring}$
\end{cfa}

Until this point, it has been assumed that assertion arguments must match the parameter type exactly, modulo polymorphic specialization (\ie, no implicit conversions are applied to assertion arguments).
This decision presents a conflict with the flexibility of tuples.


\subsubsection{Assertion Inference}

\begin{cfa}
int f([int, double], double);
forall(otype T, otype U | { T f(T, U, U); })
void g(T, U);
g(5, 10.21);
\end{cfa}
If assertion arguments must match exactly, then the call to ©g© cannot be resolved, since the expected type of ©f© is flat, while the only ©f© in scope requires a tuple type.
Since tuples are fluid, this requirement reduces the usability of tuples in polymorphic code.
To ease this pain point, function parameter and return lists are flattened for the purposes of type unification, which allows the previous example to pass expression resolution.

This relaxation is made possible by extending the existing thunk generation scheme, as described by Bilson \cite{Bilson03}.
Now, whenever a candidate's parameter structure does not exactly match the formal parameter's structure, a thunk is generated to specialize calls to the actual function.
\begin{cfa}
int _thunk(int _p0, double _p1, double _p2) {
	return f([_p0, _p1], _p2);
}
\end{cfa}
Essentially, this provides flattening and structuring conversions to inferred functions, improving the compatibility of tuples and polymorphism.


\section{Tuples}

In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
(More contexts are added shortly.)
A list of such elements is called a \newterm{lexical list}.
The general syntax of a lexical list is:
\begin{cfa}
[ $\emph{exprlist}$ ]
\end{cfa}
where ©$\emph{exprlist}$© is a list of one or more expressions separated by commas.
The brackets, ©[]©, allow differentiating between lexical lists and expressions containing the C comma operator.
The following are examples of lexical lists:
\begin{cfa}
[ x, y, z ]
[ 2 ]
[ v+w, x*y, 3.14159, f() ]
\end{cfa}
Tuples are permitted to contain sub-tuples (\ie nesting), such as ©[ [ 14, 21 ], 9 ]©, which is a 2-element tuple whose first element is itself a tuple.
Note, a tuple is not a record (structure);
a record denotes a single value with substructure, whereas a tuple is multiple values with no substructure \see{flattening coercion in \VRef{s:FlatteningStructuring}}.
In essence, tuples are largely a compile time phenomenon, having little or no runtime presence.

Tuples can be organized into compile-time tuple variables;
these variables are of \newterm{tuple type}.
Tuple variables and types can be used anywhere lists of conventional variables and types can be used.
The general syntax of a tuple type is:
\begin{cfa}
[ $\emph{typelist}$ ]
\end{cfa}
where ©$\emph{typelist}$© is a list of one or more legal \CFA or C type specifications separated by commas, which may include other tuple type specifications.
Examples of tuple types include:
\begin{cfa}
[ unsigned int, char ]
[ double, double, double ]
[ * int, int * ] $\C{// mix of CFA and ANSI}$
[ * [ 5 ] int, * * char, * [ [ int, int ] ] (int, int) ]
\end{cfa}
Like tuples, tuple types may be nested, such as ©[ [ int, int ], int ]©, which is a 2-element tuple type whose first element is itself a tuple type.

Examples of declarations using tuple types are:
\begin{cfa}
[ int, int ] x; $\C{// 2 element tuple, each element of type int}$
* [ char, char ] y; $\C{// pointer to a 2 element tuple}$
[ [ int, int ] ] z ([ int, int ]);
\end{cfa}
The last example declares an external routine that expects a 2 element tuple as an input parameter and returns a 2 element tuple as its result.

As mentioned, tuples can appear in contexts requiring a list of value, such as an argument list of a routine call.
In unambiguous situations, the tuple brackets may be omitted, \eg a tuple that appears as an argument may have its
square brackets omitted for convenience; therefore, the following routine invocations are equivalent:
\begin{cfa}
f( [ 1, x+2, fred() ] );
f( 1, x+2, fred() );
\end{cfa}
Also, a tuple or a tuple variable may be used to supply all or part of an argument list for a routine expecting multiple input parameters or for a routine expecting a tuple as an input parameter.
For example, the following are all legal:
\begin{cfa}
[ int, int ] w1;
[ int, int, int ] w2;
[ void ] f (int, int, int); $\C{// three input parameters of type int}$
[ void ] g ([ int, int, int ]); $\C{3 element tuple as input}$
f( [ 1, 2, 3 ] );
f( w1, 3 );
f( 1, w1 );
f( w2 );
g( [ 1, 2, 3 ] );
g( w1, 3 );
g( 1, w1 );
g( w2 );
\end{cfa}
Note, in all cases 3 arguments are supplied even though the syntax may appear to supply less than 3. As mentioned, a
tuple does not have structure like a record; a tuple is simply converted into a list of components.
\begin{rationale}
The present implementation of \CFA does not support nested routine calls when the inner routine returns multiple values; \ie a statement such as ©g( f() )© is not supported.
Using a temporary variable to store the  results of the inner routine and then passing this variable to the outer routine works, however.
\end{rationale}

A tuple can contain a C comma expression, provided the expression containing the comma operator is enclosed in parentheses.
For instance, the following tuples are equivalent:
\begin{cfa}
[ 1, 3, 5 ]
[ 1, (2, 3), 5 ]
\end{cfa}
The second element of the second tuple is the expression (2, 3), which yields the result 3.
This requirement is the same as for comma expressions in argument lists.

Type qualifiers, \ie const and volatile, may modify a tuple type.
The meaning is the same as for a type qualifier modifying an aggregate type [Int99, x 6.5.2.3(7),x 6.7.3(11)], \ie the qualifier is distributed across all of the types in the tuple, \eg:
\begin{cfa}
const volatile [ int, float, const int ] x;
\end{cfa}
is equivalent to:
\begin{cfa}
[ const volatile int, const volatile float, const volatile int ] x;
\end{cfa}
Declaration qualifiers can only appear at the start of a \CFA tuple declaration4, \eg:
\begin{cfa}
extern [ int, int ] w1;
static [ int, int, int ] w2;
\end{cfa}
\begin{rationale}
Unfortunately, C's syntax for subscripts precluded treating them as tuples.
The C subscript list has the form ©[i][j]...© and not ©[i, j, ...]©.
Therefore, there is no syntactic way for a routine returning multiple values to specify the different subscript values, \eg ©f[ g() ]© always means a single subscript value because there is only one set of brackets.
Fixing this requires a major change to C because the syntactic form ©M[i, j, k]© already has a particular meaning: ©i, j, k© is a comma expression.
\end{rationale}


\subsection{Tuple Coercions}

There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
In addition, the coercion of dereferencing can be performed on a tuple variable to yield its value(s), as for other variables.
A \newterm{closing coercion} takes a set of values and converts it into a tuple value, which is a contiguous set of values, as in:
\begin{cfa}
[ int, int, int, int ] w;
w = [ 1, 2, 3, 4 ];
\end{cfa}
First the right-hand tuple is closed into a tuple value and then the tuple value is assigned.

An \newterm{opening coercion} is the opposite of closing; a tuple value is converted into a tuple of values, as in:
\begin{cfa}
[ a, b, c, d ] = w
\end{cfa}
©w© is implicitly opened to yield a tuple of four values, which are then assigned individually.

A \newterm{flattening coercion} coerces a nested tuple, \ie a tuple with one or more components, which are themselves tuples, into a flattened tuple, which is a tuple whose components are not tuples, as in:
\begin{cfa}
[ a, b, c, d ] = [ 1, [ 2, 3 ], 4 ];
\end{cfa}
First the right-hand tuple is flattened and then the values are assigned individually.
Flattening is also performed on tuple types.
For example, the type ©[ int, [ int, int ], int ]© can be coerced, using flattening, into the type ©[ int, int, int, int ]©.

A \newterm{structuring coercion} is the opposite of flattening;
a tuple is structured into a more complex nested tuple.
For example, structuring the tuple ©[ 1, 2, 3, 4 ]© into the tuple ©[ 1, [ 2, 3 ], 4 ]© or the tuple type ©[ int, int, int, int ]© into the tuple type ©[ int, [ int, int ], int ]©.
In the following example, the last assignment illustrates all the tuple coercions:
\begin{cfa}
[ int, int, int, int ] w = [ 1, 2, 3, 4 ];
int x = 5;
[ x, w ] = [ w, x ]; $\C{// all four tuple coercions}$
\end{cfa}
Starting on the right-hand tuple in the last assignment statement, w is opened, producing a tuple of four values;
therefore, the right-hand tuple is now the tuple ©[ [ 1, 2, 3, 4 ], 5 ]©.
This tuple is then flattened, yielding ©[ 1, 2, 3, 4, 5 ]©, which is structured into ©[ 1, [ 2, 3, 4, 5 ] ]© to match the tuple type of the left-hand side.
The tuple ©[ 2, 3, 4, 5 ]© is then closed to create a tuple value.
Finally, ©x© is assigned ©1© and ©w© is assigned the tuple value using \Index{multiple assignment} \see{\VRef{s:TupleAssignment}}.
\begin{rationale}
A possible additional language extension is to use the structuring coercion for tuples to initialize a complex record with a tuple.
\end{rationale}


\subsection{Mass Assignment}

\CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
Mass assignment has the following form:
\begin{cfa}
[ $\emph{lvalue}$, ... , $\emph{lvalue}$ ] = $\emph{expr}$;
\end{cfa}
\index{lvalue}
The left-hand side is a tuple of \emph{lvalues}, which is a list of expressions each yielding an address, \ie any data object that can appear on the left-hand side of a conventional assignment statement.
©$\emph{expr}$© is any standard arithmetic expression.
Clearly, the types of the entities being assigned must be type compatible with the value of the expression.

Mass assignment has parallel semantics, \eg the statement:
\begin{cfa}
[ x, y, z ] = 1.5;
\end{cfa}
is equivalent to:
\begin{cfa}
x = 1.5; y = 1.5; z = 1.5;
\end{cfa}
This semantics is not the same as the following in C:
\begin{cfa}
x = y = z = 1.5;
\end{cfa}
as conversions between intermediate assignments may lose information.
A more complex example is:
\begin{cfa}
[ i, y[i], z ] = a + b;
\end{cfa}
which is equivalent to:
\begin{cfa}
t = a + b;
a1 = &i; a2 = &y[i]; a3 = &z;
*a1 = t; *a2 = t; *a3 = t;
\end{cfa}
The temporary ©t© is necessary to store the value of the expression to eliminate conversion issues.
The temporaries for the addresses are needed so that locations on the left-hand side do not change as the values are assigned.
In this case, ©y[i]© uses the previous value of ©i© and not the new value set at the beginning of the mass assignment.


\subsection{Multiple Assignment}

\CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
Multiple assignment has the following form:
\begin{cfa}
[ $\emph{lvalue}$, ... , $\emph{lvalue}$ ] = [ $\emph{expr}$, ... , $\emph{expr}$ ];
\end{cfa}
\index{lvalue}
The left-hand side is a tuple of \emph{lvalues}, and the right-hand side is a tuple of \emph{expr}s.
Each \emph{expr} appearing on the right-hand side of a multiple assignment statement is assigned to the corresponding \emph{lvalues} on the left-hand side of the statement using parallel semantics for each assignment.
An example of multiple assignment is:
\begin{cfa}
[ x, y, z ] = [ 1, 2, 3 ];
\end{cfa}
Here, the values ©1©, ©2© and ©3© are assigned, respectively, to the variables ©x©, ©y© and ©z©.
 A more complex example is:
\begin{cfa}
[ i, y[ i ], z ] = [ 1, i, a + b ];
\end{cfa}
Here, the values ©1©, ©i© and ©a + b© are assigned to the variables ©i©, ©y[i]© and ©z©, respectively.
 Note, the parallel semantics of
multiple assignment ensures:
\begin{cfa}
[ x, y ] = [ y, x ];
\end{cfa}
correctly interchanges (swaps) the values stored in ©x© and ©y©.
The following cases are errors:
\begin{cfa}
[ a, b, c ] = [ 1, 2, 3, 4 ];
[ a, b, c ] = [ 1, 2 ];
\end{cfa}
because the number of entities in the left-hand tuple is unequal with the right-hand tuple.

As for all tuple contexts in C, side effects should not be used because C does not define an ordering for the evaluation of the elements of a tuple;
both these examples produce indeterminate results:
\begin{cfa}
f( x++, x++ ); $\C{// C routine call with side effects in arguments}$
[ v1, v2 ] = [ x++, x++ ]; $\C{// side effects in right-hand side of multiple assignment}$
\end{cfa}


\subsection{Cascade Assignment}

As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
Cascade assignment has the following form:
\begin{cfa}
$\emph{tuple}$ = $\emph{tuple}$ = ... = $\emph{tuple}$;
\end{cfa}
and it has the same parallel semantics as for mass and multiple assignment.
Some examples of cascade assignment are:
\begin{cfa}
x1 = y1 = x2 = y2 = 0;
[ x1, y1 ] = [ x2, y2 ] = [ x3, y3 ];
[ x1, y1 ] = [ x2, y2 ] = 0;
[ x1, y1 ] = z = 0;
\end{cfa}
As in C, the rightmost assignment is performed first, \ie assignment parses right to left.


\section{Stream I/O Library}
\label{s:StreamIOLibrary}
\index{input/output stream library}
\index{stream library}

The goal of \CFA stream input/output (I/O) is to simplify the common cases\index{I/O!common case}, while fully supporting polymorphism and user defined types in a consistent way.
Stream I/O can be implicitly or explicitly formatted.
Implicit formatting means \CFA selects the output or input format for values that match with the type of a variable.
Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
\CFA formatting is a cross between C ©printf© and \CC ©cout© manipulators, and Python implicit spacing and newline.
Specifically:
\begin{itemize}
\item
©printf©/Python format codes are dense, making them difficult to read and remember.
\CFA/\CC format manipulators are named, making them easier to read and remember.
\item
©printf©/Python separates format codes from associated variables, making it difficult to match codes with variables.
\CFA/\CC co-locate codes with associated variables, where \CFA has the tighter binding.
\item
Format manipulators in \CFA have local effect, whereas \CC have global effect, except ©setw©.
Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
(To guarantee no side-effects, manipulator values must be saved and restored across function calls.)
\item
\CFA has more sophisticated implicit spacing between values than Python, plus implicit newline at the end of a print.
\end{itemize}
The \CFA header file for the I/O library is \Indexc{fstream.hfa}.

For implicit formatted output, the common case is printing a series of variables separated by whitespace.
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{2em}}l@{\hspace{2em}}l@{}}
\multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CC}}	& \multicolumn{1}{c}{\textbf{Python}}	\\
\begin{cfa}
int x = 1, y = 2, z = 3;
sout | x @|@ y @|@ z;
\end{cfa}
&
\begin{cfa}

cout << x @<< " "@ << y @<< " "@ << z << endl;
\end{cfa}
&
\begin{cfa}
x = 1;  y = 2;  z = 3
print( x, y, z )
\end{cfa}
\\
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1@ @2@ @3
\end{cfa}
&
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1@ @2@ @3
\end{cfa}
&
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1@ @2@ @3
\end{cfa}
\end{tabular}
\end{cquote}
The \CFA form has half the characters of the \CC form, and is similar to \Index*{Python} I/O with respect to implicit separators and newline.
Similar simplification occurs for \Index{tuple} I/O, which flattens the tuple and prints each value separated by ``\lstinline[showspaces=true]@, @''.
\begin{cfa}
[int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
sout | t1 | t2; $\C{// print tuples}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt]
1@, @2@, @3 4@, @5@, @6
\end{cfa}
Finally, \CFA uses the logical-or operator for I/O as it is the lowest-priority \emph{overloadable} operator, other than assignment.
Therefore, fewer output expressions require parenthesis.
\begin{cquote}
\begin{tabular}{@{}ll@{}}
\textbf{\CFA:}
&
\begin{cfa}
sout | x * 3 | y + 1 | z << 2 | x == y | @(@x | y@)@ | @(@x || y@)@ | @(@x > z ? 1 : 2@)@;
\end{cfa}
\\
\textbf{\CC:}
&
\begin{cfa}
cout << x * 3 << y + 1 << @(@z << 2@)@ << @(@x == y@)@ << @(@x | y@)@ << @(@x || y@)@ << @(@x > z ? 1 : 2@)@ << endl;
\end{cfa}
\\
&
\begin{cfa}[showspaces=true,aboveskip=0pt]
3 3 12 0 3 1 2
\end{cfa}
\end{tabular}
\end{cquote}
Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.
There is a weak similarity between the \CFA logical-or operator and the \Index{Shell pipe-operator} for moving data, where data flows in the correct direction for input but the opposite direction for output.

For implicit formatted input, the common case is reading a sequence of values separated by whitespace, where the type of an input constant must match with the type of the input variable.
\begin{cquote}
\begin{lrbox}{\myboxA}
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
int x;   double y   char z;
\end{cfa}
\end{lrbox}
\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{3em}}l@{}}
\multicolumn{1}{@{}l@{}}{\usebox\myboxA} \\
\multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CFA}}	& \multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CC}}	& \multicolumn{1}{c}{\textbf{Python}}	\\
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
sin | x | y | z;
\end{cfa}
&
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
cin >> x >> y >> z;
\end{cfa}
&
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
x = int(input());  y = float(input());  z = input();
\end{cfa}
\\
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@1@ @2.5@ @A@


\end{cfa}
&
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@1@ @2.5@ @A@


\end{cfa}
&
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@1@
@2.5@
@A@
\end{cfa}
\end{tabular}
\end{cquote}



\subsection{Implicit Separator}

The \Index{implicit separator}\index{I/O!separator} character (space/blank) is a separator not a terminator for output.
The rules for implicitly adding the separator are:
\begin{enumerate}
\item
A separator does not appear at the start or end of a line.
\begin{cfa}[belowskip=0pt]
sout | 1 | 2 | 3;
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1 2 3
\end{cfa}

\item
A separator does not appear before or after a character literal or variable.
\begin{cfa}
sout | '1' | '2' | '3';
123
\end{cfa}

\item
A separator does not appear before or after a null (empty) C string, which is a local mechanism to disable insertion of the separator character.
\begin{cfa}
sout | 1 | "" | 2 | "" | 3;
123
\end{cfa}

\item
A separator does not appear before a C string starting with the (extended) \Index*{ASCII}\index{ASCII!extended} characters: \LstStringStyle{,.;!?)]\}\%\textcent\guillemotright}, where \LstStringStyle{\guillemotright} a closing citation mark.
\begin{cfa}
sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
	   | 7 | "$\LstStringStyle{\textcent}$ x" | 8 | "$\LstStringStyle{\guillemotright}$ x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
\end{cfa}
\begin{cfa}[showspaces=true]
1@,@ x 2@.@ x 3@;@ x 4@!@ x 5@?@ x 6@%@ x 7$\R{\LstStringStyle{\textcent}}$ x 8$\R{\LstStringStyle{\guillemotright}}$ x 9@)@ x 10@]@ x 11@}@ x
\end{cfa}

\item
A separator does not appear after a C string ending with the (extended) \Index*{ASCII}\index{ASCII!extended} characters: \LstStringStyle{([\{=\$\textsterling\textyen\textexclamdown\textquestiondown\guillemotleft}, where \LstStringStyle{\textexclamdown\textquestiondown} are inverted opening exclamation and question marks, and \LstStringStyle{\guillemotleft} is an opening citation mark.
%$
\begin{cfa}
sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x $\LstStringStyle{\textsterling}$" | 6 | "x $\LstStringStyle{\textyen}$"
	   | 7 | "x $\LstStringStyle{\textexclamdown}$" | 8 | "x $\LstStringStyle{\textquestiondown}$" | 9 | "x $\LstStringStyle{\guillemotleft}$" | 10;
\end{cfa}
%$
\begin{cfa}[showspaces=true]
x @(@1 x @[@2 x @{@3 x @=@4 x $\LstStringStyle{\textdollar}$5 x $\R{\LstStringStyle{\textsterling}}$6 x $\R{\LstStringStyle{\textyen}}$7 x $\R{\LstStringStyle{\textexclamdown}}$8 x $\R{\LstStringStyle{\textquestiondown}}$9 x $\R{\LstStringStyle{\guillemotleft}}$10
\end{cfa}
%$

\item
A seperator does not appear before/after a C string starting/ending with the \Index*{ASCII} quote or whitespace characters: \lstinline[basicstyle=\tt,showspaces=true]{`'": \t\v\f\r\n}
\begin{cfa}
sout | "x`" | 1 | "`x'" | 2 | "'x\"" | 3 | "\"x:" | 4 | ":x " | 5 | " x\t" | 6 | "\tx";
\end{cfa}
\begin{cfa}[showspaces=true,showtabs=true]
x@`@1@`@x$\R{\texttt{'}}$2$\R{\texttt{'}}$x$\R{\texttt{"}}$3$\R{\texttt{"}}$x@:@4@:@x@ @5@ @x@	@6@	@x
\end{cfa}

\item
If a space is desired before or after one of the special string start/end characters, simply insert a space.
\begin{cfa}
sout | "x ($\R{\texttt{\textvisiblespace}}$" | 1 | "$\R{\texttt{\textvisiblespace}}$) x" | 2 | "$\R{\texttt{\textvisiblespace}}$, x" | 3 | "$\R{\texttt{\textvisiblespace}}$:x:$\R{\texttt{\textvisiblespace}}$" | 4;
\end{cfa}
\begin{cfa}[showspaces=true,showtabs=true]
x (@ @1@ @) x 2@ @, x 3@ @:x:@ @4
\end{cfa}
\end{enumerate}


\subsection{Separation Manipulators}

The following \Index{manipulator}s control \Index{implicit output separation}.
The effect of these manipulators is global for an output stream (except ©sepOn© and ©sepOff©).
\begin{enumerate}
\item
\Indexc{sepSet}\index{manipulator!sepSet@©sepSet©} and \Indexc{sep}\index{manipulator!sep@©sep©}/\Indexc{sepGet}\index{manipulator!sepGet@©sepGet©} set and get the separator string.
The separator string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
\begin{cfa}[escapechar=off,belowskip=0pt]
sepSet( sout, ", $" ); $\C{// set separator from " " to ", \$"}$
sout | 1 | 2 | 3 | " \"" | @sep@ | "\"";
\end{cfa}
%$
\begin{cfa}[mathescape=off,showspaces=true,aboveskip=0pt]
1@, $@2@, $@3 @", $"@
\end{cfa}
%$
\begin{cfa}[belowskip=0pt]
sepSet( sout, " " ); $\C{// reset separator to " "}$
sout | 1 | 2 | 3 | " \"" | @sepGet( sout )@ | "\"";
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt]
1@ @2@ @3 @" "@
\end{cfa}
©sepGet© can be used to store a separator and then restore it:
\begin{cfa}[belowskip=0pt]
char store[@sepSize@]; $\C{// sepSize is the maximum separator size}$
strcpy( store, sepGet( sout ) ); $\C{// copy current separator}$
sepSet( sout, "_" ); $\C{// change separator to underscore}$
sout | 1 | 2 | 3;
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1@_@2@_@3
\end{cfa}
\begin{cfa}[belowskip=0pt]
sepSet( sout, store ); $\C{// change separator back to original}$
sout | 1 | 2 | 3;
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt]
1@ @2@ @3
\end{cfa}

\item
\Indexc{sepSetTuple}\index{manipulator!sepSetTuple@©sepSetTuple©} and \Indexc{sepTuple}\index{manipulator!sepTuple@©sepTuple©}/\Indexc{sepGetTuple}\index{manipulator!sepGetTuple@©sepGetTuple©} get and set the tuple separator-string.
The tuple separator-string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
\begin{cfa}[belowskip=0pt]
sepSetTuple( sout, " " ); $\C{// set tuple separator from ", " to " "}$
sout | t1 | t2 | " \"" | @sepTuple@ | "\"";
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt]
1 2 3 4 5 6 @" "@
\end{cfa}
\begin{cfa}[belowskip=0pt]
sepSetTuple( sout, ", " ); $\C{// reset tuple separator to ", "}$
sout | t1 | t2 | " \"" | @sepGetTuple( sout )@ | "\"";
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt]
1, 2, 3 4, 5, 6 @", "@
\end{cfa}
As for ©sepGet©, ©sepGetTuple© can be use to store a tuple separator and then restore it.

\item
\Indexc{sepDisable}\index{manipulator!sepDisable@©sepDisable©} and \Indexc{sepEnable}\index{manipulator!sepEnable@©sepEnable©} toggle printing the separator.
\begin{cfa}[belowskip=0pt]
sout | sepDisable | 1 | 2 | 3; $\C{// turn off implicit separator}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
123
\end{cfa}
\begin{cfa}[belowskip=0pt]
sout | sepEnable | 1 | 2 | 3; $\C{// turn on implicit separator}$
\end{cfa}
\begin{cfa}[mathescape=off,showspaces=true,aboveskip=0pt,belowskip=0pt]
1 2 3
\end{cfa}

\item
\Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} toggle printing the separator with respect to the next printed item, and then return to the global seperator setting.
\begin{cfa}[belowskip=0pt]
sout | 1 | sepOff | 2 | 3; $\C{// turn off implicit separator for the next item}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
12 3
\end{cfa}
\begin{cfa}[belowskip=0pt]
sout | sepDisable | 1 | sepOn | 2 | 3; $\C{// turn on implicit separator for the next item}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1 23
\end{cfa}
The tuple separator also responses to being turned on and off.
\begin{cfa}[belowskip=0pt]
sout | t1 | sepOff | t2; $\C{// turn off implicit separator for the next item}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1, 2, 34, 5, 6
\end{cfa}
©sepOn© \emph{cannot} be used to start/end a line with a separator because separators do not appear at the start/end of a line;
use ©sep© to accomplish this functionality.
\begin{cfa}[belowskip=0pt]
sout | sepOn | 1 | 2 | 3 | sepOn; $\C{// sepOn does nothing at start/end of line}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
1 2 3
\end{cfa}
\begin{cfa}[belowskip=0pt]
sout | sep | 1 | 2 | 3 | sep ; $\C{// use sep to print separator at start/end of line}$
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@ @1 2 3@ @
\end{cfa}
\end{enumerate}


\subsection{Newline Manipulators}

The following \Index{manipulators} control \Index{newline separation} for input and output.

For input:
\begin{enumerate}[parsep=0pt]
\item
\Indexc{nl}\index{manipulator!nl@©nl©} scans characters until the next newline character, \ie ignore the remaining characters in the line.
\item
\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} reads the newline character, when reading single characters.
\item
\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} read the newline character, when reading single characters.
\end{enumerate}
For example, in:
\begin{cfa}
sin | i | @nl@ | j;
1 @2@
3
\end{cfa}
variable ©i© is assigned 1, the 2 is skipped, and variable ©j© is assigned 3.

For output:
\begin{enumerate}[parsep=0pt]
\item
\Indexc{nl}\index{manipulator!nl@©nl©} inserts a newline.
\begin{cfa}
sout | nl; $\C{// only print newline}$
sout | 2; $\C{// implicit newline}$
sout | 3 | nl | 4 | nl; $\C{// terminating nl merged with implicit newline}$
sout | 5 | nl | nl; $\C{// again terminating nl merged with implicit newline}$
sout | 6; $\C{// implicit newline}$

2
3
4
5

6
\end{cfa}
Note, a terminating ©nl© is merged (overrides) with the implicit newline at the end of the ©sout© expression, otherwise it is impossible to to print a single newline
\item
\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} implicitly prints a newline at the end of each output expression.
\item
\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} implicitly print a newline at the end of each output expression.
\end{enumerate}


\subsection{Output Value Manipulators}

The following \Index{manipulator}s control formatting of output values (printing), and only affect the format of the argument.
\begin{enumerate}
\item
\Indexc{bin}( integer )\index{manipulator!bin@©bin©} print value in base 2 preceded by ©0b©/©0B©.
\begin{cfa}[belowskip=0pt]
sout | bin( 0 ) | bin( 27HH ) | bin( 27H ) | bin( 27 ) | bin( 27L );
0b0 0b11011 0b11011 0b11011 0b11011
sout | bin( -27HH ) | bin( -27H ) | bin( -27 ) | bin( -27L );
0b11100101 0b1111111111100101 0b11111111111111111111111111100101 0b@(58 1s)@100101
\end{cfa}

\item
\Indexc{oct}( integer )\index{manipulator!oct@©oct©} print value in base 8 preceded by ©0©.
\begin{cfa}[belowskip=0pt]
sout | oct( 0 ) | oct( 27HH ) | oct( 27H ) | oct( 27 ) | oct( 27L );
0 033 033 033 033
sout | oct( -27HH ) | oct( -27H ) | oct( -27 ) | oct( -27L );
0345 0177745 037777777745 01777777777777777777745
\end{cfa}
Note, octal 0 is \emph{not} preceded by ©0© to prevent confusion.

\item
\Indexc{hex}( integer / floating-point )\index{manipulator!hex@©hex©} print value in base 16 preceded by ©0x©/©0X©.
\begin{cfa}[belowskip=0pt]
sout | hex( 0 ) | hex( 27HH ) | hex( 27H ) | hex( 27 ) | hex( 27L );
0 0x1b 0x1b 0x1b 0x1b
sout | hex( -27HH ) | hex( -27H ) | hex( -27 ) | hex( -27L );
0xe5 0xffe5 0xffffffe5 0xffffffffffffffe5

sout | hex( 0.0 ) | hex( 27.5F ) | hex( 27.5 ) | hex( 27.5L );
0x0.p+0 0x1.b8p+4 0x1.b8p+4 0xd.cp+1
sout | hex( -27.5F ) | hex( -27.5 ) | hex( -27.5L );
-0x1.b8p+4 -0x1.b8p+4 -0xd.cp+1
\end{cfa}

\item
\Indexc{sci}( floating-point )\index{manipulator!sci@©sci©} print value in scientific notation with exponent.
Default is 6 digits of precision.
\begin{cfa}[belowskip=0pt]
sout | sci( 0.0 ) | sci( 27.5 ) | sci( -27.5 );
0.000000e+00 2.750000e+01 -2.750000e+01
\end{cfa}

\item
\Indexc{upcase}( bin / hex / floating-point )\index{manipulator!upcase@©upcase©} print letters in a value in upper case. Lower case is the default.
\begin{cfa}[belowskip=0pt]
sout | upcase( bin( 27 ) ) | upcase( hex( 27 ) ) | upcase( 27.5e-10 ) | upcase( hex( 27.5 ) );
0@B@11011 0@X@1@B@ 2.75@E@-09 0@X@1.@B@8@P@+4
\end{cfa}

\item
\Indexc{nobase}( integer )\index{manipulator!nobase@©nobase©} do not precede ©bin©, ©oct©, ©hex© with ©0b©/©0B©, ©0©, or ©0x©/©0X©.
Printing the base is the default.
\begin{cfa}[belowskip=0pt]
sout | nobase( bin( 27 ) ) | nobase( oct( 27 ) ) | nobase( hex( 27 ) );
11011 33 1b
\end{cfa}

\item
\Indexc{nodp}( floating-point )\index{manipulator!nodp@©nodp©} do not print a decimal point if there are no fractional digits.
Printing a decimal point is the default, if there are no fractional digits.
\begin{cfa}[belowskip=0pt]
sout | 0. | nodp( 0. ) | 27.0 | nodp( 27.0 ) | nodp( 27.5 );
0.0 @0@ 27.0 @27@ 27.5
\end{cfa}

\item
\Indexc{sign}( integer / floating-point )\index{manipulator!sign@©sign©} prefix with plus or minus sign (©+© or ©-©). Only printing the minus sign is the default.
\begin{cfa}[belowskip=0pt]
sout | sign( 27 ) | sign( -27 ) | sign( 27. ) | sign( -27. ) | sign( 27.5 ) | sign( -27.5 );
@+@27 -27 @+@27.0 -27.0 @+@27.5 -27.5
\end{cfa}

\item
\Indexc{wd}©( unsigned char minimum, T val )©\index{manipulator!wd@©wd©}, ©wd( unsigned char minimum, unsigned char precision, T val )©
For all types, ©minimum© is the minimum number of printed characters.
If the value is shorter than the minimum, it is padded on the right with spaces.
\begin{cfa}[belowskip=0pt]
sout | wd( 4, 34) | wd( 3, 34 ) | wd( 2, 34 );
sout | wd( 10, 4.) | wd( 9, 4. ) | wd( 8, 4. );
sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@  @34 @ @34 34
@  @4.000000 @ @4.000000 4.000000
@  @ab @ @ab ab
\end{cfa}
If the value is larger, it is printed without truncation, ignoring the ©minimum©.
\begin{cfa}[belowskip=0pt]
sout | wd( 4, 34567 ) | wd( 3, 34567 ) | wd( 2, 34567 );
sout | wd( 4, 3456. ) | wd( 3, 3456. ) | wd( 2, 3456. );
sout | wd( 4, "abcde" ) | wd( 3, "abcde" ) | wd( 2,"abcde" );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
3456@7@ 345@67@ 34@567@
3456@.@ 345@6.@ 34@56.@
abcd@e@ abc@de@ ab@cde@
\end{cfa}

For integer types, ©precision© is the minimum number of printed digits.
If the value is shorter, it is padded on the left with leading zeros.
\begin{cfa}[belowskip=0pt]
sout | wd( 4,3, 34 ) | wd( 8,4, 34 ) | wd( 10,10, 34 );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
 @0@34     @00@34 @00000000@34
\end{cfa}
If the value is larger, it is printed without truncation, ignoring the ©precision©.
\begin{cfa}[belowskip=0pt]
sout | wd( 4,1, 3456 ) | wd( 8,2, 3456 ) | wd( 10,3, 3456 );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
3456     3456       3456
\end{cfa}
If ©precision© is 0, nothing is printed for zero.
If ©precision© is greater than the minimum, it becomes the minimum.
\begin{cfa}[belowskip=0pt]
sout | wd( 4,0, 0 ) | wd( 3,10, 34 );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@    @ @00000000@34
\end{cfa}
For floating-point types, ©precision© is the minimum number of digits after the decimal point.
\begin{cfa}[belowskip=0pt]
sout | wd( 6,3, 27.5 ) | wd( 8,1, 27.5 ) | wd( 8,0, 27.5 ) | wd( 3,8, 27.5 );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27.@500@     27.@5@      28. 27.@50000000@
\end{cfa}
For the C-string type, ©precision© is the maximum number of printed characters, so the string is truncated if it exceeds the maximum.
\begin{cfa}[belowskip=0pt]
sout | wd( 6,8, "abcd" ) | wd( 6,8, "abcdefghijk" ) | wd( 6,3, "abcd" );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
  abcd abcdefgh    abc
\end{cfa}

\item
\Indexc{ws( unsigned char minimum, unsigned char significant, floating-point )}\index{manipulator!ws@©ws©}
For floating-point type, ©minimum© is the same as for manipulator ©wd©, but ©significant© is the maximum number of significant digits to be printed for both the integer and fractions (versus only the fraction for ©wd©).
If a value's significant digits is greater than ©significant©, the last significant digit is rounded up.
\begin{cfa}[belowskip=0pt]
sout | ws(6,6, 234.567) | ws(6,5, 234.567) | ws(6,4, 234.567) | ws(6,3, 234.567);
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
234.567 234.5@7@  234.@6@    23@5@
\end{cfa}
If a value's magnitude is greater than ©significant©, the value is printed in scientific notation with the specified number of significant digits.
\begin{cfa}[belowskip=0pt]
sout | ws(6,6, 234567.) | ws(6,5, 234567.) | ws(6,4, 234567.) | ws(6,3, 234567.);
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
234567. 2.3457@e+05@ 2.346@e+05@ 2.35@e+05@
\end{cfa}
If ©significant© is greater than ©minimum©, it defines the number of printed characters.
\begin{cfa}[belowskip=0pt]
sout | ws(3,6, 234567.) | ws(4,6, 234567.) | ws(5,6, 234567.) | ws(6,6, 234567.);
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
234567. 234567. 234567. 234567.
\end{cfa}

\item
\Indexc{left}( field-width )\index{manipulator!left@©left©} left justify within the given field.
\begin{cfa}[belowskip=0pt]
sout | left(wd(4, 27)) | left(wd(10, 27.)) | left(wd(10, 27.5)) | left(wd(4,3, 27)) | left(wd(10,3, 27.5));
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27@  @ 27.000000  27.500000  027  27.500@    @
\end{cfa}

\item
\Indexc{pad0}( field-width )\index{manipulator!pad0@©pad0©} left pad with zeroes (0).
\begin{cfa}[belowskip=0pt]
sout | pad0( wd( 4, 27 ) ) | pad0( wd( 4,3, 27 ) ) | pad0( wd( 8,3, 27.5 ) );
@00@27  @0@27 @00@27.500
\end{cfa}
\end{enumerate}

\begin{comment}
#include <fstream>
#include <string.h>										// strcpy

int main( void ) {
	int x = 1, y = 2, z = 3;
	sout | x | y | z;
	[int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
	sout | t1 | t2;						// print tuples
	sout | x * 3 | y + 1 | z << 2 | x == y | (x | y) | (x || y) | (x > z ? 1 : 2);
	sout | 1 | 2 | 3;
	sout | '1' | '2' | '3';
	sout | 1 | "" | 2 | "" | 3;
	sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x £" | 6 | "x ¥"
		| 7 | "x ¡" | 8 | "x ¿" | 9 | "x «" | 10;
	sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
		| 7 | "¢ x" | 8 | "» x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
	sout | "x`" | 1 | "`x'" | 2 | "'x\"" | 3 | "\"x:" | 4 | ":x " | 5 | " x\t" | 6 | "\tx";
	sout | "x ( " | 1 | " ) x" | 2 | " , x" | 3 | " :x: " | 4;

	sepSet( sout, ", $" );						// set separator from " " to ", $"
	sout | 1 | 2 | 3 | " \"" | sep | "\"";
	sepSet( sout, " " );						// reset separator to " "
	sout | 1 | 2 | 3 | " \"" | sepGet( sout ) | "\"";

	char store[sepSize];
	strcpy( store, sepGet( sout ) );
	sepSet( sout, "_" );
	sout | 1 | 2 | 3;
	sepSet( sout, store );
	sout | 1 | 2 | 3;

	sepSetTuple( sout, " " );					// set tuple separator from ", " to " "
	sout | t1 | t2 | " \"" | sepTuple | "\"";
	sepSetTuple( sout, ", " );					// reset tuple separator to ", "
	sout | t1 | t2 | " \"" | sepGetTuple( sout ) | "\"";

	sout | sepDisable | 1 | 2 | 3;		// globally turn off implicit separator
	sout | sepEnable | 1 | 2 | 3;		// globally turn on implicit separator

	sout | 1 | sepOff | 2 | 3;			// locally turn on implicit separator
	sout | sepDisable | 1 | sepOn | 2 | 3; // globally turn off implicit separator
	sout | sepEnable;
	sout | t1 | sepOff | t2;				// locally turn on/off implicit separator

	sout | sepOn | 1 | 2 | 3 | sepOn ;	// sepOn does nothing at start/end of line
	sout | sep | 1 | 2 | 3 | sep ;		// use sep to print separator at start/end of line
}

// Local Variables: //
// tab-width: 4 //
// fill-column: 100 //
// End: //
\end{comment}
%$


\subsection{Input Value Manipulators}

The format of numeric input values in the same as C constants without a trailing type suffix, as the input value-type is denoted by the input variable.
For ©_Bool© type, the constants are ©true© and ©false©.
For integral types, any number of digits, optionally preceded by a sign (©+© or ©-©), where a
\begin{itemize}
\item
©1©-©9© prefix introduces a decimal value (©0©-©9©),
\item
©0© prefix introduces an octal value (©0©-©7©), and
\item
©0x© or ©0X© prefix introduces a hexadecimal value (©0©-©f©) with lower or upper case letters.
\end{itemize}
For floating-point types, any number of decimal digits, optionally preceded by a sign (©+© or ©-©), optionally containing a decimal point, and optionally followed by an exponent, ©e© or ©E©, with signed (optional) decimal digits.
Floating-point values can also be written in hexadecimal format preceded by ©0x© or ©0X© with hexadecimal digits and exponent denoted by ©p© or ©P©.

For the C-string type, the input values are \emph{not} the same as C-string constants, \ie double quotes bracketing arbitrary text with escape sequences.
Instead, the next sequence of non-whitespace characters are read, and the input sequence is terminated with delimiter ©'\0'©.
The string variable \emph{must} be large enough to contain the input sequence.

The following \Index{manipulator}s control formatting of input values (reading), and only affect the format of the argument.

\begin{enumerate}
\item
\Indexc{skip( const char * pattern )}\index{manipulator!skip@©skip©} / ©skip( unsigned int length )© / ©const char * pattern©
The argument defines a ©pattern© or ©length©.
The ©pattern© is composed of white-space and non-white-space characters, where \emph{any} white-space character matches 0 or more input white-space characters (hence, consecutive white-space characters in the pattern are combined), and each non-white-space character matches exactly with an input character.
The ©length© is composed of the next $N$ characters, including the newline character.
If the match successes, the input characters are discarded, and input continues with the next character.
If the match fails, the input characters are left unread.
\begin{cfa}[belowskip=0pt]
char sk[$\,$] = "abc";
sin | "abc " | skip( sk ) | skip( 5 ); // match input sequence
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@abc   @
@abc  @
@xx@
\end{cfa}

\item
\Indexc{wdi}©( unsigned int maximum, T & val )©\index{manipulator!wdi@©wdi©}
For all types except ©char©, ©maximum© is the maximum number of characters read for the current operation.
\begin{cfa}[belowskip=0pt]
char s[10];   int i;   double d;   
sin | wdi( 4, s ) | wdi( 3, i ) | wdi( 8, d );  // c == "abcd", i == 123, d == 3.456E+2
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@abcd1233.456E+2@
\end{cfa}
Note, input ©wdi© cannot be overloaded with output ©wd© because both have the same parameters but return different types.
Currently, \CFA cannot distinguish between these two manipulators in the middle of an ©sout©/©sin© expression based on return type.

\item
\Indexc{ignore( T & val )}\index{manipulator!ignore@©ignore©}
For all types, the data is read from the stream depending on the argument type but ignored, \ie it is not stored in the argument.
\begin{cfa}[belowskip=0pt]
double d;
sin | ignore( d );  // d is unchanged
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@  -75.35e-4@ 25
\end{cfa}

\item
\Indexc{incl( const char * scanset, char * s )}\index{manipulator!incl@©incl©}
For the C-string type, the argument defines a ©scanset© that matches any number of characters \emph{in} the set.
Matching characters are read into the C string and null terminated.
\begin{cfa}[belowskip=0pt]
char s[10];
sin | incl( "abc", s );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@bca@xyz
\end{cfa}

\item
\Indexc{excl( const char * scanset, char * s )}\index{manipulator!excl@©excl©}
For the C-string type, the argument defines a ©scanset© that matches any number of characters \emph{not in} the set.
Non-matching characters are read into the C string and null terminated.
\begin{cfa}[belowskip=0pt]
char s[10];
sin | excl( "abc", s );
\end{cfa}
\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@xyz@bca
\end{cfa}
\end{enumerate}


\subsection{Concurrent Stream Access}

When a stream is shared by multiple threads, input or output characters can be intermixed or cause failure.
For example, if two threads execute the following:
\begin{cfa}
$\emph{thread\(_1\)}$ : sout | "abc " | "def ";
$\emph{thread\(_2\)}$ : sout | "uvw " | "xyz ";
\end{cfa}
possible outputs are:
\begin{cquote}
\begin{tabular}{@{}l|l|l|l|l@{}}
\begin{cfa}
abc def
uvw xyz 
\end{cfa}
&
\begin{cfa}
abc uvw xyz 
def 
\end{cfa}
&
\begin{cfa}
uvw abc xyz def

\end{cfa}
&
\begin{cfa}
abuvwc dexf
yz
\end{cfa}
&
\begin{cfa}
uvw abc def 
xyz 
\end{cfa}
\end{tabular}
\end{cquote}
Concurrent operations can even corrupt the internal state of the stream resulting in failure.
As a result, some form of mutual exclusion is required for concurrent stream access.

A coarse-grained solution is to perform all stream operations via a single thread or within a monitor providing the necessary mutual exclusion for the stream.
A fine-grained solution is to have a lock for each stream, which is acquired and released around stream operations by each thread.
\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, with the manipulator appearing as the first item in a cascade list, \eg:
\begin{cfa}
$\emph{thread\(_1\)}$ : sout | @acquire@ | "abc " | "def ";   // manipulator
$\emph{thread\(_2\)}$ : sout | @acquire@ | "uvw " | "xyz ";
\end{cfa}
Now, the order of the thread execution is still non-deterministic, but the output is constrained to two possible lines in either order.
\begin{cquote}
\def\VRfont{\fontfamily{pcr}\upshape\selectfont}
\begin{tabular}{@{}l|l@{}}
\begin{cfa}
abc def
uvw xyz
\end{cfa}
&
\begin{cfa}
uvw xyz
abc def
\end{cfa}
\end{tabular}
\end{cquote}
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, 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
	@osacquire@ acq = { sout };				$\C{// named stream locker}$
	sout | 1;
	sout | @acquire@ | 2 | 3;				$\C{// unnecessary, but ok to acquire and release again}$
	sout | 4;
}	// implicitly release the lock when "acq" is deallocated
\end{cfa}
Note, the unnecessary ©acquire© manipulator works because the recursive stream-lock can be acquired/released multiple times by the owner thread.
Hence, calls to functions that also acquire a stream lock for their output do not result in \Index{deadlock}.

The previous values written by threads 1 and 2 can be read in concurrently:
\begin{cfa}
{	// acquire sin lock for block duration
	@isacquire acq = { sin };@				$\C{// named stream locker}$
	int x, y, z, w;
	sin | x;
	sin | @acquire@ | y | z;				$\C{// unnecessary, but ok to acquire and release again}$
	sin | w;
}	// implicitly release the lock when "acq" is deallocated
\end{cfa}
Again, the order of the reading threads is non-deterministic.
Note, non-deterministic reading is rare.

\Textbf{WARNING:} The general problem of \Index{nested locking} can occur if routines are called in an I/O sequence that block, \eg:
\begin{cfa}
sout | @acquire@ | "data:" | rtn( mon );	$\C{// mutex call on monitor}$
\end{cfa}
If the thread executing the I/O expression blocks in the monitor with the ©sout© lock, other threads writing to ©sout© also block until the thread holding the lock is unblocked and releases it.
This scenario can lead to \Index{deadlock}, if the thread that is going to unblock the thread waiting in the monitor first writes to ©sout© (deadly embrace).
To prevent nested locking, a simple precaution is to factor out the blocking call from the expression, \eg:
\begin{cfa}
int @data@ = rtn( mon );
sout | acquire | "data:" | @data@;
\end{cfa}

\Textbf{WARNING:} ©printf©\index{printf@©printf©}, ©scanf©\index{scanf@©scanf©} and their derivatives are unsafe when used with user-level threading, as in \CFA.
These stream routines use kernel-thread locking (©futex©\index{futex@©futex©}), which block kernel threads, to prevent interleaving of I/O.
However, the following simple example illustrates how a deadlock can occur (other complex scenarios are possible).
Assume a single kernel thread and two user-level threads calling ©printf©.
One user-level thread acquires the I/O lock and is time-sliced while performing ©printf©.
The other user-level thread then starts execution, calls ©printf©, and blocks the only kernel thread because it cannot acquire the I/O lock.
It does not help if the kernel lock is multiple acquisition, \ie, the lock owner can acquire it multiple times, because it then results in two user threads in the ©printf© critical section, corrupting the stream.


\begin{comment}
\section{Types}

\subsection{Type Definitions}

\CFA allows users to define new types using the keyword type.

\begin{cfa}
// SensorValue is a distinct type and represented as an int
type SensorValue = int;
\end{cfa}

A type definition is different from a typedef in C because a typedef just creates an alias for a type,  while Do.s type definition creates a distinct type.
This means that users can define distinct function overloads for the new type \see{\VRef{s:Overloading} for more information}.
For example:

\begin{cfa}
type SensorValue = int;
void printValue(int v) {...}
void printValue(SensorValue v) {...}
void process(int v) {...}

SensorValue s = ...;

printValue(s); // calls version with SensorValue argument

printValue((int) s); // calls version with int argument

process(s); // implicit conversion to int
\end{cfa}

If SensorValue was defined with a typedef, then these two print functions would not have unique signatures.
This can be very useful to create a distinct type that has the same representation as another type.

The compiler will assume it can safely convert from the old type to the new type, implicitly.
Users may override this and define a function that must be called to convert from one type to another.

\begin{cfa}
type SensorValue = int;
// ()? is the overloaded conversion operator identifier
// This function converts an int to a SensorValue
SensorValue ()?(int val) {
	...
}
void process(int v) {...}

SensorValue s = ...;
process(s); // implicit call to conversion operator
\end{cfa}

In many cases, it is not desired for the compiler to do this implicit conversion.
To avoid that, the user can use the explicit modifier on the conversion operator.
Any places where the conversion is needed but not explicit (with a cast), will result in a compile-time error.

\begin{cfa}
type SensorValue = int;

// conversion from int to SensorValue; must be explicit
explicit SensorValue ()?(int val) {
	...
}

void process(int v) {...}

SensorValue s = ...;
process(s); // implicit cast to int: compile-time error
process((int) s); // explicit cast to int: calls conversion func
\end{cfa}

The conversion may not require any code, but still need to be explicit; in that case, the syntax can be simplified to:
\begin{cfa}
type SensorValue = int;
explicit SensorValue ()?(int);
void process(int v) {...}

SensorValue s = ...;
process(s); // compile-time error
process((int) s); // type is converted, no function is called
\end{cfa}
\end{comment}


\subsection{Structures}

Structures in \CFA are basically the same as structures in C.
A structure is defined with the same syntax as in C.
When referring to a structure in \CFA, users may omit the struct keyword.
\begin{cfa}
struct Point {
	double x;
	double y;
};

Point p = {0.0, 0.0};
\end{cfa}

\CFA does not support inheritance among types, but instead uses composition to enable reuse of structure fields.
Composition is achieved by embedding one type into another.
When type A is embedded in type B, an object with type B may be used as an object of type A, and the fields of type A are directly accessible.
Embedding types is achieved using anonymous members.
For example, using Point from above:
\begin{cfa}
void foo(Point p);

struct ColoredPoint {
	Point; // anonymous member (no identifier)
	int Color;
};
...
	ColoredPoint cp = ...;
	cp.x = 10.3; // x from Point is accessed directly
	cp.color = 0x33aaff; // color is accessed normally
	foo(cp); // cp can be used directly as a Point
\end{cfa}


\section{Constructors and Destructors}

\CFA supports C initialization of structures, but it also adds constructors for more advanced initialization.
Additionally, \CFA adds destructors that are called when a variable is deallocated (variable goes out of scope or object is deleted).
These functions take a reference to the structure as a parameter \see{\VRef{s:PointerReference} for more information}.

\begin{figure}
\begin{cfa}
struct Widget {
	int id;
	float size;
	Parts * optionalParts;
};

// ?{} is the constructor operator identifier
// The first argument is a reference to the type to initialize
// Subsequent arguments can be specified for initialization

void ?{}(Widget &w) { // default constructor
	w.id = -1;
	w.size = 0.0;
	w.optionalParts = 0;
}

// constructor with values (does not need to include all fields)
void ?{}(Widget &w, int id, float size) {
	w.id = id;
	w.size = size;
	w.optionalParts = 0;
}

// ^? is the destructor operator identifier
void ^?(Widget &w) { // destructor
	w.id = 0;
	w.size = 0.0;
	if (w.optionalParts != 0) {
	// This is the only pointer to optionalParts, free it
	free(w.optionalParts);
	w.optionalParts = 0;
	}
}

Widget baz; // reserve space only
Widget foo{}; // calls default constructor
Widget bar{23, 2.45}; // calls constructor with values
baz{24, 0.91}; // calls constructor with values
?{}(baz, 24, 0.91}; // explicit call to constructor
^bar; // explicit call to destructor
^?(bar); // explicit call to destructor
\end{cfa}
\caption{Constructors and Destructors}
\end{figure}


\section{Overloading}
\label{s:Overloading}

Overloading refers to the capability of a programmer to define and use multiple objects in a program with the same name.
In \CFA, a declaration may overload declarations from outer scopes with the same name, instead of hiding them as is the case in C.
This may cause identical C and \CFA programs to behave differently.
The compiler selects the appropriate object (overload resolution) based on context information at the place where it is used.
Overloading allows programmers to give functions with different signatures but similar semantics the same name, simplifying the interface to users.
Disadvantages of overloading are that it can be used to give functions with different semantics the same name, causing confusion, or that the compiler may resolve to a different function from what the programmer expected.
\CFA allows overloading of functions, operators, variables, and even the constants 0 and 1.

The compiler follows some overload resolution rules to determine the best interpretation of all of these overloads.
The best valid interpretations are the valid interpretations that use the fewest unsafe conversions.
Of these, the best are those where the functions and objects involved are the least polymorphic.
Of these, the best have the lowest total conversion cost, including all implicit conversions in the argument expressions.
Of these, the best have the highest total conversion cost for the implicit conversions (if any) applied to the argument expressions.
If there is no single best valid interpretation, or if the best valid interpretation is ambiguous, then the resulting interpretation is ambiguous.
For details about type inference and overload resolution, please see the \CFA Language Specification.
\begin{cfa}
int foo(int a, int b) {
	float sum = 0.0;
	float special = 1.0;
	{
		int sum = 0;
		// both the float and int versions of sum are available
		float special = 4.0;
		// this inner special hides the outer version
		...
	}
	...
}
\end{cfa}


\subsection{Constant}

The constants 0 and 1 have special meaning.
In \CFA, as in C, all scalar types can be incremented and
decremented, which is defined in terms of adding or subtracting 1.
The operations ©&&©, ©||©, and ©!© can be applied to any scalar arguments and are defined in terms of comparison against 0 (ex. ©(a && b)© becomes ©(a != 0 && b != 0)©).

In C, the integer constants 0 and 1 suffice because the integer promotion rules can convert them to any arithmetic type, and the rules for pointer expressions treat constant expressions evaluating to 0 as a special case.
However, user-defined arithmetic types often need the equivalent of a 1 or 0 for their functions or operators, polymorphic functions often need 0 and 1 constants of a type matching their polymorphic parameters, and user-defined pointer-like types may need a null value.
Defining special constants for a user-defined type is more efficient than defining a conversion to the type from ©_Bool©.

Why just 0 and 1? Why not other integers? No other integers have special status in C.
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 does not seem worth the gain.

For example, to define the constants for a complex type, the programmer would define the following:

\begin{cfa}
struct Complex {
	double real;
	double imaginary;
}

const Complex 0 = {0, 0};
const Complex 1 = {1, 0};
...

	Complex a = 0;
...

	a++;
...
	if (a) { // same as if (a == 0)
...
}
\end{cfa}


\subsection{Variable}
\label{s:VariableOverload}

The overload rules of \CFA allow a programmer to define multiple variables with the same name, but different types.
Allowing overloading of variable names enables programmers to use the same name across multiple types, simplifying naming conventions and is compatible with the other overloading that is allowed.
For example, a developer may want to do the following:
\begin{cfa}
int pi = 3;
float pi = 3.14;
char pi = .p.;
\end{cfa}


\subsection{Function Overloading}

Overloaded functions in \CFA are resolved based on the number and type of arguments, type of return value, and the level of specialization required (specialized functions are preferred over generic).

The examples below give some basic intuition about how the resolution works.
\begin{cfa}
// Choose the one with less conversions
int doSomething(int value) {...} // option 1
int doSomething(short value) {...} // option 2

int a, b = 4;
short c = 2;

a = doSomething(b); // chooses option 1
a = doSomething(c); // chooses option 2

// Choose the specialized version over the generic

generic(type T)
T bar(T rhs, T lhs) {...} // option 3
float bar(float rhs, float lhs){...} // option 4
float a, b, c;
double d, e, f;
c = bar(a, b); // chooses option 4

// specialization is preferred over unsafe conversions

f = bar(d, e); // chooses option 5
\end{cfa}


\subsection{Operator}

\CFA also allows operators to be overloaded, to simplify the use of user-defined types.
Overloading the operators allows the users to use the same syntax for their custom types that they use for built-in types, increasing readability and improving productivity.
\CFA uses the following special identifiers to name overloaded operators:

\begin{table}[hbt]
\centering
\begin{tabular}{@{}l@{\hspace{\parindentlnth}}l@{\hspace{\parindentlnth}}l@{}}
\begin{tabular}{@{}ll@{}}
©?[?]©	& subscripting \impl{?[?]}					\\
©?()©	& function call \impl{?()}					\\
©?++©	& postfix increment \impl{?++}				\\
©?--©	& postfix decrement \impl{?--}				\\
©++?©	& prefix increment \impl{++?}				\\
©--?©	& prefix decrement \impl{--?}				\\
©*?©	& dereference \impl{*?}						\\
©+?©	& unary plus \impl{+?}						\\
©-?©	& arithmetic negation \impl{-?}				\\
©~?©	& bitwise negation \impl{~?}				\\
©!?©	& logical complement \impl{"!?}				\\
©?\?©	& exponentiation \impl{?\?}					\\
©?*?©	& multiplication \impl{?*?}					\\
©?/?©	& division \impl{?/?}						\\
©?%?©	& remainder \impl{?%?}						\\
\end{tabular}
&
\begin{tabular}{@{}ll@{}}
©?+?©	& addition \impl{?+?}						\\
©?-?©	& subtraction \impl{?-?}					\\
©?<<?©	& left shift \impl{?<<?}					\\
©?>>?©	& right shift \impl{?>>?}					\\
©?<?©	& less than \impl{?<?}						\\
©?<=?©	& less than or equal \impl{?<=?}			\\
©?>=?©	& greater than or equal \impl{?>=?}			\\
©?>?©	& greater than \impl{?>?}					\\
©?==?©	& equality \impl{?==?}						\\
©?!=?©	& inequality \impl{?"!=?}					\\
©?&?©	& bitwise AND \impl{?&?}					\\
©?^?©	& exclusive OR \impl{?^?}					\\
©?|?©	& inclusive OR \impl{?"|?}					\\
													\\
													\\
\end{tabular}
&
\begin{tabular}{@{}ll@{}}
©?=?©	& simple assignment \impl{?=?}				\\
©?\=?©	& exponentiation assignment \impl{?\=?}		\\
©?*=?©	& multiplication assignment \impl{?*=?}		\\
©?/=?©	& division assignment \impl{?/=?}			\\
©?%=?©	& remainder assignment \impl{?%=?}			\\
©?+=?©	& addition assignment \impl{?+=?}			\\
©?-=?©	& subtraction assignment \impl{?-=?}		\\
©?<<=?©	& left-shift assignment \impl{?<<=?}		\\
©?>>=?©	& right-shift assignment \impl{?>>=?}		\\
©?&=?©	& bitwise AND assignment \impl{?&=?}		\\
©?^=?©	& exclusive OR assignment \impl{?^=?}		\\
©?|=?©	& inclusive OR assignment \impl{?"|=?}		\\
													\\
													\\
													\\
\end{tabular}
\end{tabular}
\caption{Operator Identifiers}
\label{opids}
\end{table}

These identifiers are defined such that the question marks in the name identify the location of the operands.
These operands represent the parameters to the functions, and define how the operands are mapped to the function call.
For example, ©a + b© becomes ©?+?(a, b)©.

In the example below, a new type, myComplex, is defined with an overloaded constructor, + operator, and string operator.
These operators are called using the normal C syntax.

\begin{cfa}
type Complex = struct { // define a Complex type
	double real;
	double imag;
}

// Constructor with default values

void ?{}(Complex &c, double real = 0.0, double imag = 0.0) {
	c.real = real;
	c.imag = imag;
}

Complex ?+?(Complex lhs, Complex rhs) {
	Complex sum;
	sum.real = lhs.real + rhs.real;
	sum.imag = lhs.imag + rhs.imag;
	return sum;
}

String ()?(const Complex c) {
	// use the string conversions for the structure members
	return (String)c.real + . + . + (String)c.imag + .i.;
}
...

Complex a, b, c = {1.0}; // constructor for c w/ default imag
...
c = a + b;
print(.sum = . + c);
\end{cfa}


\section{Auto Type-Inferencing}

Auto type-inferencing occurs in a declaration where a variable's type is inferred from its initialization ex\-pression type.
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{3em}}ll@{}}
\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CC}}	& \multicolumn{1}{c}{\textbf{\Indexc{gcc}}} \\
\begin{cfa}

auto j = 3.0 * 4;
int i;
auto k = i;
\end{cfa}
&
\begin{cfa}
#define expr 3.0 * i
typeof(expr) j = expr;
int i;
typeof(i) k = i;
\end{cfa}
&
\begin{cfa}

// use type of initialization expression

// use type of primary variable
\end{cfa}
\end{tabular}
\end{cquote}
The two important capabilities are:
\begin{itemize}
\item
not determining or writing long generic types,
\item
ensuring secondary variables, related to a primary variable, always have the same type.
\end{itemize}

In \CFA, ©typedef© provides a mechanism to alias long type names with short ones, both globally and locally, but not eliminate the use of the short name.
\Indexc{gcc} provides ©typeof© to declare a secondary variable from a primary variable.
\CFA also relies heavily on the specification of the left-hand side of assignment for type inferencing, so in many cases it is crucial to specify the type of the left-hand side to select the correct type of the right-hand expression.
Only for overloaded routines \emph{with the same return type} is variable type-inferencing possible.
Finally, ©auto© presents the programming problem of tracking down a type when the type is actually needed.
For example, given
\begin{cfa}
auto j = @...@
\end{cfa}
and the need to write a routine to compute using ©j©
\begin{cfa}
void rtn( @...@ parm );
rtn( j );
\end{cfa}
A programmer must work backwards to determine the type of ©j©'s initialization expression, reconstructing the possibly long generic type-name.
In this situation, having the type name or a short alias is very useful.

There is also the conundrum in type inferencing of when to \emph{\Index{brand}} a type.
That is, when is the type of the variable more important than the type of its initialization expression.
For example, if a change is made in an initialization expression, it can cause cascading type changes and/or errors.
At some point, a variable type needs to remain constant and the expression to be in error when it changes.

Given ©typedef© and ©typeof© in \CFA, and the strong need to use the type of left-hand side in inferencing, auto type-inferencing is not supported at this time.
Should a significant need arise, this feature can be revisited.


\begin{comment}
\section{Generics}

\CFA supports parametric polymorphism to allow users to define generic functions and types.
Generics allow programmers to use type variables in place of concrete types so that the code can be reused with multiple types.
The type parameters can be restricted to satisfy a set of constraints.
This enables \CFA to build fully compiled generic functions and types, unlike other languages like \Index*[C++]{\CC{}} where templates are expanded or must be explicitly instantiated.


\subsection{Generic Functions}

Generic functions in \CFA are similar to template functions in \Index*[C++]{\CC{}}, and will sometimes be expanded into specialized versions, just like in \CC.
The difference, however, is that generic functions in \CFA can also be separately compiled, using function pointers for callers to pass in all needed functionality for the given type.
This means that compiled libraries can contain generic functions that can be used by programs linked with them (statically or dynamically).
Another advantage over \CC templates is unlike templates, generic functions are statically checked, even without being instantiated.

A simple example of using Do.s parametric polymorphism to create a generic swap function would look like this:

\begin{cfa}
generic(type T)
void swap(T &a, T &b) {
	T tmp = a;
	a = b;
	b = a;
}

int a, b;
swap(a, b);

Point p1, p2;
swap(p1, p2);
\end{cfa}

Here, instead of specifying types for the parameters a and b, the function has a generic type parameter, type T.
This function can be called with any type, and the compiler will handle generating the proper code for that type, using call site inference to determine the appropriate value for T.


\subsection{Bounded Quantification}

Some generic functions only work (or make sense) for any type that satisfies a given property.
For example, here is a function to pick the minimum of two values of some type.
\begin{cfa}
generic (type T | bool ?<?(T, T) )

T min( T a, T b ) {
	return a < b ? a : b;
}
\end{cfa}

It only makes sense to call min with values of a type that has an ordering: a way to decide whether one value is less than another.
The ordering function used here is the less than operator, <.
The syntax used to reference the operator is discussed in further detail in Operator Overloading.
In \CFA, this assertion on the type of a generic is written as the bound, (type T | bool ?<?(T, T)).
The \CFA compiler enforces that minis only called with types for which the less than operator is defined, and reports a compile-time error otherwise.

Bounds can also involve multiple types, and multiple requirements, as shown below:
\begin{cfa}
generic (type T, type U | { T foo(T, U); U bar(U); })

T baz(T t, U u) {
	return foo(t, bar(u));
}
\end{cfa}


\subsection{Interfaces}

Type bounds as shown above are not very informative, merely requiring that a function exists with the right name and type.
Suppose you try to call a polymorphic function and \CFA gives you an error that int combine(int, int) is not defined.
Can you define it? What is it supposed to do? Perhaps it should compute the sum, or the bitwise and, or the maximum, or the least common multiple; or perhaps it's an operation that can't be defined for integers.
The function signature doesn't say.

Interfaces gather together a set of function signatures under a common name, which solves two problems.
First, an interface name can be used in type bounds instead of function signatures.
This avoids repetition when a bound is used in many functions.
Second, interfaces explicitly document the existence of a commonly used set of functionality, making programs easier to understand.
\begin{cfa}
generic (type T)
interface Orderable {
	bool ?<?(T, T);
};

generic (type T | Orderable(T))
T min( T a, T b ) {
	return a < b ? a : b;
}
\end{cfa}

This definition of the interface Orderable makes the generic function min easier to read and understand.
Orderable can also be reused for other generic functions, max for example.
Interfaces can also build on top of other interfaces.
For example:
\begin{cfa}
generic (type T | Orderable(T)
interface FooBarable {
	int foo(T, T);
	int Bar(T, T);
};
\end{cfa}

The FooBarable interface specifies all of the bounds of the Orderable interface, plus the additional bounds specified in its definition.
A type does not need to specify that it satisfies any interface, the compiler can figure this out at compile time.
For example, there is no need to add some special syntax to show that a type implements the Orderable interface, just define a ?<? operator and it is satisfied.


\subsection{Generic Typedefs}

Type synonyms can be defined generically using the typedef keyword together with a generic type annotation.
These can be used to abbreviate complicated type expressions, especially in generic code.
\begin{cfa}
// typedef the generic function pointers for later use

generic(type T)
typedef int (* predicate)(T);
generic(type Captured, type T)
typedef void (* callback)(Captured, T);

generic(type T)
void find(int length, T * array,
	predicate(T) p, callback(void *, T)f) {
	int i;
	for (i = 0; i < length; i++)
	if (p(array[i])) f(NULL, array[i]);
}
\end{cfa}


\subsection{Generic Types}

Generic types are defined using the same mechanisms as those described above for generic functions.
This feature allows users to create types that have one or more fields that use generic parameters as types, similar to a template classes in \Index*[C++]{\CC{}}.
For example, to make a generic linked list, a placeholder is created for the type of the elements, so that the specific type of the elements in the list need not be specified when defining the list.
In C, something like this would have to be done using void pointers and unsafe casting.
As in generic functions, Do.s generic types are different from \CC templates in that they can be fully compiled, while \CC templates are more like macro expansions.
This means that a \CFA generic type from a compiled library can be used with any type that satisfies the bounds.

The syntax for defining a generic type looks very similar to that of a generic function.
Generic types support bounds and interfaces, using the same syntax as generic functions.
\begin{cfa}
generic (type T)
struct LinkedListElem {
	T elem;
	LinkedListElem(T) * next;
};

LinkedListElem *++?(LinkedListElem ** elem) {
	return * elem = elem->next;
}

generic (type T)
struct LinkedList {
	LinkedListElem(T) * head;
	unsigned int size;
}

generic (type T | bool ?==?(T, T))
bool contains(LinkedList(T) * list, T elem) {
	for(LinkedListElem * iter = list->head; iter != 0; ++iter) {
	if (iter->elem == elem) return true;
	}
	return false;
}
\end{cfa}


\section{Safety}

Safety, along with productivity, is a key goal of Do.
This section discusses the safety features that have been included in \CFA to help programmers create more stable, reliable, and secure code.


\subsection{Exceptions}

\CFA introduces support for exceptions as an easier way to recover from exceptional conditions that may be detected within a block of code.
In C, developers can use error codes and special return values to report to a caller that an error occurred in a function.
The major problem with error codes is that they can be easily ignored by the caller.
Failure to properly check for errors can result in the caller making incorrect assumptions about the current state or about the return value that are very likely to result in errors later on in the program, making the source of the problem more difficult to find when debugging.
An unhandled exception on the other hand will cause a crash, revealing the original source of the erroneous state.

Exceptions in \CFA allow a different type of control flow.
Throwing an exception terminates execution of the current block, invokes the destructors of variables that are local to the block, and propagates the exception to the parent block.
The exception is immediately re-thrown from the parent block unless it is caught as described below.
\CFA uses keywords similar to \Index*[C++]{\CC{}} for exception handling.
An exception is thrown using a throw statement, which accepts one argument.

\begin{cfa}
	...

	throw 13;

	...
\end{cfa}

An exception can be caught using a catch statement, which specifies the type of the exception it can catch.
A catch is specified immediately after a guarded block to signify that it can catch an exception from that block.
A guarded block is specified using the try keyword, followed by a block of code inside of curly braces.

\begin{cfa}
	...

	try {
		throw 13;
	}
	catch(int e) {
		printf(.caught an exception: %d\n., e);
	}
\end{cfa}
\end{comment}


\section{Concurrency}

Concurrency support in \CFA is implemented on top of a highly efficient runtime system of light-weight, M:N, user level threads.
The model integrates concurrency features into the language by making the structure type the core unit of concurrency.
All communication occurs through method calls, where data is sent via method arguments, and received via the return value.
This enables a very familiar interface to all programmers, even those with no parallel programming experience.
It also allows the compiler to do static type checking of all communication, a very important safety feature.
This controlled communication with type safety has some similarities with channels in \Index*{Go}, and can actually implement channels exactly, as well as create additional communication patterns that channels cannot.
Mutex objects, monitors, are used to contain mutual exclusion within an object and synchronization across concurrent threads.

\begin{figure}
\begin{cfa}
#include <fstream>
#include <coroutine>

coroutine Fibonacci {
	int fn; $\C{// used for communication}$
};
void ?{}( Fibonacci * this ) {
	this->fn = 0;
}
void main( Fibonacci * this ) {
	int fn1, fn2; $\C{// retained between resumes}$
	this->fn = 0; $\C{// case 0}$
	fn1 = this->fn;
	suspend(); $\C{// return to last resume}$

	this->fn = 1; $\C{// case 1}$
	fn2 = fn1;
	fn1 = this->fn;
	suspend(); $\C{// return to last resume}$

	for ( ;; ) { $\C{// general case}$
		this->fn = fn1 + fn2;
		fn2 = fn1;
		fn1 = this->fn;
		suspend(); $\C{// return to last resume}$
	} // for
}
int next( Fibonacci * this ) {
	resume( this ); $\C{// transfer to last suspend}$
	return this->fn;
}
int main() {
	Fibonacci f1, f2;
	for ( int i = 1; i <= 10; i += 1 ) {
		sout | next( &f1 ) | ' ' | next( &f2 );
	} // for
}
\end{cfa}
\caption{Fibonacci Coroutine}
\label{f:FibonacciCoroutine}
\end{figure}


\subsection{Coroutine}

\Index{Coroutines} are the precursor to tasks.
\VRef[Figure]{f:FibonacciCoroutine} shows a coroutine that computes the \Index*{Fibonacci} numbers.


\subsection{Monitors}

A monitor is a structure in \CFA which includes implicit locking of its fields.
Users of a monitor interact with it just like any structure, but the compiler handles code as needed to ensure mutual exclusion.
An example of the definition of a monitor is shown here:
\begin{cfa}
type Account = monitor {
	const unsigned long number; // account number
	float balance; // account balance
};
\end{cfa}

\begin{figure}
\begin{cfa}
#include <fstream>
#include <kernel>
#include <monitor>
#include <thread>

monitor global_t {
	int value;
};

void ?{}(global_t * this) {
	this->value = 0;
}

static global_t global;

void increment3( global_t * mutex this ) {
	this->value += 1;
}
void increment2( global_t * mutex this ) {
	increment3( this );
}
void increment( global_t * mutex this ) {
	increment2( this );
}

thread MyThread {};

void main( MyThread* this ) {
	for(int i = 0; i < 1_000_000; i++) {
		increment( &global );
	}
}
int main(int argc, char* argv[]) {
	processor p;
	{
		MyThread f[4];
	}
	sout | global.value;
}
\end{cfa}
\caption{Atomic-Counter Monitor}
\caption{f:AtomicCounterMonitor}
\end{figure}

\begin{comment}
Since a monitor structure includes an implicit locking mechanism, it does not make sense to copy a monitor;
it is always passed by reference.
Users can specify to the compiler whether or not a function will require mutual exclusion of the monitor using the mutex modifier on the parameter.
When mutex is specified, the compiler inserts locking before executing the body of the function, and unlocking after the body.
This means that a function requiring mutual exclusion could block if the lock is already held by another thread.
Blocking on a monitor lock does not block the kernel thread, it simply blocks the user thread, which yields its kernel thread while waiting to obtain the lock.
If multiple mutex parameters are specified, they will be locked in parameter order (\ie first parameter is locked first) and unlocked in the
reverse order.
\begin{cfa}
// This function accesses a constant field, it does not require
// mutual exclusion

export unsigned long getAccountNumber(Account &a) {
	return a.number;
}

// This function accesses and modifies a shared field; it
// requires mutual exclusion

export float withdrawal(mutex Account &a, float amount) {
	a.balance -= amount;
	return a.balance;
}
\end{cfa}

Often, one function using a monitor will call another function using that same monitor.
If both require mutual exclusion, then the thread would be waiting for itself to release the lock when it calls the inner function.
This situation is resolved by allowing recursive entry (reentrant locks), meaning that if the lock is already held by the caller, it can be locked again.
It will still be unlocked the same number of times.
An example of this situation is shown below:

\begin{cfa}
// deleting a job from a worker requires mutual exclusion

void deleteJob(mutex Worker &w, Job &j) {
	...
}

// transferring requires mutual exclusion and calls deleteJob

void transferJob(mutex Worker & from, Worker & to) {
	...
	deleteJob(j);
	...
}
\end{cfa}
\end{comment}


\subsection{Tasks}

\CFA also provides a simple mechanism for creating and utilizing user level threads.
A task provides mutual exclusion like a monitor, and also has its own execution state and a thread of control.
Similar to a monitor, a task is defined like a structure:

\begin{figure}
\begin{cfa}
#include <fstream>
#include <kernel>
#include <stdlib>
#include <thread>

thread First  { signal_once * lock; };
thread Second { signal_once * lock; };

void ?{}( First * this, signal_once* lock ) { this->lock = lock; }
void ?{}( Second * this, signal_once* lock ) { this->lock = lock; }

void main( First * this ) {
	for ( int i = 0; i < 10; i += 1 ) {
		sout | "First : Suspend No." | i + 1;
		yield();
	}
	signal( this->lock );
}

void main( Second * this ) {
	wait( this->lock );
	for ( int i = 0; i < 10; i += 1 ) {
		sout | "Second : Suspend No." | i + 1;
		yield();
	}
}

int main( void ) {
	signal_once lock;
	sout | "User main begin";
	{
		processor p;
		{
			First  f = { &lock };
			Second s = { &lock };
		}
	}
	sout | "User main end";
}
\end{cfa}
\caption{Simple Tasks}
\label{f:SimpleTasks}
\end{figure}


\begin{comment}
\section{Modules and Packages }

High-level encapsulation is useful for organizing code into reusable units, and accelerating compilation speed.
\CFA provides a convenient mechanism for creating, building and sharing groups of functionality that enhances productivity and improves compile time.

There are two levels of encapsulation in \CFA, module and package.
A module is a logical grouping of functionality that can be easily pulled into another project, much like a module in \Index*{Python} or a package in \Index*{Go}.
A module forms a namespace to limit the visibility and prevent naming conflicts of variables.
Furthermore, a module is an independent translation unit, which can be compiled separately to accelerate the compilation speed.

A package is a physical grouping of one or more modules that is used for code distribution and version management.
Package is also the level of granularity at which dependences are managed.
A package is similar to the Crate in \Index*{Rust}.


\subsection{No Declarations, No Header Files}

In C and \Index*[C++]{\CC{}}, it is necessary to declare or define every global variable, global function, and type before it is used in each file.
Header files and a preprocessor are normally used to avoid repeating code.
Thus, many variables, functions, and types are described twice, which exposes an opportunity for errors and causes additional maintenance work.
Instead of following this model, the \CFA tools can extract all of the same information from the code automatically.
This information is then stored in the object files for each module, in a format that can quickly be read by the compiler, and stored at the top of the file, for quick access.
In addition to the user productivity improvements, this simple change also improves compile time, by saving the information in a simple machine readable format, instead of making the compiler parse the same information over and over from a header file.
This seems like a minor change, but according to (Pike, \Index*{Go} at Google: Language Design in the Service of Software Engineering), this simple change can cause massive reductions in compile time.

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:
\begin{cfa}
bool isEven(unsigned int x) {
	if (x == 0) return true;
	else return !isOdd(x);
}

bool isOdd(unsigned int x) {
	if (x == 1) return true;
	else return !isEven(x - 2);
}
\end{cfa}

Header files in C are used to expose the declarations from a library, so that they can be used externally.
With \CFA, this functionality is replaced with module exports, discussed below.
When building a \CFA module which needs to be callable from C code, users can use the tools to generate a header file suitable for including in these C files with all of the needed declarations.

In order to interoperate with existing C code, \CFA files can still include header files, the contents of which will be enclosed in a C linkage section to indicate C calling conventions \see{\VRef{s:Interoperability} for more information}.


\subsection{Modules}

A module typically contains a set of related types and methods, with some objects accessible from outside the package, and some limited to use inside the module.
These modules can then be easily shared and reused in multiple projects.
As modules are intended to be distributed for reuse, they should generally have stable, well-defined interfaces.

\CFA adds the following keywords to express the module systems: module, export, import, as.


\subsubsection{Module Declaration}

The syntax to declare a module is module moduleName;.

The module declaration must be at the beginning of a file, and each file can only belong to one module.
If there is no module declaration at the beginning of a file, the file belongs to the global module.
A module can span several files.
By convention, a module and the files belonging to the module have additional mapping relationship which is described in the Do-Lang Tooling documentation.

The moduleName follows the same rules of a variable name, except that it can use slash "/" to indicate the module/sub-module relationship.
For example, container/vector is a valid module name, where container is the parent module name, and vector is the sub-module under container.

Only the interfaces of a module are visible from outside, when the module is imported. export is a type decorator to declare a module interface.
A method, a global variable or a type can be declared as a module interface.
Types defined in a module and referenced by an exported function or a variable must be exported, too.

The following code is a simple module declaration example.
\begin{cfa}
module M;

//visible outside module M

export int f(int i) { return i + 1; }
export double aCounter;

//not visible outside module M

int g(int i) { return i - 1; }

double bCounter;
\end{cfa}

export module moduleName; can be use to re-export all the visible (exported) names in moduleName from the current module.


\subsubsection{Module Import}

The syntax to import a module is import moduleName; or import moduleName as anotherName;.
One package cannot be imported with both of the two types of syntax in one file.
A package imported in one file will only be visible in this file.
For example, two files, A and B belong to the same module.
If file A imports another module, M, the exported names in M are not visible in file B.

All of the exported names are visible in the file that imports the module.
The exported names can be accessed within a namespace based on the module name in the first syntax (ex moduleName.foo).
If moduleName has several elements separated by '/' to describe a sub-module (ex. import container/vector;), the last element in the moduleName is used as the namespace to access the visible names in that module (ex vector.add(...);).
The as keyword is used to confine the imported names in a unique namespace (ex. anotherName.foo). anotherName must be a valid identifier (same rules as a variable name) which means it cannot have '/' in it.
Conflicts in namespaces will be reported by the compiler.
The second method can be used to solve conflicting name problems.
The following code snippets show the two situations.

\begin{cfa}
module util/counter;
export int f(int i) { return i+1; }

import util/counter;

int main() {
	return counter.f(200); // f() from the package counter
}

import util/counter as ct;
int main() {
	return ct.f(200); // f() from the package counter
}
\end{cfa}


Additionally, using the .as. syntax, a user can force the compiler to add the imported names into the current namespace using .as ..With these module rules, the following module definitions and imports can be achieved without any problem.

\begin{cfa}
module M1;
export int f(int i) { return i+1;} // visible outside

int g(int i) { return i-1;} // not visible outside

module M2;
int f(int i) { return i * 2; } // not visible outside
export int g(int g) { return i / 2; } // visible outside

import M1 as .;

import M2 as .;


int main() {
	return f(3) + g(4); //f() from M1 and g() from M2;
}
\end{cfa}


\subsubsection{Sub-Module and Module Aggregation}

Several modules can be organized in a parent module and sub-modules relationship.
The sub-module names are based on hierarchical naming, and use slash, "/", to indicate the relationship.
For example, std/vector and std/io are sub-modules of module std.
The exported names in a sub-module are NOT visible if the parent module is imported, which means the exported names in the sub-module are
not implicitly exported in the parent module.

Aggregation is a mechanism to support components and simplified importing.
The mechanism is not based on naming but based on manual declaration.
For example, the following is the aggregated sequence module.
The export {...} is syntactic sugar for many lines of export module aModule;.
If an aggregated module is imported, all the included modules in the aggregation are imported.

\begin{cfa}
module std/sequence;

export {
	module std/vector;
	module std/list;
	module std/array;
	module std/deque;
	module std/forward_list;
	module std/queue;
	module std/stack;
};
\end{cfa}

After importing the aggregated module, each individual name is still contained in the original name space.
For example, vector.add() and list.add() should be used to reference the add methods if there are add methods in both the vector module and the list module.


\subsubsection{Import from Repository}

When a module is imported, the tools locate the module in the one of the accessible package paths (defined by command line flag or environment variable).
The tools also support retrieving modules of a package from external repositories.
See Listing 40: Package directory structure


\subsubsection{Package Import}

Because packages are the places where the building tool looks for modules, there is no code required in the \CFA source file to import a package.
In order to use modules in a package, the programmer needs to guide the building tool to locate the right package by 1) Adding the package's parent path into \$DOPATH;
or 2) Adding the package dependence into the current project's Do.prj.
More details about locating a module in a package are explained in the next section.


\subsubsection{Package Versioning}

A package must have a version number.
The version number is a string.
For example "1.0", "1.a", "A1", and "1ec5fab753eb979d3886a491845b8ae152d58c8f" are all valid version numbers.
By convention, a package is stored in a directory named packageName-packageVersion.
For example, the util package with version 1.1 is stored in a directory named util-1.1.

The project description file can optionally specify the version of the package used in the current project.
If not defined, because the version number is a string, and all the different versions for the same package will be sorted in increasing order, the package with the largest version number will be used in the compilation.
The builder tool will record the specific package version used in the build in the project's "Do.lock" file to enable fully repeatable builds.


\subsection{Module and Package Organization}

\CFA has two level of encapsulations, module and package.
This section explains the object model of modules, packages and other language concepts.
It also explains how programmers should organize their code, and the method used by the build tools to locate packages, and import modules for compilation.


\subsubsection{Object Model}

There are several concepts in Do.
\begin{itemize}
\item
File: a \CFA source file
\item
Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
\item
Package: a container to organize modules for distribution; It has attributes like name, author,
version, dependences, etc.
\item
Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
\end{itemize}

The following rules summarize the object model of all the above concepts:
\begin{itemize}
\item
A module contains one or more files
\begin{itemize}
\item
One file can only belong to one module
\item
A module has its name and interfaces exported
\item
A file without a module declaration at the beginning belongs to the global module
\item
\end{itemize}

\item
A package contains one or more modules
\begin{itemize}
\item
A package has additional meta info described in Do.prj file
\item
A package may be dependent on other packages.
\end{itemize}

\item
A project contains one or more modules in its source code
\begin{itemize}
\item
A project has additional meta info described in Do.prj file
\item
A project may be dependent on other packages
\item
A project can be transformed into a package for distribution
\item
A project can generate one or more executable binaries
\end{itemize}
\end{itemize}


\subsubsection{Module File Organization}

The rules of this section are the conventions to organize module files in one package.

The file location of a module in a package must match the module/submodule naming hierarchy.
The names separated by slash "/" must match the directory levels.
If only one file is used to implement one module, there is no need to put the module implementation file inside a sub-directory.
The file can be put inside its parent module's sub-directory with the sub module's name as the file name.

Here is an example of a package, util.
\begin{cfa}
+ util
Do.prj #package description file
	heap.do #Case 1: module heap;
	list.do #Case 1: mdoule list;
	ring.do #Case 1: module ring;
	+ string #Case 2
	impl1.do #module string;
	+ std
	vector.do
	list.do
	+ array #Case 3
	array1.do #module std/array;
	array2.do #module std/array;
	sequence.do #Case 4, module std/sequence;
	test.do #Case 5
\end{cfa}

\begin{itemize}
\item
Case 1: Each individual file implements a module
\item
Case 2: Put the implementation of a module under the sub-directory, but there is only one file
\item
Case 3: Put the implementation of a module under the sub-directory; There are several files to
implement one module
\item
Case 4: One file to express one aggregation
\item
Case 5: The file does not belong to any module; It is used for testing purpose
\end{itemize}

The example only uses source code, ".do" files, to show the module file organization.
Other module packaging formats, like binary, must also follow the same rules.


\subsection{Module File Format}

\CFA supports different types of module file formats.

\begin{itemize}
\item
Pure source code format: The files should be organized following the previous section's definition.
\item
IR format (TBD): The \CFA compiler IR format, similar to the source code format
\item
Binary format, including ".a" static library or ".so" dynamic linkage library
\begin{itemize}
\item
The file's name must match the right level's module name defined in the previous section
\item
E.g. "util.so" includes all modules for the package util.
\item
E.g. "string.so" under the package directory to include files belonging to "module string;"
\end{itemize}
\item.
Archive format
\begin{itemize}
\item
The archive is named as ".dar", and is a zip archive of the source code or the binary for a package
\item
E.g. "util.dar" is the whole package for util package including the package direction file
\end{itemize}
\item
Hybrid format
\begin{itemize}
\item
A package can be distributed partly in source code, partly in binary format, and/or packaged in the archive format
\item
The only limitation is that the names of the files must match the module location names defined in previous section
\end{itemize}
\end{itemize}
Package and Module Locating and the \CFA Language Tooling documentation for more details.


\subsection{Packages}

A package is synonymous with a library in other languages.
The intent of the package level encapsulation is to facilitate code distribution, version control, and dependence management.
A package is a physical grouping of one or more modules in a directory (an archive file for a directory).
The concept of a package is the convention for grouping code, and the contract between the language and the building tool to search for imported modules.


\subsubsection{Package Definition}

A package is defined by putting a project description file, Do.prj, with one or more modules into a directory.
This project description file contains the package's meta data, including package name, author, version, dependences, etc.
It should be in the root of the package directory.

The modules in the package could be either source code, or compiled binary format.
The location of the module files should follow the module name's path.

Here is a simple example of the directory structure of a package, core.
It contains a module std and several sub-modules under std.
\begin{cfa}
+ core
	Do.prj
	+ std
	+ io
	file.do # module std/io/file;
	network.do #module std/io/network;
	+ container
	vector.do #module std/container/vector;
	list.do #module std/container/list;
\end{cfa}


\subsubsection{Package Import}

Because packages are the places where the building tool looks for modules, there is no code required in the \CFA source file to import a package.
In order to use modules in a package, the programmer needs to guide the building tool to locate the right package by 1) Adding the package's parent path into \$DOPATH; or 2) Adding the package dependence into the current project's Do.prj.
More details about locating a module in a package are explained in the next section.


\subsubsection{Package Versioning}

A package must have a version number.
The version number is a string.
For example "1.0", "1.a", "A1", and "1ec5fab753eb979d3886a491845b8ae152d58c8f" are all valid version numbers.
By convention, a package is stored in a directory named packageName-packageVersion.
For example, the util package with version 1.1 is stored in a directory named util-1.1.

The project description file can optionally specify the version of the package used in the current project.
If not defined, because the version number is a string, and all the different versions for the same package will be sorted in increasing order, the package with the largest version number will be used in the compilation.
The builder tool will record the specific package version used in the build in the project's "Do.lock" file to enable fully repeatable builds.


\subsection{Module and Package Organization}

\CFA has two level of encapsulations, module and package.
This section explains the object model of modules, packages and other language concepts.
It also explains how programmers should organize their code, and the method used by the build tools to locate packages, and import modules for compilation.


\subsubsection{Object Model}

There are several concepts in Do.
\begin{itemize}
\item
File: a \CFA source file
\item
Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
\item
Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, etc.
\item
Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
\end{itemize}

The following rules summarize the object model of all the above concepts:
\begin{itemize}
\item
A module contains one or more files
\begin{itemize}
\item
One file can only belong to one module
\item
A module has its name and interfaces exported
\item
A file without a module declaration at the beginning belongs to the global module
\end{itemize}
\item
A package contains one or more modules
\begin{itemize}
\item
A package has additional meta info described in Do.prj file
\item
A package may be dependent on other packages.
\end{itemize}
\item
A project contains one or more modules in its source code
\begin{itemize}
\item
A project has additional meta info described in Do.prj file
\item
A project may be dependent on other packages
\item
A project can be transformed into a package for distribution
\item
A project can generate one or more executable binaries
\end{itemize}
\end{itemize}


\subsubsection{Module File Organization}

The rules of this section are the conventions to organize module files in one package.

The file location of a module in a package must match the module/submodule naming hierarchy.
The names separated by slash "/" must match the directory levels.
If only one file is used to implement one module, there is no need to put the module implementation file inside a sub-directory.
The file can be put inside its parent module's sub-directory with the sub module's name as the file name.

Here is an example of a package, util.
\begin{cfa}
+ util
	Do.prj #package description file
	heap.do #Case 1: module heap;
	list.do #Case 1: mdoule list;
	ring.do #Case 1: module ring;
	+ string #Case 2
	impl1.do #module string;
	+ std
	vector.do
	list.do
	+ array #Case 3
	array1.do #module std/array;
	array2.do #module std/array;
	sequence.do #Case 4, module std/sequence;
	test.do #Case 5
\end{cfa}


\begin{itemize}
\item
Case 1: Each individual file implements a module
\item
Case 2: Put the implementation of a module under the sub-directory, but there is only one file
\item
Case 3: Put the implementation of a module under the sub-directory; There are several files to implement one module
\item
Case 4: One file to express one aggregation
\item
Case 5: The file does not belong to any module; It is used for testing purpose
\end{itemize}

The example only uses source code, ".do" files, to show the module file organization.
Other module packaging formats, like binary, must also follow the same rules.


\subsubsection{Module File Format}

\CFA supports different types of module file formats.

\begin{itemize}
\item
Pure source code format: The files should be organized following the previous section's definition.
\item
IR format (TBD): The \CFA compiler IR format, similar to the source code format
\item
Binary format, including ".a" static library or ".so" dynamic linkage library
\begin{itemize}
\item
The file's name must match the right level's module name defined in the previous section
\item
E.g. "util.so" includes all modules for the package util.
\item
E.g. "string.so" under the package directory to include files belonging to "module string;"
\end{itemize}
\item
Archive format
\begin{itemize}
\item
The archive is named as ".dar", and is a zip archive of the source code or the binary for a package
\item
E.g. "util.dar" is the whole package for util package including the package direction file
\end{itemize}
\item
Hybrid format
\begin{itemize}
\item
A package can be distributed partly in source code, partly in binary format, and/or packaged in the archive format
\item
The only limitation is that the names of the files must match the module location names defined in previous section
\end{itemize}
\end{itemize}


\subsection{Package and Module Locating}

The high-level build tools provided by \CFA will handle finding a package in your local filesystem or retrieving it from a repository if necessary, building it if necessary, and linking with it.
If a programmer prefers, one can directly call the compiler, docc to build the source files and create and link to static libraries.

When a source file imports a module, the \CFA build tool and docc compiler will locate the module according to the following order:

\begin{enumerate}
\item
This source file's directory tree, which is typically the project's src directory
\item
All of the dependent packages (in a directory or in an archive file) under the current \CFA project's pkg directory
\item
The dependent packages (in a directory or in an archive file) inside the paths defined in the DOPATH environment variable
\item
The dependent packages (in a directory or in an archive file) inside the global \CFA SDK installation's pkg directory
\item
If one dependent package is still not found, the builder tool will automatically retrieve it from the repository defined in the SDK installation's configuration, and store it in the SDK's pkg directory
\end{enumerate}

The module found first in a package will shadow the modules with the same name in the later packages in the search sequence.


\subsubsection{Dependent Package}

Dependent packages are those packages containing modules that the current project's source code will import from.
Dependent packages are defined implicitly or explicitly in one \CFA project.
All of the packages under the current project's pkg directory are implicitly dependent packages.
For others, the dependent packages must be defined in the project's Do.prj file.


\subsubsection{Package and Module Locating Example}

\begin{cfa}
# A project's source code tree

--------------------------------------

+ testProject
	Do.prj
	+ src
	main.do
	+ pkg
	+ security-1.1
	Do.prj
	security.do #module security

--------------------------------------

# Do.prj

--------------------------------------

[dependences]
std
util = "0.2"

--------------------------------------

# main.do

---------------------------------------

import security;
import std/vector;
import container;

----------------------------------------
\end{cfa}


\begin{cfa}
# pkg directory's source code tree

-----------------------------------------

+ pkg
	+ std-1.0
	Do.prj
	vector.do #module std/vector;
	queue.do #module std/queue;
	+ std-1.1
	Do.prj
	vector.do #module std/vector;
	queue.do #module std/queue;
	list.do #module std/list;
	+ util-0.1
	Do.prj
	container.do #module container;
	+ security-1.0
	security.do #module security;
------------------------------------------
\end{cfa}


During the compiling of main.do file import security;
The security module appears in both the local security-1.1 package, and the global security-1.0 package.
According to the locating sequence, the local security module in security-1.1 will be used.
And because the security-1.1 package is under local's pkg directory.
No dependence description is required in the project Do.prj file.

import std/vector;

The std/vector package appears in two different versions' packages in the global path and the project dependence doesn't specify the version. std-1.1 is used in this case.

import container;

The Do.prj specifies the version 0.2 should be used to locate container module from util package but only version 0.1 is available in the local file system.
The builder tool then will try to retrieve it from the web and store it in the global pkg directory.
After that, the container module from the newly downloaded package will be used in the compilation.
\end{comment}


\section{Language Comparisons}

\CFA is one of many languages that attempts to improve upon C.
In developing \CFA, many other languages were consulted for ideas, constructs, and syntax.
Therefore, it is important to show how these languages each compare with Do.
In this section, \CFA is compared with what the writers of this document consider to be the closest competitors of Do: \Index*[C++]{\CC{}}, \Index*{Go}, \Index*{Rust}, and \Index*{D}.


\begin{comment}
\subsection[Comparing Key Features of CFA]{Comparing Key Features of \CFA}


{% local change to lstlising to reduce font size


\lstset{basicstyle=\linespread{0.9}\sf\relsize{-2}}


\subsubsection{Constructors and Destructors}

\begin{flushleft}
\begin{tabular}{@{}l|l|l|l@{}}
\multicolumn{1}{c|}{\textbf{\CFA}}	& \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}	\\
\hline
\begin{cfa}
struct Line {
	float lnth;
}
// default constructor
void ?{}( Line * l ) {
	l->lnth = 0.0;
	sout | "default";
}


// constructor with length
void ?{}( Line * l, float lnth ) {
	l->lnth = lnth;
	sout | "lnth" | l->lnth;

}

// destructor
void ^?() {
	sout | "destroyed";
	l.lnth = 0.0;
}

// usage
Line line1;
Line line2 = { 3.4 };
\end{cfa}
&
\begin{C++}
class Line {
	float lnth;

	// default constructor
	Line() {
		cout << "default" << endl;
		lnth = 0.0;
	}


	// constructor with lnth
	Line( float l ) {
		cout << "length " << length
			 << endl;
		length = l;
	}

	// destructor
	~Line() {
		cout << "destroyed" << endl;
		length = 0.0;
	}
}
// usage
Line line1;
Line line2( 3.4 );
\end{C++}
&
\begin{lstlisting}[language=Golang]
type Line struct {
	length float32
}
// default constructor
func makeLine() Line {
	fmt.PrintLn( "default" )
	return Line{0.0}
}


// constructor with length
func makeLine( length float32 ) Line {
	fmt.Printf( "length %v", length )

	return Line{length}
}

// no destructor





// usage
line1 := makeLine()
line2 := makeLine( 3.4 )
\end{lstlisting}
&
\begin{cfa}
struct Line {
	length: f32
}
// default constructor
impl Default for Line {
	fn default () -> Line {
		println!( "default" );
		Line{ length: 0.0 }
	}
}
// constructor with length
impl Line {
	fn make( len: f32 ) -> Line {
		println!( "length: {}", len );
		Line{ length: len }
	}
}
// destructor
impl Drop for Line {
	fn drop( &mut self ) {
		self.length = 0.0
	}
}
// usage
let line1:Line = Default::default();
Line line2( 3.4 );
\end{cfa}
\end{tabular}
\end{flushleft}


\subsubsection{Operator Overloading}

\begin{flushleft}
\begin{tabular}{@{}l|l|l|l@{}}
\multicolumn{1}{c|}{\textbf{\CFA}}	& \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}	\\
\hline
\begin{cfa}
struct Cpx {
	double re, im;
};
// overload addition operator
Cpx ?+?( Cpx l, const Cpx r ) {
	return (Cpx){l.re+l.im, l.im+r.im};
}
Cpx a, b, c;
c = a + b;
\end{cfa}
&
\begin{cfa}
struct Cpx {
	double re, im;
};
// overload addition operator
Cpx operator+( Cpx l, const Cpx r ) {
	return (Cpx){l.re+l.im, l.im+r.im};
}
Cpx a, b, c;
c = a + b;
\end{cfa}
&
\begin{cfa}
// no operator overloading







\end{cfa}
&
\begin{cfa}
struct Cpx {
	re: f32,
	im: f32
}
// overload addition operator
impl Add for Cpx {
	type Output = Cpx
	fn add(self, r: Cpx) -> Cpx {
		let mut res = Cpx{re: 0.0, im: 0.0};
		res.re = self.re + r.re;
		res.im = self.im + r.im;
		return res
	}
}
let (a, b, mut c) = ...;
c = a + b
\end{cfa}
\end{tabular}
\end{flushleft}


\subsubsection{Calling C Functions}

\begin{flushleft}
\begin{tabular}{@{}l|l|l@{}}
\multicolumn{1}{c|}{\textbf{\CFA/\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}	\\
\hline
\begin{cfa}[boxpos=t]
extern "C" {
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
}
size_t fileSize( const char * path ) {
	struct stat s;
	stat(path, &s);
	return s.st_size;
}
\end{cfa}
&
\begin{cfa}[boxpos=t]
/*
#cgo
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
*/
import "C"
import "unsafe"

func fileSize(path string) C.size_t {
	var buf C.struct_stat
	c_string := C.CString(path)
	C.stat(p, &buf)
	C.free(unsafe.Pointer(c_string))
	return buf._st_size
}
\end{cfa}
&
\begin{cfa}[boxpos=t]
use libc::{c_int, size_t};
// translated from sys/stat.h
#[repr(C)]
struct stat_t {
	...
	st_size: size_t,
	...
}
#[link(name = "libc")]
extern {
	fn stat(path: * const u8,
	buf: * mut stat_t) -> c_int;
}
fn fileSize(path: * const u8) -> size_t
{
	unsafe {
		let mut buf: stat_t = uninit();
		stat(path, &mut buf);
		buf.st_size
	}
}
\end{cfa}
\end{tabular}
\end{flushleft}


\subsubsection{Generic Functions}

\begin{flushleft}
\begin{tabular}{@{}l|l|l|l@{}}
\multicolumn{1}{c|}{\textbf{\CFA}}	& \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}	\\
\hline
\begin{cfa}
generic(type T, type N |
	{ int ?<?(N, N); })
T * maximize(N (*f)(const T&),
	int n, T *a) {
	T * bestX = NULL;
	N bestN;
	for (int i = 0; i < n; i++) {
	N curN = f(a[i]);
	if (bestX == NULL ||
	curN > bestN) {
	bestX = &a[i]; bestN = curN;
	}
	}
	return bestX;
}

string * longest(int n, string *p)
{
	return maximize(length, n, p);
}
\end{cfa}
&
\begin{cfa}
template<typename T, typename F>
T * maximize(const F &f,
	int n, T *a) {
	typedef decltype(f(a[0])) N;
	T * bestX = NULL;
	N bestN;
	for (int i = 0; i < n; i++) {
	N curN = f(a[i]);
	if (bestX == NULL || curN > bestN)
	{
	bestX = &a[i]; bestN = curN;
	}
	}
	return bestX;
}

string * longest(int n, string *p) {
	return maximize(
	[](const string &s) {
	return s.length();
	}, n, p);
}
\end{cfa}
&
\begin{cfa}
// Go does not support generics!
func maximize(
	gt func(interface{}, interface{}) bool,
	f func(interface{}) interface{},
	a []interface{}) interface{} {
	var bestX interface{} = nil
	var bestN interface{} = nil
	for _, x := range a {
	curN := f(x)
	if bestX == nil || gt(curN, bestN)
	{
	bestN = curN
	bestX = x
	}
	}
	return bestX
}

func longest(
	a []interface{}) interface{} {
	return maximize(
	func(a, b interface{}) bool {
	return a.(int) > b.(int) },
	func(s interface{}) interface{} {
	return len(s.(string)) },
	a).(string)
}
\end{cfa}
&
\begin{cfa}
use std::cmp::Ordering;

fn maximize<N: Ord + Copy, T, F:
Fn(&T) -> N>(f: F, a: &Vec<T>) ->
Option<&T> {
	let mut best_x: Option<&T> = None;
	let mut best_n: Option<N> = None;
	for x in a {
	let n = f(x);
	if (match best_n { None => true,
	Some(bn) =>
	n.cmp(&bn) == Ordering::Greater })
	{
	best_x = Some(x);
	best_n = Some(n);
	}
	}
	return best_x
}

fn longest(a: &Vec<String>) ->
	Option<&String> {
	return
	maximize(|x: &String| x.len(), a)
}
\end{cfa}
\end{tabular}
\end{flushleft}


\subsubsection{Modules / Packages}

\begin{cfa}
\CFA
\CC


module example/M;

export int inc(int val) {
	return val + 1;
}




--------------------------------------
//Use the module in another file
import example/M;
int main() {
	print(M.inc(100));
	return 0;
}
// Using \CC17 module proposal

module example.M;

export {
	int inc(int val);
}

int inc(inv val) {
	return val + 1;
}
--------------------------------------
// Use the module in another file
import example.M;
int main() {
	cout << inc(100) << endl;
	return 0;
}

Go
Rust
package example/M;

func Inc(val int32) int32 {
	// Capitalization indicates exported
	return val + 100
}


--------------------------------------
//Use the package in another file
package main
import .fmt.
import "example/M"

func main() int32 {
	fmt.Printf(.%v., M.Inc(100))
}
pub mod example {
	pub mod M {
	pub inc(val i32) -> i32 {
	return val + 100;
	}
	}
}

--------------------------------------
//Use the module in another file
use example::M;



fn main() {
	println!(.{}., M::inc(100));
}
\end{cfa}


\subsubsection{Parallel Tasks}

\begin{flushleft}
\begin{tabular}{@{}l|l|l|l@{}}
\multicolumn{1}{c|}{\textbf{\CFA}}	& \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}	\\
\hline
\begin{cfa}
task Nonzero {
	int * data;
	int start;
	int end;
	int* res;
};

void ?{}(Nonzero &a, int d[], int s,
	int e, int* subres) {
	// constructor
	a.data = d;
	a.start = s;
	a.end = e;
	a.res = subres;
}

// implicitly spawn thread here
void ?()(NonzeroCounter &a) {
	int i;
	int nonzero = 0;
	for (i=start; c<end; ++i) {
	if(a.data[i]!=0){ nonzero++;}
	}
	*a.res = nonzero;
}

int main() {
	int sz = ...
	int data[sz] = ...;
	int r1 = 0, r2=0;
	int res;
	{ // create a scope for Nonzero
	Nonzero n1{data, 0, sz/2, &n1};
	Nonzero n2{data, sz/2, sz, &n2};
	n1();//spawn
	n2();//spawn
	}
	res = r1+r2;
	return res;
}
\end{cfa}
&
\begin{cfa}
#include <thread>
#include <mutex>

std::mutex m;












void task(const vector<int>&v,
	int* res, size_t s,
	size_t e) {
	int non_zero = 0;
	for(size_t i = s; i < e; ++i){
	if(v[i]!=0) { non_zero++;}
	}
	std::unique_lock<mutex> lck {m};
	*res += non_zero;
}

int main() {
	vector<int> data = ...; //data
	int res = 0;
	std::thread t1 {task, ref(data),
	&res, 0,
	data.size()/2};
	std::thread t2 {task, ref(data),
	&res, data.size()/2,
	data.size()};
	t1.join();
	t2.join();
	return res;
}
\end{cfa}
&
\begin{cfa}
package main

import "fmt"

func nonzero(data []int, c chan int) {
	nz := 0
	for _, v:=range data {
	if(v!=0) { nz := nz+1 }
	}
	c <- nz
}

func main() {
	sz := ...
	data := make([]int, sz)
	... // data init
	go nonzero(data[:len(data)/2], c)
	go nonzero(data[len(data)/2:], c)
	n1, n2 := <-c, <-c
	res := n1 + n2
	fmt.Println(res)
}
\end{cfa}
&
\begin{cfa}
use std::thread;
use std::sync:mpsc::channel;

fn main() {
	let sz = ...;
	let mut data:Vec<i32> =
	Vec::with_capacity(sz as usize);
	... //init data
	let (tx, rx) = channel();
	for i in 0..1 {
	let tx = tx.clone();
	let data = data.clone()
	thread::spawn(move|| {
	let mut nz := 0;
	let mut s = 0;
	let mut e = sz / 2;
	if i == 1 {
	s = sz/2;
	e = data.len();
	}
	for i in s..(e - 1) {
	if data[i] != 0 (
	nz = nz + 1
	}
	}
	tx.send(nz).unwrap();
	});
	}
	let res = rx.recv().unwrap() +
	rx.recv().unwrap();
	println!(.{}., res);
}
\end{cfa}
\end{tabular}
\end{flushleft}

}% local change to lstlising to reduce font size


\subsection{Summary of Language Comparison}
\end{comment}


\subsection[C++]{\CC}

\Index*[C++]{\CC{}} is a general-purpose programming language.
It has imperative, object-oriented and generic programming features, while also providing facilities for low-level memory manipulation. (Wikipedia)

The primary focus of \CC seems to be adding object-oriented programming to C, and this is the primary difference between \CC and Do.
\CC uses classes to encapsulate data and the functions that operate on that data, and to hide the internal representation of the data.
\CFA uses modules instead to perform these same tasks.
Classes in \CC also enable inheritance among types.
Instead of inheritance, \CFA embraces composition and interfaces to achieve the same goals with more flexibility.
There are many studies and articles comparing inheritance and composition (or is-a versus has-a relationships), so we will not go into more detail here (Venners, 1998) (Pike, \Index*{Go} at Google: Language Design in the Service of Software Engineering , 2012).

Overloading in \CFA is very similar to overloading in \CC, with the exception of the additional use, in \CFA, of the return type to differentiate between overloaded functions.
References and exceptions in \CFA are heavily based on the same features from \CC.
The mechanism for interoperating with C code in \CFA is also borrowed from \CC.

Both \CFA and \CC provide generics, and the syntax is quite similar.
The key difference between the two, is that in \CC templates are expanded at compile time for each type for which the template is instantiated, while in \CFA, function pointers are used to make the generic fully compilable.
This means that a generic function can be defined in a compiled library, and still be used as expected from source.


\subsection{Go}

\Index*{Go}, also commonly referred to as golang, is a programming language developed at Google in 2007 [.].
It is a statically typed language with syntax loosely derived from that of C, adding garbage collection, type
safety, some structural typing capabilities, additional built-in types such as variable-length arrays and key-value maps, and a large standard library. (Wikipedia)

Go and \CFA differ significantly in syntax and implementation, but the underlying core concepts of the two languages are aligned.
Both Go and \CFA use composition and interfaces as opposed to inheritance to enable encapsulation and abstraction.
Both languages (along with their tooling ecosystem) provide a simple packaging mechanism for building units of code for easy sharing and reuse.
Both languages also include built-in light weight, user level threading concurrency features that attempt to simplify the effort and thought process required for writing parallel programs while maintaining high performance.

Go has a significant runtime which handles the scheduling of its light weight threads, and performs garbage collection, among other tasks.
\CFA uses a cooperative scheduling algorithm for its tasks, and uses automatic reference counting to enable advanced memory management without garbage collection.
This results in Go requiring significant overhead to interface with C libraries while \CFA has no overhead.


\subsection{Rust}

\Index*{Rust} is a general-purpose, multi-paradigm, compiled programming language developed by Mozilla Research.
It is designed to be a "safe, concurrent, practical language", supporting pure-functional, concurrent-actor[dubious . discuss][citation needed], imperative-procedural, and object-oriented styles.

The primary focus of Rust is in safety, especially in concurrent programs.
To enforce a high level of safety, Rust has added ownership as a core feature of the language to guarantee memory safety.
This safety comes at the cost of a difficult learning curve, a change in the thought model of the program, and often some runtime overhead.

Aside from those key differences, Rust and \CFA also have several similarities.
Both languages support no overhead interoperability with C and have minimal runtimes.
Both languages support inheritance and polymorphism through the use of interfaces (traits).


\subsection{D}

The \Index*{D} programming language is an object-oriented, imperative, multi-paradigm system programming
language created by Walter Bright of Digital Mars and released in 2001. [.]
Though it originated as a re-engineering of \CC, D is a distinct language, having redesigned some core \CC features while also taking inspiration from other languages, notably \Index*{Java}, \Index*{Python}, Ruby, C\#, and Eiffel.

D and \CFA both start with C and add productivity features.
The obvious difference is that D uses classes and inheritance while \CFA uses composition and interfaces.
D is closer to \CFA than \CC since it is limited to single inheritance and also supports interfaces.
Like \CC, and unlike \CFA, D uses garbage collection and has compile-time expanded templates.
D does not have any built-in concurrency constructs in the
language, though it does have a standard library for concurrency which includes the low-level primitives for concurrency.


\appendix


\section{Syntax Ambiguities}

C has a number of syntax ambiguities, which are resolved by taking the longest sequence of overlapping characters that constitute a token.
For example, the program fragment ©x+++++y© is parsed as \lstinline[showspaces=true]@x ++ ++ + y@ because operator tokens ©++© and ©+© overlap.
Unfortunately, the longest sequence violates a constraint on increment operators, even though the parse \lstinline[showspaces=true]@x ++ + ++ y@ might yield a correct expression.
Hence, C programmers are aware that spaces have to added to disambiguate certain syntactic cases.

In \CFA, there are ambiguous cases with dereference and operator identifiers, \eg ©int *?*?()©, where the string ©*?*?© can be interpreted as:
\begin{cfa}
*?$\R{\textvisiblespace}$*? $\C{// dereference operator, dereference operator}$
*$\R{\textvisiblespace}$?*? $\C{// dereference, multiplication operator}$
\end{cfa}
By default, the first interpretation is selected, which does not yield a meaningful parse.
Therefore, \CFA does a lexical look-ahead for the second case, and backtracks to return the leading unary operator and reparses the trailing operator identifier.
Otherwise a space is needed between the unary operator and operator identifier to disambiguate this common case.

A similar issue occurs with the dereference, ©*?(...)©, and routine-call, ©?()(...)© identifiers.
The ambiguity occurs when the deference operator has no parameters:
\begin{cfa}
*?()$\R{\textvisiblespace...}$ ;
*?()$\R{\textvisiblespace...}$(...) ;
\end{cfa}
requiring arbitrary whitespace look-ahead for the routine-call parameter-list to disambiguate.
However, the dereference operator \emph{must} have a parameter/argument to dereference ©*?(...)©.
Hence, always interpreting the string ©*?()© as \lstinline[showspaces=true]@* ?()@ does not preclude any meaningful program.

The remaining cases are with the increment/decrement operators and conditional expression, \eg:
\begin{cfa}
i++?$\R{\textvisiblespace...}$(...);
i?++$\R{\textvisiblespace...}$(...);
\end{cfa}
requiring arbitrary whitespace look-ahead for the operator parameter-list, even though that interpretation is an incorrect expression (juxtaposed identifiers).
Therefore, it is necessary to disambiguate these cases with a space:
\begin{cfa}
i++$\R{\textvisiblespace}$? i : 0;
i?$\R{\textvisiblespace}$++i : 0;
\end{cfa}


\section{C Incompatibles}

The following incompatibles exist between \CFA and C, and are similar to Annex C for \CC~\cite{C++14}.


\begin{enumerate}
\item
\begin{description}
\item[Change:] add new keywords \\
New keywords are added to \CFA \see{\VRef{s:CFAKeywords}}.
\item[Rationale:] keywords added to implement new semantics of \CFA.
\item[Effect on original feature:] change to semantics of well-defined feature. \\
Any \Celeven programs using these keywords as identifiers are invalid \CFA programs.
\item[Difficulty of converting:] keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism \see{\VRef{s:BackquoteIdentifiers}}.
\item[How widely used:] clashes among new \CFA keywords and existing identifiers are rare.
\end{description}

\item
\begin{description}
\item[Change:] drop K\&R C declarations \\
K\&R declarations allow an implicit base-type of ©int©, if no type is specified, plus an alternate syntax for declaring parameters.
\eg:
\begin{cfa}
x; $\C{// int x}$
*y; $\C{// int *y}$
f( p1, p2 ); $\C{// int f( int p1, int p2 );}$
g( p1, p2 ) int p1, p2; $\C{// int g( int p1, int p2 );}$
\end{cfa}
\CFA continues to support K\&R routine definitions:
\begin{cfa}
f( a, b, c ) $\C{// default int return}$
	int a, b; char c $\C{// K\&R parameter declarations}$
{
	...
}
\end{cfa}
\item[Rationale:] dropped from \Celeven standard.\footnote{
At least one type specifier shall be given in the declaration specifiers in each declaration, and in the specifier-qualifier list in each structure declaration and type name~\cite[\S~6.7.2(2)]{C11}}
\item[Effect on original feature:] original feature is deprecated. \\
Any old C programs using these K\&R declarations are invalid \CFA programs.
\item[Difficulty of converting:] trivial to convert to \CFA.
\item[How widely used:] existing usages are rare.
\end{description}

\item
\begin{description}
\item[Change:] type of character literal ©int© to ©char© to allow more intuitive overloading:
\begin{cfa}
int rtn( int i );
int rtn( char c );
rtn( 'x' ); $\C{// programmer expects 2nd rtn to be called}$
\end{cfa}
\item[Rationale:] it is more intuitive for the call to ©rtn© to match the second version of definition of ©rtn© rather than the first.
In particular, output of ©char© variable now print a character rather than the decimal ASCII value of the character.
\begin{cfa}
sout | 'x' | " " | (int)'x';
x 120
\end{cfa}
Having to cast ©'x'© to ©char© is non-intuitive.
\item[Effect on original feature:] change to semantics of well-defined feature that depend on:
\begin{cfa}
sizeof( 'x' ) == sizeof( int )
\end{cfa}
no long work the same in \CFA programs.
\item[Difficulty of converting:] simple
\item[How widely used:] programs that depend upon ©sizeof( 'x' )© are rare and can be changed to ©sizeof(char)©.
\end{description}

\item
\begin{description}
\item[Change:] make string literals ©const©:
\begin{cfa}
char * p = "abc"; $\C{// valid in C, deprecated in \CFA}$
char * q = expr ? "abc" : "de"; $\C{// valid in C, invalid in \CFA}$
\end{cfa}
The type of a string literal is changed from ©[] char© to ©const [] char©.
Similarly, the type of a wide string literal is changed from ©[] wchar_t© to ©const [] wchar_t©.
\item[Rationale:] This change is a safety issue:
\begin{cfa}
char * p = "abc";
p[0] = 'w'; $\C{// segment fault or change constant literal}$
\end{cfa}
The same problem occurs when passing a string literal to a routine that changes its argument.
\item[Effect on original feature:] change to semantics of well-defined feature.
\item[Difficulty of converting:] simple syntactic transformation, because string literals can be converted to ©char *©.
\item[How widely used:] programs that have a legitimate reason to treat string literals as pointers to potentially modifiable memory are rare.
\end{description}

\item
\begin{description}
\item[Change:] remove \newterm{tentative definitions}, which only occurs at file scope:
\begin{cfa}
int i; $\C{// forward definition}$
int *j = @&i@; $\C{// forward reference, valid in C, invalid in \CFA}$
int i = 0; $\C{// definition}$
\end{cfa}
is valid in C, and invalid in \CFA because duplicate overloaded object definitions at the same scope level are disallowed.
This change makes it impossible to define mutually referential file-local static objects, if initializers are restricted to the syntactic forms of C. For example,
\begin{cfa}
struct X { int i; struct X *next; };
static struct X a; $\C{// forward definition}$
static struct X b = { 0, @&a@ };$\C{// forward reference, valid in C, invalid in \CFA}$
static struct X a = { 1, &b }; $\C{// definition}$
\end{cfa}
\item[Rationale:] avoids having different initialization rules for builtin types and user-defined types.
\item[Effect on original feature:] change to semantics of well-defined feature.
\item[Difficulty of converting:] the initializer for one of a set of mutually-referential file-local static objects must invoke a routine call to achieve the initialization.
\item[How widely used:] seldom
\end{description}

\item
\begin{description}
\item[Change:] have ©struct© introduce a scope for nested types:
\begin{cfa}
enum @Colour@ { R, G, B, Y, C, M };
struct Person {
	enum @Colour@ { R, G, B };	$\C[7cm]{// nested type}$
	struct Face { $\C{// nested type}$
		@Colour@ Eyes, Hair; $\C{// type defined outside (1 level)}$
	};
	@.Colour@ shirt; $\C{// type defined outside (top level)}$
	@Colour@ pants; $\C{// type defined same level}$
	Face looks[10]; $\C{// type defined same level}$
};
@Colour@ c = R; $\C{// type/enum defined same level}$
Person@.Colour@ pc = Person@.@R;$\C{// type/enum defined inside}$
Person@.@Face pretty; $\C{// type defined inside}\CRT$
\end{cfa}
In C, the name of the nested types belongs to the same scope as the name of the outermost enclosing structure, \ie the nested types are hoisted to the scope of the outer-most type, which is not useful and confusing.
\CFA is C \emph{incompatible} on this issue, and provides semantics similar to \Index*[C++]{\CC{}}.
Nested types are not hoisted and can be referenced using the field selection operator ``©.©'', unlike the \CC scope-resolution operator ``©::©''.
\item[Rationale:] ©struct© scope is crucial to \CFA as an information structuring and hiding mechanism.
\item[Effect on original feature:] change to semantics of well-defined feature.
\item[Difficulty of converting:] Semantic transformation.
\item[How widely used:] C programs rarely have nest types because they are equivalent to the hoisted version.
\end{description}

\item
\begin{description}
\item[Change:] In C++, the name of a nested class is local to its enclosing class.
\item[Rationale:] C++ classes have member functions which require that classes establish scopes.
\item[Difficulty of converting:] Semantic transformation. To make the struct type name visible in the scope of the enclosing struct, the struct tag could be declared in the scope of the enclosing struct, before the enclosing struct is defined. Example:
\begin{cfa}
struct Y; $\C{// struct Y and struct X are at the same scope}$
struct X {
	struct Y { /* ... */ } y;
};
\end{cfa}
All the definitions of C struct types enclosed in other struct definitions and accessed outside the scope of the enclosing struct could be exported to the scope of the enclosing struct.
Note: this is a consequence of the difference in scope rules, which is documented in 3.3.
\item[How widely used:] Seldom.
\end{description}

\item
\begin{description}
\item[Change:] remove implicit conversion of ©void *© to or from any ©T *© pointer:
\begin{cfa}
void foo() {
	int * b = malloc( sizeof(int) ); $\C{// implicitly convert void * to int *}$
	char * c = b; $\C{// implicitly convert int * to void *, and then void * to char *}$
}
\end{cfa}
\item[Rationale:] increase type safety
\item[Effect on original feature:] deletion of semantically well-defined feature.
\item[Difficulty of converting:] requires adding a cast \see{\VRef{s:StorageManagement} for better alternatives}:
\begin{cfa}
	int * b = (int *)malloc( sizeof(int) );
	char * c = (char *)b;
\end{cfa}
\item[How widely used:] Significant.
Some C translators already give a warning if the cast is not used.
\end{description}

\item
\begin{description}
\item[Change:] Types must be declared in declarations, not in expressions
In C, a sizeof expression or cast expression may create a new type. For example,
\begin{cfa}
p = (void*)(struct x {int i;} *)0;
\end{cfa}
declares a new type, struct x .
\item[Rationale:] This prohibition helps to clarify the location of declarations in the source code.
\item[Effect on original feature:] Deletion of a semantically welldefined feature.
\item[Difficulty of converting:] Syntactic transformation.
\item[How widely used:] Seldom.
\end{description}

\item
\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 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)]©
\item[How widely used:] Seldom.
\end{description}
\end{enumerate}


\section{\texorpdfstring{\CFA Keywords}{Cforall Keywords}}
\label{s:CFAKeywords}

\CFA introduces the following new \Index{keyword}s, which cannot be used as identifiers.

\begin{cquote}
\begin{tabular}{@{}lllllll@{}}
\begin{tabular}{@{}l@{}}
\Indexc{basetypeof}		\\
\Indexc{choose}			\\
\Indexc{coroutine}		\\
\Indexc{disable}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{enable}			\\
\Indexc{exception}		\\
\Indexc{fallthrough}	\\
\Indexc{fallthru}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{finally}		\\
\Indexc{fixup}			\\
\Indexc{forall}			\\
\Indexc{generator}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{int128}			\\
\Indexc{monitor}		\\
\Indexc{mutex}			\\
\Indexc{one_t}			\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{report}			\\
\Indexc{suspend}		\\
\Indexc{throw}			\\
\Indexc{throwResume}	\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{trait}			\\
\Indexc{try}			\\
\Indexc{virtual}		\\
\Indexc{waitfor}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{when}			\\
\Indexc{with}			\\
\Indexc{zero_t}			\\
						\\
\end{tabular}
\end{tabular}
\end{cquote}
\CFA introduces the following new \Index{quasi-keyword}s, which can be used as identifiers.
\begin{cquote}
\begin{tabular}{@{}ll@{}}
\begin{tabular}{@{}l@{}}
\Indexc{catch}			\\
\Indexc{catchResume}	\\
\Indexc{finally}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{fixup}			\\
\Indexc{or}				\\
\Indexc{timeout}		\\
\end{tabular}
\end{tabular}
\end{cquote}

\section{Standard Headers}
\label{s:StandardHeaders}

\Celeven prescribes the following standard header-files~\cite[\S~7.1.2]{C11} and \CFA adds to this list:
\begin{cquote}
\begin{tabular}{@{}llllll|l@{}}
\multicolumn{6}{c|}{C11} & \multicolumn{1}{c}{\CFA}		\\
\hline
\begin{tabular}{@{}l@{}}
\Indexc{assert.h}		\\
\Indexc{complex.h}		\\
\Indexc{ctype.h}		\\
\Indexc{errno.h}		\\
\Indexc{fenv.h}			\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc[deletekeywords=float]{float.h} \\
\Indexc{inttypes.h}		\\
\Indexc{iso646.h}		\\
\Indexc{limits.h}		\\
\Indexc{locale.h}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{math.h}			\\
\Indexc{setjmp.h}		\\
\Indexc{signal.h}		\\
\Indexc{stdalign.h}		\\
\Indexc{stdarg.h}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{stdatomic.h}	\\
\Indexc{stdbool.h}		\\
\Indexc{stddef.h}		\\
\Indexc{stdint.h}		\\
\Indexc{stdio.h}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{stdlib.h}		\\
\Indexc{stdnoreturn.h}	\\
\Indexc{string.h}		\\
\Indexc{tgmath.h}		\\
\Indexc{threads.h}		\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{time.h}			\\
\Indexc{uchar.h}		\\
\Indexc{wchar.h}		\\
\Indexc{wctype.h}		\\
						\\
\end{tabular}
&
\begin{tabular}{@{}l@{}}
\Indexc{gmp.h}			\\
\Indexc{malloc.h}		\\
\Indexc{unistd.h}		\\
						\\
						\\
\end{tabular}
\end{tabular}
\end{cquote}
For the prescribed head-files, \CFA uses header interposition to wraps these includes in an ©extern "C"©;
hence, names in these include files are not mangled\index{mangling!name} \see{\VRef{s:Interoperability}}.
All other C header files must be explicitly wrapped in ©extern "C"© to prevent name mangling.
This approach is different from \Index*[C++]{\CC{}} where the name-mangling issue is handled internally in C header-files through checks for preprocessor variable ©__cplusplus©, which adds appropriate ©extern "C"© qualifiers.


\section{Standard Library}
\label{s:StandardLibrary}

The \CFA standard-library wraps explicitly-polymorphic C routines into implicitly-polymorphic versions.


\subsection{Storage Management}
\label{s:StorageManagement}

The storage-management routines extend their C equivalents by overloading, alternate names, providing shallow type-safety, and removing the need to specify the allocation size for non-array types.

C storage management provides the following capabilities:
\begin{description}
\item[filled]
after allocation with a specified character or value.
\item[resize]
an existing allocation to decreased or increased its size.
In either case, new storage may or may not be allocated and, if there is a new allocation, as much data from the existing allocation is copied into the new allocation.
For an increase in storage size, new storage after the copied data may be filled.
\item[align]
an allocation on a specified memory boundary, \eg, an address multiple of 64 or 128 for cache-line purposes.
\item[array]
the allocation size is scaled to the specified number of array elements.
An array may be filled, resized, or aligned.
\end{description}
\VRef[Table]{t:AllocationVersusCapabilities} shows allocation routines supporting different combinations of storage-management capabilities.
\begin{table}
\centering
\begin{minipage}{0.75\textwidth}
\begin{tabular}{@{}r|l|l|l|l|l@{}}
\multicolumn{1}{c}{}&		& \multicolumn{1}{c|}{fill}	& resize	& alignment	& array	\\
\hline
C		& ©malloc©			& no			& no		& no		& no	\\
		& ©calloc©			& yes (0 only)	& no		& no		& yes	\\
		& ©realloc©			& copy			& yes		& no		& no	\\
		& ©memalign©		& no			& no		& yes		& no	\\
		& ©aligned_alloc©\footnote{Same as ©memalign© but size is an integral multiple of alignment, which is universally ignored.}
							& no			& no		& yes		& no	\\
		& ©posix_memalign©	& no			& no		& yes		& no	\\
		& ©valloc©			& no			& no		& yes (page size)& no	\\
		& ©pvalloc©\footnote{Same as ©valloc© but rounds size to multiple of page size.}
							& no			& no		& yes (page size)& no	\\
\hline
\CFA	& ©cmemalign©		& yes (0 only)	& no		& yes		& yes	\\
		& ©realloc©			& copy			& yes		& yes		& no	\\
		& ©alloc©			& no			& yes		& no		& yes	\\
		& ©alloc_set©		& yes			& yes		& no		& yes	\\
		& ©alloc_align©		& no			& yes		& yes		& yes	\\
		& ©alloc_align_set©	& yes			& yes		& yes		& yes	\\
\end{tabular}
\end{minipage}
\caption{Allocation Routines versus Storage-Management Capabilities}
\label{t:AllocationVersusCapabilities}
\end{table}

\CFA memory management extends the type safety of all allocations by using the type of the left-hand-side type to determine the allocation size and return a matching type for the new storage.
Type-safe allocation is provided for all C allocation routines and new \CFA allocation routines, \eg in
\begin{cfa}
int * ip = (int *)malloc( sizeof(int) );		$\C{// C}$
int * ip = malloc();							$\C{// \CFA type-safe version of C malloc}$
int * ip = alloc();								$\C{// \CFA type-safe uniform alloc}$
\end{cfa}
the latter two allocations determine the allocation size from the type of ©p© (©int©) and cast the pointer to the allocated storage to ©int *©.

\CFA memory management extends allocation safety by implicitly honouring all alignment requirements, \eg in
\begin{cfa}
struct S { int i; } __attribute__(( aligned( 128 ) )); // cache-line alignment
S * sp = malloc();								$\C{// honour type alignment}$
\end{cfa}
the storage allocation is implicitly aligned to 128 rather than the default 16.
The alignment check is performed at compile time so there is no runtime cost.

\CFA memory management extends the resize capability with the notion of \newterm{sticky properties}.
Hence, initial allocation capabilities are remembered and maintained when resize requires copying.
For example, an initial alignment and fill capability are preserved during a resize copy so the copy has the same alignment and extended storage is filled.
Without sticky properties it is dangerous to use ©realloc©, resulting in an idiom of manually performing the reallocation to maintain correctness.
\begin{cfa}

\end{cfa}

\CFA memory management extends allocation to support constructors for initialization of allocated storage, \eg in
\begin{cfa}
struct S { int i; };							$\C{// cache-line alignment}$
void ?{}( S & s, int i ) { s.i = i; }
// assume ?|? operator for printing an S

S & sp = *@new@( 3 );							$\C{// call constructor after allocation}$
sout | sp.i;
@delete@( &sp );

S * spa = @anew@( 10, 5 );						$\C{// allocate array and initialize each array element}$
for ( i; 10 ) sout | spa[i] | nonl;
sout | nl;
@adelete@( 10, spa );
\end{cfa}
Allocation routines ©new©/©anew© allocate a variable/array and initialize storage using the allocated type's constructor.
Note, the matching deallocation routines ©delete©/©adelete©.

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
extern "C" {
	// C unsafe allocation
	void * malloc( size_t size );$\indexc{malloc}$
	void * calloc( size_t dim, size_t size );$\indexc{calloc}$
	void * realloc( void * ptr, size_t size );$\indexc{realloc}$
	void * memalign( size_t align, size_t size );$\indexc{memalign}$
	void * aligned_alloc( size_t align, size_t size );$\indexc{aligned_alloc}$
	int posix_memalign( void ** ptr, size_t align, size_t size );$\indexc{posix_memalign}$
	void * cmemalign( size_t alignment, size_t noOfElems, size_t elemSize );$\indexc{cmemalign}$ // CFA

	// C unsafe initialization/copy
	void * memset( void * dest, int c, size_t size );$\indexc{memset}$
	void * memcpy( void * dest, const void * src, size_t size );$\indexc{memcpy}$
}

void * realloc( void * oaddr, size_t nalign, size_t size ); // CFA heap

forall( dtype T | sized(T) ) {
	// $\CFA$ safe equivalents, i.e., implicit size specification
	T * malloc( void );
	T * calloc( size_t dim );
	T * realloc( T * ptr, size_t size );
	T * memalign( size_t align );
	T * cmemalign( size_t align, size_t dim  );
	T * aligned_alloc( size_t align );
	int posix_memalign( T ** ptr, size_t align );

	// $\CFA$ safe general allocation, fill, resize, alignment, array
	T * alloc( void );$\indexc{alloc}$					$\C[3.5in]{// variable, T size}$
	T * alloc( size_t dim );							$\C{// array[dim], T size elements}$
	T * alloc( T ptr[], size_t dim );					$\C{// realloc array[dim], T size elements}$

	T * alloc_set( char fill );$\indexc{alloc_set}$		$\C{// variable, T size, fill bytes with value}$
	T * alloc_set( T fill );							$\C{// variable, T size, fill with value}$
	T * alloc_set( size_t dim, char fill );				$\C{// array[dim], T size elements, fill bytes with value}$
	T * alloc_set( size_t dim, T fill );				$\C{// array[dim], T size elements, fill elements with value}$
	T * alloc_set( size_t dim, const T fill[] );		$\C{// array[dim], T size elements, fill elements with array}$
	T * alloc_set( T ptr[], size_t dim, char fill );	$\C{// realloc array[dim], T size elements, fill bytes with value}$

	T * alloc_align( size_t align );					$\C{// aligned variable, T size}$
	T * alloc_align( size_t align, size_t dim );		$\C{// aligned array[dim], T size elements}$
	T * alloc_align( T ptr[], size_t align );			$\C{// realloc new aligned array}$
	T * alloc_align( T ptr[], size_t align, size_t dim ); $\C{// realloc new aligned array[dim]}$

	T * alloc_align_set( size_t align, char fill );		$\C{// aligned variable, T size, fill bytes with value}$
	T * alloc_align_set( size_t align, T fill );		$\C{// aligned variable, T size, fill with value}$
	T * alloc_align_set( size_t align, size_t dim, char fill ); $\C{// aligned array[dim], T size elements, fill bytes with value}$
	T * alloc_align_set( size_t align, size_t dim, T fill ); $\C{// aligned array[dim], T size elements, fill elements with value}$
	T * alloc_align_set( size_t align, size_t dim, const T fill[] ); $\C{// aligned array[dim], T size elements, fill elements with array}$
	T * alloc_align_set( T ptr[], size_t align, size_t dim, char fill ); $\C{// realloc new aligned array[dim], fill new bytes with value}$

	// $\CFA$ safe initialization/copy, i.e., implicit size specification
	T * memset( T * dest, char fill );$\indexc{memset}$
	T * memcpy( T * dest, const T * src );$\indexc{memcpy}$

	// $\CFA$ safe initialization/copy, i.e., implicit size specification, array types
	T * amemset( T dest[], char fill, size_t dim );
	T * amemcpy( T dest[], const T src[], size_t dim );
}

// $\CFA$ allocation/deallocation and constructor/destructor, non-array types
forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * new( Params p );$\indexc{new}$
forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void delete( T * ptr );$\indexc{delete}$
forall( dtype T, ttype Params | sized(T) | { void ^?{}( T & ); void delete( Params ); } )
  void delete( T * ptr, Params rest );

// $\CFA$ allocation/deallocation and constructor/destructor, array types
forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * anew( size_t dim, Params p );$\indexc{anew}$
forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void adelete( size_t dim, T arr[] );$\indexc{adelete}$
forall( dtype T | sized(T) | { void ^?{}( T & ); }, ttype Params | { void adelete( Params ); } )
  void adelete( size_t dim, T arr[], Params rest );
\end{cfa}


\subsection{String to Value Conversion}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
int ato( const char * ptr );$\indexc{ato}$
unsigned int ato( const char * ptr );
long int ato( const char * ptr );
unsigned long int ato( const char * ptr );
long long int ato( const char * ptr );
unsigned long long int ato( const char * ptr );
float ato( const char * ptr );
double ato( const char * ptr );
long double ato( const char * ptr );
float _Complex ato( const char * ptr );
double _Complex ato( const char * ptr );
long double _Complex ato( const char * ptr );

int strto( const char * sptr, char ** eptr, int base );
unsigned int strto( const char * sptr, char ** eptr, int base );
long int strto( const char * sptr, char ** eptr, int base );
unsigned long int strto( const char * sptr, char ** eptr, int base );
long long int strto( const char * sptr, char ** eptr, int base );
unsigned long long int strto( const char * sptr, char ** eptr, int base );
float strto( const char * sptr, char ** eptr );
double strto( const char * sptr, char ** eptr );
long double strto( const char * sptr, char ** eptr );
float _Complex strto( const char * sptr, char ** eptr );
double _Complex strto( const char * sptr, char ** eptr );
long double _Complex strto( const char * sptr, char ** eptr );
\end{cfa}


\subsection{Search / Sort}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
forall( otype T | { int ?<?( T, T ); } ) $\C{// location}$
T * bsearch( T key, const T * arr, size_t dim );$\indexc{bsearch}$

forall( otype T | { int ?<?( T, T ); } ) $\C{// position}$
unsigned int bsearch( T key, const T * arr, size_t dim );

forall( otype T | { int ?<?( T, T ); } )
void qsort( const T * arr, size_t dim );$\indexc{qsort}$

forall( otype E | { int ?<?( E, E ); } ) {
	E * bsearch( E key, const E * vals, size_t dim );$\indexc{bsearch}$ $\C{// location}$
	size_t bsearch( E key, const E * vals, size_t dim );$\C{// position}$
	E * bsearchl( E key, const E * vals, size_t dim );$\indexc{bsearchl}$
	size_t bsearchl( E key, const E * vals, size_t dim );
	E * bsearchu( E key, const E * vals, size_t dim );$\indexc{bsearchu}$
	size_t bsearchu( E key, const E * vals, size_t dim );
}

forall( otype K, otype E | { int ?<?( K, K ); K getKey( const E & ); } ) {
	E * bsearch( K key, const E * vals, size_t dim );
	size_t bsearch( K key, const E * vals, size_t dim );
	E * bsearchl( K key, const E * vals, size_t dim );
	size_t bsearchl( K key, const E * vals, size_t dim );
	E * bsearchu( K key, const E * vals, size_t dim );
	size_t bsearchu( K key, const E * vals, size_t dim );
}

forall( otype E | { int ?<?( E, E ); } ) {
	void qsort( E * vals, size_t dim );$\indexc{qsort}$
}
\end{cfa}


\subsection{Absolute Value}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
unsigned char abs( signed char );$\indexc{abs}$
int abs( int );
unsigned long int abs( long int );
unsigned long long int abs( long long int );
float abs( float );
double abs( double );
long double abs( long double );
float abs( float _Complex );
double abs( double _Complex );
long double abs( long double _Complex );
forall( otype T | { void ?{}( T *, zero_t ); int ?<?( T, T ); T -?( T ); } )
T abs( T );
\end{cfa}


\subsection{Random Numbers}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
void srandom( unsigned int seed );$\indexc{srandom}$
char random( void );$\indexc{random}$
char random( char u ); $\C{// [0,u)}$
char random( char l, char u ); $\C{// [l,u)}$
int random( void );
int random( int u ); $\C{// [0,u)}$
int random( int l, int u ); $\C{// [l,u)}$
unsigned int random( void );
unsigned int random( unsigned int u ); $\C{// [0,u)}$
unsigned int random( unsigned int l, unsigned int u ); $\C{// [l,u)}$
long int random( void );
long int random( long int u ); $\C{// [0,u)}$
long int random( long int l, long int u ); $\C{// [l,u)}$
unsigned long int random( void );
unsigned long int random( unsigned long int u ); $\C{// [0,u)}$
unsigned long int random( unsigned long int l, unsigned long int u ); $\C{// [l,u)}$
float random( void );						 $\C{// [0.0, 1.0)}$
double random( void );						 $\C{// [0.0, 1.0)}$
float _Complex random( void );				 $\C{// [0.0, 1.0)+[0.0, 1.0)i}$
double _Complex random( void );				 $\C{// [0.0, 1.0)+[0.0, 1.0)i}$
long double _Complex random( void );		 $\C{// [0.0, 1.0)+[0.0, 1.0)i}$
\end{cfa}


\subsection{Algorithms}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
forall( otype T | { int ?<?( T, T ); } ) T min( T t1, T t2 );$\indexc{min}$
forall( otype T | { int ?>?( T, T ); } ) T max( T t1, 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 ) void swap( T * t1, T * t2 );$\indexc{swap}$
\end{cfa}


\section{Math Library}
\label{s:Math Library}

The \CFA math-library wraps explicitly-polymorphic C math-routines into implicitly-polymorphic versions.


\subsection{General}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float ?%?( float, float );$\indexc{fmod}$
float fmod( float, float );
double ?%?( double, double );
double fmod( double, double );
long double ?%?( long double, long double );
long double fmod( long double, long double );

float remainder( float, float );$\indexc{remainder}$
double remainder( double, double );
long double remainder( long double, long double );

float remquo( float, float, int * );$\indexc{remquo}$
double remquo( double, double, int * );
long double remquo( long double, long double, int * );
[ int, float ] remquo( float, float );
[ int, double ] remquo( double, double );
[ int, long double ] remquo( long double, long double );

float div( float, float, int * );$\indexc{div}$ $\C{// alternative name for remquo}$
double div( double, double, int * );
long double div( long double, long double, int * );
[ int, float ] div( float, float );
[ int, double ] div( double, double );
[ int, long double ] div( long double, long double );

float fma( float, float, float );$\indexc{fma}$
double fma( double, double, double );
long double fma( long double, long double, long double );

float fdim( float, float );$\indexc{fdim}$
double fdim( double, double );
long double fdim( long double, long double );

float nan( const char * );$\indexc{nan}$
double nan( const char * );
long double nan( const char * );
\end{cfa}


\subsection{Exponential}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float exp( float );$\indexc{exp}$
double exp( double );
long double exp( long double );
float _Complex exp( float _Complex );
double _Complex exp( double _Complex );
long double _Complex exp( long double _Complex );

float exp2( float );$\indexc{exp2}$
double exp2( double );
long double exp2( long double );
// float _Complex exp2( float _Complex );
// double _Complex exp2( double _Complex );
// long double _Complex exp2( long double _Complex );

float expm1( float );$\indexc{expm1}$
double expm1( double );
long double expm1( long double );

float pow( float, float );$\indexc{pow}$
double pow( double, double );
long double pow( long double, long double );
float _Complex pow( float _Complex, float _Complex );
double _Complex pow( double _Complex, double _Complex );
long double _Complex pow( long double _Complex, long double _Complex );
\end{cfa}


\subsection{Logarithm}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float log( float );$\indexc{log}$
double log( double );
long double log( long double );
float _Complex log( float _Complex );
double _Complex log( double _Complex );
long double _Complex log( long double _Complex );

float log2( float );$\indexc{log2}$
double log2( double );
long double log2( long double );
// float _Complex log2( float _Complex );
// double _Complex log2( double _Complex );
// long double _Complex log2( long double _Complex );

float log10( float );$\indexc{log10}$
double log10( double );
long double log10( long double );
// float _Complex log10( float _Complex );
// double _Complex log10( double _Complex );
// long double _Complex log10( long double _Complex );

float log1p( float );$\indexc{log1p}$
double log1p( double );
long double log1p( long double );

int ilogb( float );$\indexc{ilogb}$
int ilogb( double );
int ilogb( long double );

float logb( float );$\indexc{logb}$
double logb( double );
long double logb( long double );

float sqrt( float );$\indexc{sqrt}$
double sqrt( double );
long double sqrt( long double );
float _Complex sqrt( float _Complex );
double _Complex sqrt( double _Complex );
long double _Complex sqrt( long double _Complex );

float cbrt( float );$\indexc{cbrt}$
double cbrt( double );
long double cbrt( long double );

float hypot( float, float );$\indexc{hypot}$
double hypot( double, double );
long double hypot( long double, long double );
\end{cfa}


\subsection{Trigonometric}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float sin( float );$\indexc{sin}$
double sin( double );
long double sin( long double );
float _Complex sin( float _Complex );
double _Complex sin( double _Complex );
long double _Complex sin( long double _Complex );

float cos( float );$\indexc{cos}$
double cos( double );
long double cos( long double );
float _Complex cos( float _Complex );
double _Complex cos( double _Complex );
long double _Complex cos( long double _Complex );

float tan( float );$\indexc{tan}$
double tan( double );
long double tan( long double );
float _Complex tan( float _Complex );
double _Complex tan( double _Complex );
long double _Complex tan( long double _Complex );

float asin( float );$\indexc{asin}$
double asin( double );
long double asin( long double );
float _Complex asin( float _Complex );
double _Complex asin( double _Complex );
long double _Complex asin( long double _Complex );

float acos( float );$\indexc{acos}$
double acos( double );
long double acos( long double );
float _Complex acos( float _Complex );
double _Complex acos( double _Complex );
long double _Complex acos( long double _Complex );

float atan( float );$\indexc{atan}$
double atan( double );
long double atan( long double );
float _Complex atan( float _Complex );
double _Complex atan( double _Complex );
long double _Complex atan( long double _Complex );

float atan2( float, float );$\indexc{atan2}$
double atan2( double, double );
long double atan2( long double, long double );

float atan( float, float ); $\C{// alternative name for atan2}$
double atan( double, double );$\indexc{atan}$
long double atan( long double, long double );
\end{cfa}


\subsection{Hyperbolic}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float sinh( float );$\indexc{sinh}$
double sinh( double );
long double sinh( long double );
float _Complex sinh( float _Complex );
double _Complex sinh( double _Complex );
long double _Complex sinh( long double _Complex );

float cosh( float );$\indexc{cosh}$
double cosh( double );
long double cosh( long double );
float _Complex cosh( float _Complex );
double _Complex cosh( double _Complex );
long double _Complex cosh( long double _Complex );

float tanh( float );$\indexc{tanh}$
double tanh( double );
long double tanh( long double );
float _Complex tanh( float _Complex );
double _Complex tanh( double _Complex );
long double _Complex tanh( long double _Complex );

float asinh( float );$\indexc{asinh}$
double asinh( double );
long double asinh( long double );
float _Complex asinh( float _Complex );
double _Complex asinh( double _Complex );
long double _Complex asinh( long double _Complex );

float acosh( float );$\indexc{acosh}$
double acosh( double );
long double acosh( long double );
float _Complex acosh( float _Complex );
double _Complex acosh( double _Complex );
long double _Complex acosh( long double _Complex );

float atanh( float );$\indexc{atanh}$
double atanh( double );
long double atanh( long double );
float _Complex atanh( float _Complex );
double _Complex atanh( double _Complex );
long double _Complex atanh( long double _Complex );
\end{cfa}


\subsection{Error / Gamma}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float erf( float );$\indexc{erf}$
double erf( double );
long double erf( long double );
float _Complex erf( float _Complex );
double _Complex erf( double _Complex );
long double _Complex erf( long double _Complex );

float erfc( float );$\indexc{erfc}$
double erfc( double );
long double erfc( long double );
float _Complex erfc( float _Complex );
double _Complex erfc( double _Complex );
long double _Complex erfc( long double _Complex );

float lgamma( float );$\indexc{lgamma}$
double lgamma( double );
long double lgamma( long double );
float lgamma( float, int * );
double lgamma( double, int * );
long double lgamma( long double, int * );

float tgamma( float );$\indexc{tgamma}$
double tgamma( double );
long double tgamma( long double );
\end{cfa}


\subsection{Nearest Integer}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float floor( float );$\indexc{floor}$
double floor( double );
long double floor( long double );

float ceil( float );$\indexc{ceil}$
double ceil( double );
long double ceil( long double );

float trunc( float );$\indexc{trunc}$
double trunc( double );
long double trunc( long double );

float rint( float );$\indexc{rint}$
long double rint( long double );
long int rint( float );
long int rint( double );
long int rint( long double );
long long int rint( float );
long long int rint( double );
long long int rint( long double );

long int lrint( float );$\indexc{lrint}$
long int lrint( double );
long int lrint( long double );
long long int llrint( float );
long long int llrint( double );
long long int llrint( long double );

float nearbyint( float );$\indexc{nearbyint}$
double nearbyint( double );
long double nearbyint( long double );

float round( float );$\indexc{round}$
long double round( long double );
long int round( float );
long int round( double );
long int round( long double );
long long int round( float );
long long int round( double );
long long int round( long double );

long int lround( float );$\indexc{lround}$
long int lround( double );
long int lround( long double );
long long int llround( float );
long long int llround( double );
long long int llround( long double );
\end{cfa}


\subsection{Manipulation}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
float copysign( float, float );$\indexc{copysign}$
double copysign( double, double );
long double copysign( long double, long double );

float frexp( float, int * );$\indexc{frexp}$
double frexp( double, int * );
long double frexp( long double, int * );

float ldexp( float, int );$\indexc{ldexp}$
double ldexp( double, int );
long double ldexp( long double, int );

[ float, float ] modf( float );$\indexc{modf}$
float modf( float, float * );
[ double, double ] modf( double );
double modf( double, double * );
[ long double, long double ] modf( long double );
long double modf( long double, long double * );

float nextafter( float, float );$\indexc{nextafter}$
double nextafter( double, double );
long double nextafter( long double, long double );

float nexttoward( float, long double );$\indexc{nexttoward}$
double nexttoward( double, long double );
long double nexttoward( long double, long double );

float scalbn( float, int );$\indexc{scalbn}$
double scalbn( double, int );
long double scalbn( long double, int );

float scalbln( float, long int );$\indexc{scalbln}$
double scalbln( double, long int );
long double scalbln( long double, long int );
\end{cfa}


\section{Time Keeping}
\label{s:TimeKeeping}


%\subsection{\texorpdfstring{\protect\lstinline@Duration@}{Duration}}
\subsection{\texorpdfstring{\LstBasicStyle{Duration}}{Duration}}
\label{s:Duration}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
struct Duration {
	int64_t tv; $\C{// nanoseconds}$
};

void ?{}( Duration & dur );
void ?{}( Duration & dur, zero_t );

Duration ?=?( Duration & dur, zero_t );

Duration +?( Duration rhs );
Duration ?+?( Duration & lhs, Duration rhs );
Duration ?+=?( Duration & lhs, Duration rhs );

Duration -?( Duration rhs );
Duration ?-?( Duration & lhs, Duration rhs );
Duration ?-=?( Duration & lhs, Duration rhs );

Duration ?*?( Duration lhs, int64_t rhs );
Duration ?*?( int64_t lhs, Duration rhs );
Duration ?*=?( Duration & lhs, int64_t rhs );

int64_t ?/?( Duration lhs, Duration rhs );
Duration ?/?( Duration lhs, int64_t rhs );
Duration ?/=?( Duration & lhs, int64_t rhs );
double div( Duration lhs, Duration rhs );

Duration ?%?( Duration lhs, Duration rhs );
Duration ?%=?( Duration & lhs, Duration rhs );

_Bool ?==?( Duration lhs, Duration rhs );
_Bool ?!=?( Duration lhs, Duration rhs );
_Bool ?<? ( Duration lhs, Duration rhs );
_Bool ?<=?( Duration lhs, Duration rhs );
_Bool ?>? ( Duration lhs, Duration rhs );
_Bool ?>=?( Duration lhs, Duration rhs );

_Bool ?==?( Duration lhs, zero_t );
_Bool ?!=?( Duration lhs, zero_t );
_Bool ?<? ( Duration lhs, zero_t );
_Bool ?<=?( Duration lhs, zero_t );
_Bool ?>? ( Duration lhs, zero_t );
_Bool ?>=?( Duration lhs, zero_t );

Duration abs( Duration rhs );

Duration ?`ns( int64_t nsec );
Duration ?`us( int64_t usec );
Duration ?`ms( int64_t msec );
Duration ?`s( int64_t sec );
Duration ?`s( double sec );
Duration ?`m( int64_t min );
Duration ?`m( double min );
Duration ?`h( int64_t hours );
Duration ?`h( double hours );
Duration ?`d( int64_t days );
Duration ?`d( double days );
Duration ?`w( int64_t weeks );
Duration ?`w( double weeks );

int64_t ?`ns( Duration dur );
int64_t ?`us( Duration dur );
int64_t ?`ms( Duration dur );
int64_t ?`s( Duration dur );
int64_t ?`m( Duration dur );
int64_t ?`h( Duration dur );
int64_t ?`d( Duration dur );
int64_t ?`w( Duration dur );

Duration max( Duration lhs, Duration rhs );
Duration min( Duration lhs, Duration rhs );
\end{cfa}


%\subsection{\texorpdfstring{\protect\lstinline@\timeval@}{timeval}}
\subsection{\texorpdfstring{\LstBasicStyle{timeval}}{timeval}}
\label{s:timeval}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
void ?{}( timeval & t );
void ?{}( timeval & t, time_t sec, suseconds_t usec );
void ?{}( timeval & t, time_t sec );
void ?{}( timeval & t, zero_t );
void ?{}( timeval & t, Time time );

timeval ?=?( timeval & t, zero_t );
timeval ?+?( timeval & lhs, timeval rhs );
timeval ?-?( timeval & lhs, timeval rhs );
_Bool ?==?( timeval lhs, timeval rhs );
_Bool ?!=?( timeval lhs, timeval rhs );
\end{cfa}


%\subsection{\texorpdfstring{\protect\lstinline@timespec@}{timespec}}
\subsection{\texorpdfstring{\LstBasicStyle{timespec}}{timespec}}
\label{s:timespec}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
void ?{}( timespec & t );
void ?{}( timespec & t, time_t sec, __syscall_slong_t nsec );
void ?{}( timespec & t, time_t sec );
void ?{}( timespec & t, zero_t );
void ?{}( timespec & t, Time time );

timespec ?=?( timespec & t, zero_t );
timespec ?+?( timespec & lhs, timespec rhs );
timespec ?-?( timespec & lhs, timespec rhs );
_Bool ?==?( timespec lhs, timespec rhs );
_Bool ?!=?( timespec lhs, timespec rhs );
\end{cfa}


%\subsection{\texorpdfstring{\protect\lstinline@itimerval@}{itimerval}}
\subsection{\texorpdfstring{\LstBasicStyle{itimerval}}{itimerval}}
\label{s:itimerval}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
void ?{}( itimerval & itv, Duration alarm );
void ?{}( itimerval & itv, Duration alarm, Duration interval );
\end{cfa}


%\subsection{\texorpdfstring{\protect\lstinline@Time@}{Time}}
\subsection{\texorpdfstring{\LstBasicStyle{Time}}{Time}}
\label{s:Time}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
struct Time {
	uint64_t tv; $\C{// nanoseconds since UNIX epoch}$
};

void ?{}( Time & time );
void ?{}( Time & time, zero_t );

Time ?=?( Time & time, zero_t );

void ?{}( Time & time, timeval t );
Time ?=?( Time & time, timeval t );

void ?{}( Time & time, timespec t );
Time ?=?( Time & time, timespec t );

Time ?+?( Time & lhs, Duration rhs );
Time ?+?( Duration lhs, Time rhs );
Time ?+=?( Time & lhs, Duration rhs );

Duration ?-?( Time lhs, Time rhs );
Time ?-?( Time lhs, Duration rhs );
Time ?-=?( Time & lhs, Duration rhs );
_Bool ?==?( Time lhs, Time rhs );
_Bool ?!=?( Time lhs, Time rhs );
_Bool ?<?( Time lhs, Time rhs );
_Bool ?<=?( Time lhs, Time rhs );
_Bool ?>?( Time lhs, Time rhs );
_Bool ?>=?( Time lhs, Time rhs );

char * yy_mm_dd( Time time, char * buf );
char * ?`ymd( Time time, char * buf ) {	// short form
	return yy_mm_dd( time, buf );
} // ymd

char * mm_dd_yy( Time time, char * buf );
char * ?`mdy( Time time, char * buf ) {	// short form
	return mm_dd_yy( time, buf );
} // mdy

char * dd_mm_yy( Time time, char * buf );
char * ?`dmy( Time time, char * buf ) {	// short form
	return dd_mm_yy( time, buf );;
} // dmy

size_t strftime( char * buf, size_t size, const char * fmt, Time time );
forall( dtype ostype | ostream( ostype ) ) ostype & ?|?( ostype & os, Time time );
\end{cfa}


\section{Clock}

\subsection{C time}
\label{s:Ctime}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
char * ctime( time_t tp );
char * ctime_r( time_t tp, char * buf );
tm * gmtime( time_t tp );
tm * gmtime_r( time_t tp, tm * result );
tm * localtime( time_t tp );
tm * localtime_r( time_t tp, tm * result );
\end{cfa}


%\subsection{\texorpdfstring{\protect\lstinline@Clock@}{Clock}}
\subsection{\texorpdfstring{\LstBasicStyle{Clock}}{Clock}}
\label{s:Clock}

\leavevmode
\begin{cfa}[aboveskip=0pt,belowskip=0pt]
struct Clock {
	Duration offset; $\C{// for virtual clock: contains offset from real-time}$
	int clocktype; $\C{// implementation only -1 (virtual), CLOCK\_REALTIME}$
};

void resetClock( Clock & clk );
void resetClock( Clock & clk, Duration adj );
void ?{}( Clock & clk );
void ?{}( Clock & clk, Duration adj );

Duration getResNsec(); $\C{// with nanoseconds}$
Duration getRes(); $\C{// without nanoseconds}$

Time getTimeNsec(); $\C{// with nanoseconds}$
Time getTime(); $\C{// without nanoseconds}$
Time getTime( Clock & clk );
Time ?()( Clock & clk );
timeval getTime( Clock & clk );
tm getTime( Clock & clk );
\end{cfa}


\section{Multi-precision Integers}
\label{s:MultiPrecisionIntegers}

\CFA has an interface to the GMP \Index{multi-precision} signed-integers~\cite{GMP}, similar to the \CC interface provided by GMP.
The \CFA interface wraps GMP routines into operator routines to make programming with multi-precision integers identical to using fixed-sized integers.
The \CFA type name for multi-precision signed-integers is \Indexc{Int} and the header file is \Indexc{gmp}.

\begin{cfa}
void ?{}( Int * this ); $\C{// constructor/destructor}$
void ?{}( Int * this, Int init );
void ?{}( Int * this, zero_t );
void ?{}( Int * this, one_t );
void ?{}( Int * this, signed long int init );
void ?{}( Int * this, unsigned long int init );
void ?{}( Int * this, const char * val );
void ^?{}( Int * this );

Int ?=?( Int * lhs, Int rhs ); $\C{// assignment}$
Int ?=?( Int * lhs, long int rhs );
Int ?=?( Int * lhs, unsigned long int rhs );
Int ?=?( Int * lhs, const char * rhs );

char ?=?( char * lhs, Int rhs );
short int ?=?( short int * lhs, Int rhs );
int ?=?( int * lhs, Int rhs );
long int ?=?( long int * lhs, Int rhs );
unsigned char ?=?( unsigned char * lhs, Int rhs );
unsigned short int ?=?( unsigned short int * lhs, Int rhs );
unsigned int ?=?( unsigned int * lhs, Int rhs );
unsigned long int ?=?( unsigned long int * lhs, Int rhs );

long int narrow( Int val );
unsigned long int narrow( Int val );

int ?==?( Int oper1, Int oper2 ); $\C{// comparison}$
int ?==?( Int oper1, long int oper2 );
int ?==?( long int oper2, Int oper1 );
int ?==?( Int oper1, unsigned long int oper2 );
int ?==?( unsigned long int oper2, Int oper1 );

int ?!=?( Int oper1, Int oper2 );
int ?!=?( Int oper1, long int oper2 );
int ?!=?( long int oper1, Int oper2 );
int ?!=?( Int oper1, unsigned long int oper2 );
int ?!=?( unsigned long int oper1, Int oper2 );

int ?<?( Int oper1, Int oper2 );
int ?<?( Int oper1, long int oper2 );
int ?<?( long int oper2, Int oper1 );
int ?<?( Int oper1, unsigned long int oper2 );
int ?<?( unsigned long int oper2, Int oper1 );

int ?<=?( Int oper1, Int oper2 );
int ?<=?( Int oper1, long int oper2 );
int ?<=?( long int oper2, Int oper1 );
int ?<=?( Int oper1, unsigned long int oper2 );
int ?<=?( unsigned long int oper2, Int oper1 );

int ?>?( Int oper1, Int oper2 );
int ?>?( Int oper1, long int oper2 );
int ?>?( long int oper1, Int oper2 );
int ?>?( Int oper1, unsigned long int oper2 );
int ?>?( unsigned long int oper1, Int oper2 );

int ?>=?( Int oper1, Int oper2 );
int ?>=?( Int oper1, long int oper2 );
int ?>=?( long int oper1, Int oper2 );
int ?>=?( Int oper1, unsigned long int oper2 );
int ?>=?( unsigned long int oper1, Int oper2 );

Int +?( Int oper ); $\C{// arithmetic}$
Int -?( Int oper );
Int ~?( Int oper );

Int ?&?( Int oper1, Int oper2 );
Int ?&?( Int oper1, long int oper2 );
Int ?&?( long int oper1, Int oper2 );
Int ?&?( Int oper1, unsigned long int oper2 );
Int ?&?( unsigned long int oper1, Int oper2 );
Int ?&=?( Int * lhs, Int rhs );

Int ?|?( Int oper1, Int oper2 );
Int ?|?( Int oper1, long int oper2 );
Int ?|?( long int oper1, Int oper2 );
Int ?|?( Int oper1, unsigned long int oper2 );
Int ?|?( unsigned long int oper1, Int oper2 );
Int ?|=?( Int * lhs, Int rhs );

Int ?^?( Int oper1, Int oper2 );
Int ?^?( Int oper1, long int oper2 );
Int ?^?( long int oper1, Int oper2 );
Int ?^?( Int oper1, unsigned long int oper2 );
Int ?^?( unsigned long int oper1, Int oper2 );
Int ?^=?( Int * lhs, Int rhs );

Int ?+?( Int addend1, Int addend2 );
Int ?+?( Int addend1, long int addend2 );
Int ?+?( long int addend2, Int addend1 );
Int ?+?( Int addend1, unsigned long int addend2 );
Int ?+?( unsigned long int addend2, Int addend1 );
Int ?+=?( Int * lhs, Int rhs );
Int ?+=?( Int * lhs, long int rhs );
Int ?+=?( Int * lhs, unsigned long int rhs );
Int ++?( Int * lhs );
Int ?++( Int * lhs );

Int ?-?( Int minuend, Int subtrahend );
Int ?-?( Int minuend, long int subtrahend );
Int ?-?( long int minuend, Int subtrahend );
Int ?-?( Int minuend, unsigned long int subtrahend );
Int ?-?( unsigned long int minuend, Int subtrahend );
Int ?-=?( Int * lhs, Int rhs );
Int ?-=?( Int * lhs, long int rhs );
Int ?-=?( Int * lhs, unsigned long int rhs );
Int --?( Int * lhs );
Int ?--( Int * lhs );

Int ?*?( Int multiplicator, Int multiplicand );
Int ?*?( Int multiplicator, long int multiplicand );
Int ?*?( long int multiplicand, Int multiplicator );
Int ?*?( Int multiplicator, unsigned long int multiplicand );
Int ?*?( unsigned long int multiplicand, Int multiplicator );
Int ?*=?( Int * lhs, Int rhs );
Int ?*=?( Int * lhs, long int rhs );
Int ?*=?( Int * lhs, unsigned long int rhs );

Int ?/?( Int dividend, Int divisor );
Int ?/?( Int dividend, unsigned long int divisor );
Int ?/?( unsigned long int dividend, Int divisor );
Int ?/?( Int dividend, long int divisor );
Int ?/?( long int dividend, Int divisor );
Int ?/=?( Int * lhs, Int rhs );
Int ?/=?( Int * lhs, long int rhs );
Int ?/=?( Int * lhs, unsigned long int rhs );

[ Int, Int ] div( Int dividend, Int divisor );
[ Int, Int ] div( Int dividend, unsigned long int divisor );

Int ?%?( Int dividend, Int divisor );
Int ?%?( Int dividend, unsigned long int divisor );
Int ?%?( unsigned long int dividend, Int divisor );
Int ?%?( Int dividend, long int divisor );
Int ?%?( long int dividend, Int divisor );
Int ?%=?( Int * lhs, Int rhs );
Int ?%=?( Int * lhs, long int rhs );
Int ?%=?( Int * lhs, unsigned long int rhs );

Int ?<<?( Int shiften, mp_bitcnt_t shift );
Int ?<<=?( Int * lhs, mp_bitcnt_t shift );
Int ?>>?( Int shiften, mp_bitcnt_t shift );
Int ?>>=?( Int * lhs, mp_bitcnt_t shift );

Int abs( Int oper ); $\C{// number functions}$
Int fact( unsigned long int N );
Int gcd( Int oper1, Int oper2 );
Int pow( Int base, unsigned long int exponent );
Int pow( unsigned long int base, unsigned long int exponent );
void srandom( gmp_randstate_t state );
Int random( gmp_randstate_t state, mp_bitcnt_t n );
Int random( gmp_randstate_t state, Int n );
Int random( gmp_randstate_t state, mp_size_t max_size );
int sgn( Int oper );
Int sqrt( Int oper );

forall( dtype istype | istream( istype ) ) istype * ?|?( istype * is, Int * mp );  $\C{// I/O}$
forall( dtype ostype | ostream( ostype ) ) ostype * ?|?( ostype * os, Int mp );
\end{cfa}

The following factorial programs contrast using GMP with the \CFA and C interfaces, where the output from these programs appears in \VRef[Figure]{f:MultiPrecisionFactorials}.
(Compile with flag \Indexc{-lgmp} to link with the GMP library.)
\begin{cquote}
\begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
\multicolumn{1}{c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}}	& \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}}	\\
\hline
\begin{cfa}
#include <gmp>$\indexc{gmp}$
int main( void ) {
	sout | "Factorial Numbers";
	Int fact = 1;

	sout | 0 | fact;
	for ( unsigned int i = 1; i <= 40; i += 1 ) {
		fact *= i;
		sout | i | fact;
	}
}
\end{cfa}
&
\begin{cfa}
#include <gmp.h>$\indexc{gmp.h}$
int main( void ) {
	@gmp_printf@( "Factorial Numbers\n" );
	@mpz_t@ fact;
	@mpz_init_set_ui@( fact, 1 );
	@gmp_printf@( "%d %Zd\n", 0, fact );
	for ( unsigned int i = 1; i <= 40; i += 1 ) {
		@mpz_mul_ui@( fact, fact, i );
		@gmp_printf@( "%d %Zd\n", i, fact );
	}
}
\end{cfa}
\end{tabular}
\end{cquote}

\begin{figure}
\begin{cfa}
Factorial Numbers
0 1
1 1
2 2
3 6
4 24
5 120
6 720
7 5040
8 40320
9 362880
10 3628800
11 39916800
12 479001600
13 6227020800
14 87178291200
15 1307674368000
16 20922789888000
17 355687428096000
18 6402373705728000
19 121645100408832000
20 2432902008176640000
21 51090942171709440000
22 1124000727777607680000
23 25852016738884976640000
24 620448401733239439360000
25 15511210043330985984000000
26 403291461126605635584000000
27 10888869450418352160768000000
28 304888344611713860501504000000
29 8841761993739701954543616000000
30 265252859812191058636308480000000
31 8222838654177922817725562880000000
32 263130836933693530167218012160000000
33 8683317618811886495518194401280000000
34 295232799039604140847618609643520000000
35 10333147966386144929666651337523200000000
36 371993326789901217467999448150835200000000
37 13763753091226345046315979581580902400000000
38 523022617466601111760007224100074291200000000
39 20397882081197443358640281739902897356800000000
40 815915283247897734345611269596115894272000000000
\end{cfa}
\caption{Multi-precision Factorials}
\label{f:MultiPrecisionFactorials}
\end{figure}


\section{Rational Numbers}
\label{s:RationalNumbers}

Rational numbers are numbers written as a ratio, \ie as a fraction, where the numerator (top number) and the denominator (bottom number) are whole numbers.
When creating and computing with rational numbers, results are constantly reduced to keep the numerator and denominator as small as possible.

\begin{cfa}[belowskip=0pt]
// implementation
struct Rational {$\indexc{Rational}$
	long int numerator, denominator; $\C{// invariant: denominator > 0}$
}; // Rational

Rational rational(); $\C{// constructors}$
Rational rational( long int n );
Rational rational( long int n, long int d );
void ?{}( Rational * r, zero_t );
void ?{}( Rational * r, one_t );

long int numerator( Rational r ); $\C{// numerator/denominator getter/setter}$
long int numerator( Rational r, long int n );
long int denominator( Rational r );
long int denominator( Rational r, long int d );

int ?==?( Rational l, Rational r ); $\C{// comparison}$
int ?!=?( Rational l, Rational r );
int ?<?( Rational l, Rational r );
int ?<=?( Rational l, Rational r );
int ?>?( Rational l, Rational r );
int ?>=?( Rational l, Rational r );

Rational -?( Rational r ); $\C{// arithmetic}$
Rational ?+?( Rational l, Rational r );
Rational ?-?( Rational l, Rational r );
Rational ?*?( Rational l, Rational r );
Rational ?/?( Rational l, Rational r );

double widen( Rational r ); $\C{// conversion}$
Rational narrow( double f, long int md );

forall( dtype istype | istream( istype ) ) istype * ?|?( istype *, Rational * ); // I/O
forall( dtype ostype | ostream( ostype ) ) ostype * ?|?( ostype *, Rational );
\end{cfa}

\bibliographystyle{plain}
\bibliography{pl}


\addcontentsline{toc}{section}{\indexname} % add index name to table of contents
\begin{theindex}
Italic page numbers give the location of the main entry for the referenced term.
Plain page numbers denote uses of the indexed term.
Entries for grammar non-terminals are italicized.
A typewriter font is used for grammar terminals and program identifiers.
\indexspace
\input{user.ind}
\end{theindex}


\end{document}

% Local Variables: %
% tab-width: 4 %
% fill-column: 100 %
% compile-command: "make" %
% End: %