source: doc/user/user.tex @ a1edafa

aaron-thesisarm-ehcleanup-dtorsdeferred_resndemanglerenumforall-pointer-decayjacob/cs343-translationjenkins-sandboxnew-astnew-ast-unique-exprnew-envno_listpersistent-indexerpthread-emulationqualifiedEnumresolv-newwith_gc
Last change on this file since a1edafa was 59e86eb, checked in by Peter A. Buhr <pabuhr@…>, 5 years ago

document exponentiation operator, formatting, update indexing

  • Property mode set to 100644
File size: 251.6 KB
Line 
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -*- Mode: Latex -*- %%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%%
3%% Cforall Version 1.0.0 Copyright (C) 2016 University of Waterloo
4%%
5%% The contents of this file are covered under the licence agreement in the
6%% file "LICENCE" distributed with Cforall.
7%%
8%% user.tex --
9%%
10%% Author           : Peter A. Buhr
11%% Created On       : Wed Apr  6 14:53:29 2016
12%% Last Modified By : Peter A. Buhr
13%% Last Modified On : Mon Jul 17 13:06:40 2017
14%% Update Count     : 2825
15%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16
17% requires tex packages: texlive-base texlive-latex-base tex-common texlive-humanities texlive-latex-extra texlive-fonts-recommended
18
19\documentclass[twoside,11pt]{article}
20
21%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22
23% Latex packages used in the document.
24\usepackage[T1]{fontenc}                                % allow Latin1 (extended ASCII) characters
25\usepackage{textcomp}
26\usepackage[latin1]{inputenc}
27
28\usepackage{fullpage,times,comment}
29\usepackage{epic,eepic}
30\usepackage{upquote}                                                                    % switch curled `'" to straight
31\usepackage{calc}
32\usepackage{xspace}
33\usepackage{varioref}                                                                   % extended references
34\usepackage{listings}                                                                   % format program code
35\usepackage[flushmargin]{footmisc}                                              % support label/reference in footnote
36\usepackage{latexsym}                                   % \Box glyph
37\usepackage{mathptmx}                                   % better math font with "times"
38\usepackage[usenames]{color}
39\usepackage[pagewise]{lineno}
40\renewcommand{\linenumberfont}{\scriptsize\sffamily}
41\input{common}                                          % common CFA document macros
42\usepackage[dvips,plainpages=false,pdfpagelabels,pdfpagemode=UseNone,colorlinks=true,pagebackref=true,linkcolor=blue,citecolor=blue,urlcolor=blue,pagebackref=true,breaklinks=true]{hyperref}
43\usepackage{breakurl}
44\renewcommand{\UrlFont}{\small\sf}
45
46% Default underscore is too low and wide. Cannot use lstlisting "literate" as replacing underscore
47% removes it as a variable-name character so keywords in variables are highlighted. MUST APPEAR
48% AFTER HYPERREF.
49\renewcommand{\_}{\leavevmode\makebox[1.2ex][c]{\rule{1ex}{0.075ex}}}
50\renewcommand{\textunderscore}{\leavevmode\makebox[1.2ex][c]{\rule{1ex}{0.075ex}}}
51
52\setlength{\topmargin}{-0.45in}                                                 % move running title into header
53\setlength{\headsep}{0.25in}
54
55%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
56
57\CFAStyle                                                                                               % use default CFA format-style
58
59\lstnewenvironment{C++}[1][]
60{\lstset{language=C++,moredelim=**[is][\protect\color{red}]{®}{®}#1}}
61{}
62
63% inline code ©...© (copyright symbol) emacs: C-q M-)
64% red highlighting ®...® (registered trademark symbol) emacs: C-q M-.
65% blue highlighting ß...ß (sharp s symbol) emacs: C-q M-_
66% green highlighting ¢...¢ (cent symbol) emacs: C-q M-"
67% LaTex escape §...§ (section symbol) emacs: C-q M-'
68% keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
69% math escape $...$ (dollar symbol)
70
71%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
72
73% Names used in the document.
74\newcommand{\Version}{\input{../../version}}
75\newcommand{\Textbf}[2][red]{{\color{#1}{\textbf{#2}}}}
76\newcommand{\Emph}[2][red]{{\color{#1}\textbf{\emph{#2}}}}
77\newcommand{\R}[1]{\Textbf{#1}}
78\newcommand{\B}[1]{{\Textbf[blue]{#1}}}
79\newcommand{\G}[1]{{\Textbf[OliveGreen]{#1}}}
80
81\newsavebox{\LstBox}
82
83%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
84
85\setcounter{secnumdepth}{3}                             % number subsubsections
86\setcounter{tocdepth}{3}                                % subsubsections in table of contents
87\makeindex
88
89%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
90
91\title{\Huge
92\vspace*{1in}
93\CFA (\CFL) User Manual                         \\
94Version 1.0                                                     \\
95\vspace*{0.25in}
96\huge``describe not prescribe''
97\vspace*{1in}
98}% title
99
100\author{
101\huge \CFA Team \medskip \\
102\Large Andrew Beach, Richard Bilson, Peter A. Buhr, Thierry Delisle, \smallskip \\
103\Large Glen Ditchfield, Rodolfo G. Esteves, Aaron Moss, Rob Schluntz
104}% author
105
106\date{
107DRAFT \\ \today
108}% date
109
110%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
111
112\begin{document}
113\pagestyle{headings}
114% changed after setting pagestyle
115\renewcommand{\sectionmark}[1]{\markboth{\thesection\quad #1}{\thesection\quad #1}}
116\renewcommand{\subsectionmark}[1]{\markboth{\thesubsection\quad #1}{\thesubsection\quad #1}}
117\pagenumbering{roman}
118\linenumbers                                            % comment out to turn off line numbering
119
120\maketitle
121\thispagestyle{empty}
122\vspace*{\fill}
123\noindent
124\copyright\,2016 \CFA Project \\ \\
125\noindent
126This work is licensed under the Creative Commons Attribution 4.0 International License.
127To view a copy of this license, visit {\small\url{http://creativecommons.org/licenses/by/4.0}}.
128\vspace*{1in}
129
130\clearpage
131\thispagestyle{plain}
132\pdfbookmark[1]{Contents}{section}
133\tableofcontents
134
135\clearpage
136\thispagestyle{plain}
137\pagenumbering{arabic}
138
139
140\section{Introduction}
141
142\CFA{}\index{cforall@\CFA}\footnote{Pronounced ``\Index*{C-for-all}'', and written \CFA, CFA, or \CFL.} is a modern general-purpose programming-language, designed as an evolutionary step forward for the C programming language.
143The syntax of \CFA builds from C and should look immediately familiar to C/\Index*[C++]{\CC{}} programmers.
144% Any language feature that is not described here can be assumed to be using the standard \Celeven syntax.
145\CFA adds many modern programming-language features that directly lead to increased \emph{\Index{safety}} and \emph{\Index{productivity}}, while maintaining interoperability with existing C programs and achieving similar performance.
146Like 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.
147The primary new features include parametric-polymorphic routines and types, exceptions, concurrency, and modules.
148
149One 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''.
150Programmers can cautiously add \CFA extensions to their C programs in any order and at any time to incrementally move towards safer, higher-level programming.
151A 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.
152There is no notion or requirement for \emph{rewriting} a legacy C program in \CFA;
153instead, a programmer evolves a legacy program into \CFA by incrementally incorporating \CFA features.
154As well, new programs can be written in \CFA using a combination of C and \CFA features.
155
156\Index*[C++]{\CC{}} had a similar goal 30 years ago, allowing object-oriented programming to be incrementally added to C.
157However, \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, all of which requires significant effort and training to incrementally add \CC to a C-based project.
158In contrast, \CFA has 30 years of hindsight and a clean starting point.
159
160Like \Index*[C++]{\CC{}}, there may be both an old and new ways to achieve the same effect.
161For example, the following programs compare the \CFA, C, and \CC I/O mechanisms, where the programs output the same result.
162\begin{quote2}
163\begin{tabular}{@{}l@{\hspace{1.5em}}l@{\hspace{1.5em}}l@{}}
164\multicolumn{1}{c@{\hspace{1.5em}}}{\textbf{C}} & \multicolumn{1}{c}{\textbf{\CFA}}     & \multicolumn{1}{c}{\textbf{\CC}}      \\
165\begin{cfa}
166#include <stdio.h>§\indexc{stdio.h}§
167
168int main( void ) {
169        int x = 0, y = 1, z = 2;
170        ®printf( "%d %d %d\n", x, y, z );®
171}
172\end{cfa}
173&
174\begin{cfa}
175#include <fstream>§\indexc{fstream}§
176
177int main( void ) {
178        int x = 0, y = 1, z = 2;
179        ®sout | x | y | z | endl;®§\indexc{sout}§
180}
181\end{cfa}
182&
183\begin{cfa}
184#include <iostream>§\indexc{iostream}§
185using namespace std;
186int main() {
187        int x = 0, y = 1, z = 2;
188        ®cout<<x<<" "<<y<<" "<<z<<endl;®
189}
190\end{cfa}
191\end{tabular}
192\end{quote2}
193While the \CFA I/O looks similar to the \Index*[C++]{\CC{}} output style, there are important differences, such as automatic spacing between variables as in \Index*{Python} (see~\VRef{s:IOLibrary}).
194
195\subsection{Background}
196
197This document is a programmer reference-manual for the \CFA programming language.
198The manual covers the core features of the language and runtime-system, with simple examples illustrating syntax and semantics of each feature.
199The manual does not teach programming, i.e., how to combine the new constructs to build complex programs.
200A reader should already 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.
201Implementers should refer to the \CFA Programming Language Specification for details about the language syntax and semantics.
202Changes to the syntax and additional features are expected to be included in later revisions.
203
204
205\section{Why fix C?}
206
207The C programming language is a foundational technology for modern computing with millions of lines of code implementing everything from commercial operating-systems (especially UNIX systems) to hobby projects.
208This installation base and the programmers producing it represent a massive software-engineering investment spanning decades and likely to continue for decades more.
209Even with all its problems, C continues to be popular because it allows writing software at virtually any level in a computer system without restriction.
210For system programming, where direct access to hardware, storage management, and real-time issues are a requirement, C is usually the only language of choice.
211The TIOBE index~\cite{TIOBE} for March 2016 showed the following programming-language popularity: \Index*{Java} 20.5\%, C 14.5\%, \Index*[C++]{\CC{}} 6.7\%, \Csharp 4.3\%, \Index*{Python} 4.3\%, where the next 50 languages are less than 3\% each with a long tail.
212As well, for 30 years, C has been the number 1 and 2 most popular programming language:
213\begin{center}
214\setlength{\tabcolsep}{1.5ex}
215\begin{tabular}{@{}r|c|c|c|c|c|c|c@{}}
216Ranking & 2016  & 2011  & 2006  & 2001  & 1996  & 1991  & 1986          \\
217\hline
218Java    & 1             & 1             & 1             & 3             & 29    & -             & -                     \\
219\hline
220\R{C}   & \R{2} & \R{2} & \R{2} & \R{1} & \R{1} & \R{1} & \R{1}         \\
221\hline
222\CC             & 3             & 3             & 3             & 2             & 2             & 2             & 7                     \\
223\end{tabular}
224\end{center}
225Hence, 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.
226Love it or hate it, C has been an important and influential part of computer science for 40 years and its appeal is not diminishing.
227Unfortunately, C has many problems and omissions that make it an unacceptable programming language for modern needs.
228
229As stated, the goal of the \CFA project is to engineer modern language-features into C in an evolutionary rather than revolutionary way.
230\CC~\cite{C++14,C++} is an example of a similar project;
231however, it largely extended the C language, and did not address most of C's existing problems.\footnote{%
232Two 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.}
233\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.
234\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.
235These 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.
236As a result, there is a significant learning curve to move to these languages, and C legacy-code must be rewritten.
237These costs can be prohibitive for many companies with a large software-base in C/\CC, and a significant number of programmers require retraining to the new programming language.
238
239The 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 containing modern language-features.
240Without significant extension to the C programming language, it is becoming unable to cope with the needs of modern programming problems and programmers;
241as a result, it will fade into disuse.
242Considering the large body of existing C code and programmers, there is significant impetus to ensure C is transformed into a modern programming language.
243While \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.
244While 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.
245
246
247\section{History}
248
249The \CFA project started with \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.
250(See~\cite{Werther96} for similar work in \Index*[C++]{\CC{}}.)
251The first \CFA implementation of these extensions was by Esteves~\cite{Esteves04}.
252
253The signature feature of \CFA is \Index{overload}able \Index{parametric-polymorphic} functions~\cite{forceone:impl,Cormack90,Duggan96} with functions generalized using a ©forall© clause (giving the language its name):
254\begin{lstlisting}
255®forall( otype T )® T identity( T val ) { return val; }
256int forty_two = identity( 42 );                 §\C{// T is bound to int, forty\_two == 42}§
257\end{lstlisting}
258% extending the C type system with parametric polymorphism and overloading, as opposed to the \Index*[C++]{\CC{}} approach of object-oriented extensions.
259\CFA{}\hspace{1pt}'s polymorphism was originally formalized by Ditchfiled~\cite{Ditchfield92}, and first implemented by Bilson~\cite{Bilson03}.
260However, at that time, there was little interesting in extending C, so work did not continue.
261As the saying goes, ``\Index*{What goes around, comes around.}'', and there is now renewed interest in the C programming language because of legacy code-bases, so the \CFA project has been restarted.
262
263
264\section{Interoperability}
265\label{s:Interoperability}
266
267\CFA is designed to integrate directly with existing C programs and libraries.
268The 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.
269This feature allows \CFA programmers to take advantage of the existing panoply of C libraries to access thousands of external software features.
270Language developers often state that adequate \Index{library support} takes more work than designing and implementing the language itself.
271Fortunately, \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 very low cost.
272Hence, \CFA begins by leveraging the large repository of C libraries at little cost.
273
274\begin{comment}
275A simple example is leveraging the existing type-unsafe (©void *©) C ©bsearch© to binary search a sorted floating-point array:
276\begin{lstlisting}
277void * bsearch( const void * key, const void * base, size_t dim, size_t size,
278                                int (* compar)( const void *, const void * ));
279
280int comp( const void * t1, const void * t2 ) { return *(double *)t1 < *(double *)t2 ? -1 :
281                                *(double *)t2 < *(double *)t1 ? 1 : 0; }
282
283double key = 5.0, vals[10] = { /* 10 sorted floating-point values */ };
284double * val = (double *)bsearch( &key, vals, 10, sizeof(vals[0]), comp );      $\C{// search sorted array}$
285\end{lstlisting}
286which can be augmented simply with a polymorphic, type-safe, \CFA-overloaded wrappers:
287\begin{lstlisting}
288forall( otype T | { int ?<?( T, T ); } ) T * bsearch( T key, const T * arr, size_t size ) {
289        int comp( const void * t1, const void * t2 ) { /* as above with double changed to T */ }
290        return (T *)bsearch( &key, arr, size, sizeof(T), comp ); }
291
292forall( otype T | { int ?<?( T, T ); } ) unsigned int bsearch( T key, const T * arr, size_t size ) {
293        T * result = bsearch( key, arr, size ); $\C{// call first version}$
294        return result ? result - arr : size; }  $\C{// pointer subtraction includes sizeof(T)}$
295
296double * val = bsearch( 5.0, vals, 10 );        $\C{// selection based on return type}$
297int posn = bsearch( 5.0, vals, 10 );
298\end{lstlisting}
299The nested function ©comp© provides the hidden interface from typed \CFA to untyped (©void *©) C, plus the cast of the result.
300Providing a hidden ©comp© function in \CC is awkward as lambdas do not use C calling-conventions and template declarations cannot appear at block scope.
301As well, an alternate kind of return is made available: position versus pointer to found element.
302\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©.
303
304\CFA has replacement libraries condensing hundreds of existing C functions into tens of \CFA overloaded functions, all without rewriting the actual computations.
305For example, it is possible to write a type-safe \CFA wrapper ©malloc© based on the C ©malloc©:
306\begin{lstlisting}
307forall( dtype T | sized(T) ) T * malloc( void ) { return (T *)malloc( sizeof(T) ); }
308int * ip = malloc();                                    §\C{// select type and size from left-hand side}§
309double * dp = malloc();
310struct S {...} * sp = malloc();
311\end{lstlisting}
312where the return type supplies the type/size of the allocation, which is impossible in most type systems.
313\end{comment}
314
315However, it is necessary to differentiate between C and \CFA code because of name \Index{overload}ing, as for \CC.
316For 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©.
317Whereas, \CFA wraps each of these routines into ones with the overloaded name ©abs©:
318\begin{cfa}
319char abs( char );
320®extern "C" {®
321int abs( int );                                                 §\C{// use default C routine for int}§
322®}® // extern "C"
323long int abs( long int );
324long long int abs( long long int );
325float abs( float );
326double abs( double );
327long double abs( long double );
328float _Complex abs( float _Complex );
329double _Complex abs( double _Complex );
330long double _Complex abs( long double _Complex );
331\end{cfa}
332The problem is the name clash between the library routine ©abs© and the \CFA names ©abs©.
333Hence, names appearing in an ©extern "C"© block have \newterm*{C linkage}.
334Then overloading polymorphism uses a mechanism called \newterm{name mangling}\index{mangling!name} to create unique names that are different from C names, which are not mangled.
335Hence, 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.
336There is no way around this problem, other than C's approach of creating unique names for each pairing of operation and type.
337This example strongly illustrates a core idea in \CFA: \emph{the \Index{power of a name}}.
338The name ``©abs©'' evokes the notion of absolute value, and many mathematical types provide the notion of absolute value.
339Hence, knowing the name ©abs© is sufficient to apply it to any type where it is applicable.
340The time savings and safety of using one name uniformly versus $N$ unique names cannot be underestimated.
341
342
343\section[Compiling a CFA Program]{Compiling a \CFA Program}
344
345The command ©cfa© is used to compile \CFA program(s), and is based on the GNU \Indexc{gcc} command, \eg:
346\begin{cfa}
347cfa§\indexc{cfa}\index{compilation!cfa@©cfa©}§ [ gcc-options ] C/§\CFA{}§-files [ assembler/loader-files ]
348\end{cfa}
349\CFA programs having the following ©gcc© flags turned on:
350\begin{description}
351\item
352\Indexc{-std=gnu99}\index{compilation option!-std=gnu99@{©-std=gnu99©}}
353The 1999 C standard plus GNU extensions.
354\item
355\Indexc[deletekeywords=inline]{-fgnu89-inline}\index{compilation option!-fgnu89-inline@{\lstinline[deletekeywords=inline]$-fgnu89-inline$}}
356Use the traditional GNU semantics for inline routines in C99 mode, which allows inline routines in header files.
357\end{description}
358The following new \CFA options are available:
359\begin{description}
360\item
361\Indexc{-CFA}\index{compilation option!-CFA@©-CFA©}
362Only the C preprocessor 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.
363The generated code started with the standard \CFA prelude.
364
365\item
366\Indexc{-debug}\index{compilation option!-debug@©-debug©}
367The program is linked with the debugging version of the runtime system.
368The debug version performs runtime checks to help during the debugging phase of a \CFA program, but can substantially slow program execution.
369The runtime checks should only be removed after the program is completely debugged.
370\textbf{This option is the default.}
371
372\item
373\Indexc{-nodebug}\index{compilation option!-nodebug@©-nodebug©}
374The program is linked with the non-debugging version of the runtime system, so the execution of the program is faster.
375\Emph{However, no runtime checks or ©assert©s are performed so errors usually result in abnormal program termination.}
376
377\item
378\Indexc{-help}\index{compilation option!-help@©-help©}
379Information about the set of \CFA compilation flags is printed.
380
381\item
382\Indexc{-nohelp}\index{compilation option!-nohelp@©-nohelp©}
383Information about the set of \CFA compilation flags is not printed.
384\textbf{This option is the default.}
385
386\item
387\Indexc{-quiet}\index{compilation option!-quiet@©-quiet©}
388The \CFA compilation message is not printed at the beginning of a compilation.
389
390\item
391\Indexc{-noquiet}\index{compilation option!-noquiet@©-noquiet©}
392The \CFA compilation message is printed at the beginning of a compilation.
393\textbf{This option is the default.}
394
395\item
396\Indexc{-no-include-stdhdr}\index{compilation option!-no-include-stdhdr@©-no-include-stdhdr©}
397Do not supply ©extern "C"© wrappers for \Celeven standard include files (see~\VRef{s:StandardHeaders}).
398\textbf{This option is \emph{not} the default.}
399\end{description}
400
401The following preprocessor variables are available:
402\begin{description}
403\item
404\Indexc{__CFA_MAJOR__}\index{preprocessor variables!__CFA__@{©__CFA__©}}
405is available during preprocessing and its value is the major \Index{version number} of \CFA.\footnote{
406The C preprocessor allows only integer values in a preprocessor variable so a value like ``\Version'' is not allowed.
407Hence, the need to have three variables for the major, minor and patch version number.}
408
409\item
410\Indexc{__CFA_MINOR__}\index{preprocessor variables!__CFA_MINOR__@{©__CFA_MINOR__©}}
411is available during preprocessing and its value is the minor \Index{version number} of \CFA.
412
413\item
414\Indexc{__CFA_PATCH__}\index{preprocessor variables!__CFA_PATCH____CFA_PATCH__©}
415is available during preprocessing and its value is the patch \Index{level number} of \CFA.
416
417\item
418\Indexc{__CFA__}\index{preprocessor variables!__CFA____CFA__©},
419\Indexc{__CFORALL__}\index{preprocessor variables!__CFORALL____CFORALL__©} and
420\Indexc{__cforall}\index{preprocessor variables!__cforall@©__cforall©}
421are always available during preprocessing and have no value.
422\end{description}
423These preprocessor variables allow conditional compilation of programs that must work differently in these situations.
424For example, to toggle between C and \CFA extensions, use the following:
425\begin{cfa}
426#ifndef __CFORALL__
427#include <stdio.h>§\indexc{stdio.h}§    §\C{// C header file}§
428#else
429#include <fstream>§\indexc{fstream}§    §\C{// \CFA header file}§
430#endif
431\end{cfa}
432which conditionally includes the correct header file, if the program is compiled using \Indexc{gcc} or \Indexc{cfa}.
433
434
435\section{Constant Underscores}
436
437Numeric constants are extended to allow \Index{underscore}s\index{constant!underscore}, \eg:
438\begin{cfa}
439_®147®_®483®_®648;                                    §\C{// decimal constant}§
44056®_®ul;                                                                §\C{// decimal unsigned long constant}§
441_®377;                                                                §\C{// octal constant}§
4420x®_®ff®_®ff;                                                   §\C{// hexadecimal constant}§
4430x®_®ef3d®_®aa5c;                                               §\C{// hexadecimal constant}§
4443.141®_®592®_®654;                                              §\C{// floating point constant}§
44510®_®e®_®+1®_®00;                                               §\C{// floating point constant}§
4460x®_®ff®_®ff®_®p®_®3;                                   §\C{// hexadecimal floating point}§
4470x®_®1.ffff®_®ffff®_®p®_®128®_®l;               §\C{// hexadecimal floating point long constant}§
448_®§"\texttt{\textbackslash{x}}§®_®§\texttt{ff}§®_®§\texttt{ee}"§;     §\C{// wide character constant}§
449\end{cfa}
450The rules for placement of underscores are:
451\begin{enumerate}[topsep=5pt,itemsep=5pt,parsep=0pt]
452\item
453A sequence of underscores is disallowed, \eg ©12__34© is invalid.
454\item
455Underscores may only appear within a sequence of digits (regardless of the digit radix).
456In 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).
457\item
458A numeric prefix may end with an underscore;
459a numeric infix may begin and/or end with an underscore;
460a numeric suffix may begin with an underscore.
461For example, the octal ©0© or hexadecimal ©0x© prefix may end with an underscore ©0_377© or ©0x_ff©;
462the exponent infix ©E© may start or end with an underscore ©1.0_E10©, ©1.0E_10© or ©1.0_E_10©;
463the type suffixes ©U©, ©L©, etc. may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
464\end{enumerate}
465It 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).
466This extension is backwards compatible, matches with the use of underscore in variable names, and appears in \Index*{Ada} and \Index*{Java} 8.
467
468
469\section{Backquote Identifiers}
470\label{s:BackquoteIdentifiers}
471
472\CFA introduces in new keywords (see \VRef{s:CFAKeywords}) that can clash with existing C variable-names in legacy code.
473Keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism:
474\begin{cfa}
475int ®`®otype®`® = 3;                    §\C{// make keyword an identifier}§
476double ®`®forall®`® = 3.5;
477\end{cfa}
478Existing 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.
479\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in C header files (see~\VRef{s:StandardHeaders}) can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©:
480
481\begin{figure}
482\begin{cfa}
483// include file uses the CFA keyword "otype".
484#if ! defined( otype )                  §\C{// nesting ?}§
485#define otype ®`®otype®`®               §\C{// make keyword an identifier}§
486#define __CFA_BFD_H__
487#endif
488
489®#include_next <bfd.h>                  §\C{// must have internal check for multiple expansion}§
490®
491#if defined( otype ) && defined( __CFA_BFD_H__ )        §\C{// reset only if set}§
492#undef otype
493#undef __CFA_BFD_H__
494#endif
495\end{cfa}
496\caption{Header-File Interposition}
497\label{f:HeaderFileInterposition}
498\end{figure}
499
500
501\section{Exponentiation Operator}
502
503C, \CC, and Java (and many other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow}, to perform the exponentiation operation.
504\CFA extends the basic operators with the exponentiation operator ©?\?©\index{?\\?@\lstinline$?\?$} and ©?\=\index{?\\=?@\lstinline$?\=?$}, as in, ©x \ y© and ©x \= y©, which means $x^y$ and $x \leftarrow x^y$.
505The 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)©.
506
507As for \Index{division}, there are exponentiation operators for integral and floating-point types, including the builtin \Index{complex} types.
508Unsigned integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication (or shifting if the base is 2).
509Signed integral exponentiation\index{exponentiation!signed integral} is performed with repeated multiplication (or shifting if the base is 2), but yields a floating-point result because $b^{-e}=1/b^e$.
510Hence, it is important to designate exponent integral-constants as unsigned or signed: ©3 \ 3u© return an integral result, while ©3 \ 3© returns a floating-point result.
511Floating-point exponentiation\index{exponentiation!floating point} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the base cannot be negative.
512\begin{cfa}
513sout | 2 ® 8u | 4 ® 3u | -4 ® 3u | 4 ® -3 | -4 ® -3 | 4.0 ® 2.1 | (1.0f+2.0fi) ® (3.0f+2.0fi) | endl;
514256 64 -64 0.015625 -0.015625 18.3791736799526 0.264715-1.1922i
515\end{cfa}
516Parenthesis are necessary for the complex constants or the expresion is parsed as ©1.0f+(2.0fi \ 3.0f)+2.0fi©.
517The exponentiation operator is available for all the basic types, but for user-defined types, only the integral version is available, if the user type defines multiplication, ©*©, and one, ©1©.
518
519
520\section{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break}}{Labelled continue / break}}
521
522While C provides ©continue© and ©break© statements for altering control flow, both are restricted to one level of nesting for a particular control structure.
523Unfortunately, this restriction forces programmers to use \Indexc{goto} to achieve the equivalent control-flow for more than one level of nesting.
524To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@\lstinline $continue$!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@\lstinline $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}.
525For both ©continue© and ©break©, the target label must be directly associated with a ©for©, ©while© or ©do© statement;
526for ©break©, the target label can also be associated with a ©switch©, ©if© or compound (©{}©) statement.
527\VRef[Figure]{f:MultiLevelResumeTermination} shows the labelled ©continue© and ©break©, specifying which control structure is the target for exit, and the corresponding C program using only ©goto©.
528The innermost loop has 7 exit points, which cause resumption or termination of one or more of the 7 \Index{nested control-structure}s.
529Java supports both labelled ©continue© and ©break© statements.
530
531\begin{figure}
532\begin{tabular}{@{\hspace{\parindentlnth}}l@{\hspace{1.5em}}l@{}}
533\multicolumn{1}{c@{\hspace{1.5em}}}{\textbf{\CFA}}      & \multicolumn{1}{c}{\textbf{C}}        \\
534\begin{cfa}
535®LC:® {
536        ... §declarations§ ...
537        ®LS:® switch ( ... ) {
538          case 3:
539                ®LIF:® if ( ... ) {
540                        ®LF:® for ( ... ) {
541                                ®LW:® while ( ... ) {
542                                        ... break ®LC®; ...                     // terminate compound
543                                        ... break ®LS®; ...                     // terminate switch
544                                        ... break ®LIF®; ...                    // terminate if
545                                        ... continue ®LF;® ...   // resume loop
546                                        ... break ®LF®; ...                     // terminate loop
547                                        ... continue ®LW®; ...   // resume loop
548                                        ... break ®LW®; ...               // terminate loop
549                                } // while
550                        } // for
551                } else {
552                        ... break ®LIF®; ...                                     // terminate if
553                } // if
554        } // switch
555} // compound
556\end{cfa}
557&
558\begin{cfa}
559{
560        ... §declarations§ ...
561        switch ( ... ) {
562          case 3:
563                if ( ... ) {
564                        for ( ... ) {
565                                while ( ... ) {
566                                        ... goto ®LC®; ...
567                                        ... goto ®LS®; ...
568                                        ... goto ®LIF®; ...
569                                        ... goto ®LFC®; ...
570                                        ... goto ®LFB®; ...
571                                        ... goto ®LWC®; ...
572                                        ... goto ®LWB®; ...
573                                  ®LWC®: ; } ®LWB:® ;
574                          ®LFC:® ; } ®LFB:® ;
575                } else {
576                        ... goto ®LIF®; ...
577                } ®L3:® ;
578        } ®LS:® ;
579} ®LC:® ;
580\end{cfa}
581\end{tabular}
582\caption{Multi-level Resume/Termination}
583\label{f:MultiLevelResumeTermination}
584\end{figure}
585
586\begin{comment}
587int main() {
588  LC: {
589          LS: switch ( 1 ) {
590                  case 3:
591                  LIF: if ( 1 ) {
592                          LF: for ( ;; ) {
593                                  LW: while ( 1 ) {
594                                                break LC;                       // terminate compound
595                                                break LS;                       // terminate switch
596                                                break LIF;                      // terminate if
597                                                continue LF;     // resume loop
598                                                break LF;                       // terminate loop
599                                                continue LW;     // resume loop
600                                                break LW;                 // terminate loop
601                                        } // while
602                                } // for
603                        } else {
604                                break LIF;                                       // terminate if
605                        } // if
606                } // switch
607        } // compound
608        {
609                switch ( 1 ) {
610                  case 3:
611                        if ( 1 ) {
612                                for ( ;; ) {
613                                        while ( 1 ) {
614                                                goto LCx;
615                                                goto LSx;
616                                                goto LIF;
617                                                goto LFC;
618                                                goto LFB;
619                                                goto LWC;
620                                                goto LWB;
621                                          LWC: ; } LWB: ;
622                                  LFC: ; } LFB: ;
623                        } else {
624                                goto LIF;
625                        } L3: ;
626                } LSx: ;
627        } LCx: ;
628}
629
630// Local Variables: //
631// tab-width: 4 //
632// End: //
633\end{comment}
634
635
636Both labelled ©continue© and ©break© are a ©goto©\index{goto@\lstinline $goto$!restricted} restricted in the following ways:
637\begin{itemize}
638\item
639They cannot create a loop, which means only the looping constructs cause looping.
640This restriction means all situations resulting in repeated execution are clearly delineated.
641\item
642They cannot branch into a control structure.
643This restriction prevents missing initialization at the start of a control structure resulting in undefined behaviour.
644\end{itemize}
645The 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.
646Furthermore, the location of the label at the \emph{beginning} of the target control structure informs the reader that complex control-flow is occurring in the body of the control structure.
647With ©goto©, the label is at the end of the control structure, which fails to convey this important clue early enough to the reader.
648Finally, using an explicit target for the transfer instead of an implicit target allows new constructs to be added or removed without affecting existing constructs.
649The implicit targets of the current ©continue© and ©break©, \ie the closest enclosing loop or ©switch©, change as certain constructs are added or removed.
650
651
652\section{\texorpdfstring{\LstKeywordStyle{switch} Statement}{switch Statement}}
653
654C allows a number of questionable forms for the ©switch© statement:
655\begin{enumerate}
656\item
657By default, the end of a ©case© clause\footnote{
658In this section, the term \emph{case clause} refers to either a ©case© or ©default© clause.}
659\emph{falls through} to the next ©case© clause in the ©switch© statement;
660to exit a ©switch© statement from a ©case© clause requires explicitly terminating the clause with a transfer statement, most commonly ©break©:
661\begin{cfa}
662switch ( i ) {
663  case 1:
664        ...
665        // fall-through
666  case 2:
667        ...
668        break;  // exit switch statement
669}
670\end{cfa}
671The ability to fall-through to the next clause \emph{is} a useful form of control flow, specifically when a sequence of case actions compound:
672\begin{quote2}
673\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
674\begin{cfa}
675switch ( argc ) {
676  case 3:
677        // open output file
678        // fall-through
679  case 2:
680        // open input file
681        break;  // exit switch statement
682  default:
683        // usage message
684}
685\end{cfa}
686&
687\begin{cfa}
688
689if ( argc == 3 ) {
690        // open output file
691        ®// open input file
692®} else if ( argc == 2 ) {
693        ®// open input file (duplicate)
694
695®} else {
696        // usage message
697}
698\end{cfa}
699\end{tabular}
700\end{quote2}
701In this example, case 2 is always done if case 3 is done.
702This 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.
703C also uses fall-through to handle multiple case-values resulting in the same action:
704\begin{cfa}
705switch ( i ) {
706  ®case 1: case 3: case 5:®     // odd values
707        // odd action
708        break;
709  ®case 2: case 4: case 6:®     // even values
710        // even action
711        break;
712}
713\end{cfa}
714However, this situation is handled in other languages without fall-through by allowing a list of case values.
715While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive to many programmers and is different from virtually all other programming languages with a ©switch© statement.
716Hence, 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.
717
718\item
719It is possible to place ©case© clauses on statements nested \emph{within} the body of the ©switch© statement:
720\begin{cfa}
721switch ( i ) {
722  case 0:
723        if ( j < k ) {
724                ...
725          ®case 1:®             // transfer into "if" statement
726                ...
727        } // if
728  case 2:
729        while ( j < 5 ) {
730                ...
731          ®case 3:®             // transfer into "while" statement
732                ...
733        } // while
734} // switch
735\end{cfa}
736The problem with this usage is branching into control structures, which is known to cause both comprehension and technical difficulties.
737The comprehension problem occurs from the inability to determine how control reaches a particular point due to the number of branches leading to it.
738The technical problem results from the inability to ensure allocation and initialization of variables when blocks are not entered at the beginning.
739Often transferring into a block can bypass variable declaration and/or its initialization, which results in subsequent errors.
740There are virtually no positive arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
741Nevertheless, C does have an idiom where this capability is used, known as ``\Index*{Duff's device}''~\cite{Duff83}:
742\begin{cfa}
743register int n = (count + 7) / 8;
744switch ( count % 8 ) {
745case 0: do{ *to = *from++;
746case 7:         *to = *from++;
747case 6:         *to = *from++;
748case 5:         *to = *from++;
749case 4:         *to = *from++;
750case 3:         *to = *from++;
751case 2:         *to = *from++;
752case 1:         *to = *from++;
753                } while ( --n > 0 );
754}
755\end{cfa}
756which unrolls a loop N times (N = 8 above) and uses the ©switch© statement to deal with any iterations not a multiple of N.
757While efficient, this sort of special purpose usage is questionable:
758\begin{quote}
759Disgusting, no? But it compiles and runs just fine. I feel a combination of pride and revulsion at this
760discovery.~\cite{Duff83}
761\end{quote}
762\item
763It is possible to place the ©default© clause anywhere in the list of labelled clauses for a ©switch© statement, rather than only at the end.
764Virtually all programming languages with a ©switch© statement require the ©default© clause to appear last in the case-clause list.
765The logic for this semantics is that after checking all the ©case© clauses without success, the ©default© clause is selected;
766hence, physically placing the ©default© clause at the end of the ©case© clause list matches with this semantics.
767This physical placement can be compared to the physical placement of an ©else© clause at the end of a series of connected ©if©/©else© statements.
768
769\item
770It is possible to place unreachable code at the start of a ©switch© statement, as in:
771\begin{cfa}
772switch ( x ) {
773        ®int y = 1;®                            §\C{// unreachable initialization}§
774        ®x = 7;®                                        §\C{// unreachable code without label/branch}§
775  case 3: ...
776        ...
777        ®int z = 0;®                            §\C{// unreachable initialization, cannot appear after case}§
778        z = 2;
779  case 3:
780        ®x = z;®                                        §\C{// without fall through, z is uninitialized}§
781}
782\end{cfa}
783While 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.
784Furthermore, 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©, both of which are problematic.
785As 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.
786The key observation is that the ©switch© statement branches into control structure, \ie there are multiple entry points into its statement body.
787\end{enumerate}
788
789Before discussing potential language changes to deal with these problems, it is worth observing that in a typical C program:
790\begin{itemize}
791\item
792the number of ©switch© statements is small,
793\item
794most ©switch© statements are well formed (\ie no \Index*{Duff's device}),
795\item
796the ©default© clause is usually written as the last case-clause,
797\item
798and 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.
799\end{itemize}
800These observations put into perspective the \CFA changes to the ©switch©.
801\begin{enumerate}
802\item
803Eliminating default fall-through has the greatest potential for affecting existing code.
804However, 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:
805\begin{cfa}
806case 1:  case 2:  case 3: ...
807\end{cfa}
808still works.
809Nevertheless, reversing the default action would have a non-trivial effect on case actions that compound, such as the above example of processing shell arguments.
810Therefore, 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:
811\begin{cfa}
812®choose® ( i ) {
813  case 1:  case 2:  case 3:
814        ...
815        ®// implicit end of switch (break)
816  ®case 5:
817        ...
818        ®fallthru®;                                     §\C{// explicit fall through}§
819  case 7:
820        ...
821        ®break®                                         §\C{// redundant explicit end of switch}§
822  default:
823        j = 3;
824}
825\end{cfa}
826Like the ©switch© statement, the ©choose© statement retains the fall-through semantics for a list of ©case© clauses;
827An implicit ©break© is applied only at the end of the \emph{statements} following a ©case© clause.
828An 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.
829As well, allowing an explicit ©break© from the ©choose© is a carry over from the ©switch© statement, and expected by C programmers.
830\item
831\Index*{Duff's device} is eliminated from both ©switch© and ©choose© statements, and only invalidates a small amount of very questionable code.
832Hence, 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.
833\item
834The 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.
835Therefore, no change is made for this issue.
836\item
837Dealing 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{
838Essentially, 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.
839Further declarations at the same nesting level as the statement body are disallowed to ensure every transfer into the body is sound.
840\begin{cfa}
841switch ( x ) {
842        ®int i = 0;®                            §\C{// allowed only at start}§
843  case 0:
844        ...
845        ®int j = 0;®                            §\C{// disallowed}§
846  case 1:
847        {
848                ®int k = 0;®                    §\C{// allowed at different nesting levels}§
849                ...
850        }
851  ...
852}
853\end{cfa}
854\end{enumerate}
855
856
857\section{\texorpdfstring{\LstKeywordStyle{case} Clause}{case Clause}}
858
859C restricts the ©case© clause of a ©switch© statement to a single value.
860For multiple ©case© clauses associated with the same statement, it is necessary to have multiple ©case© clauses rather than multiple values.
861Requiring a ©case© clause for each value does not seem to be in the spirit of brevity normally associated with C.
862Therefore, the ©case© clause is extended with a list of values, as in:
863\begin{quote2}
864\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
865\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}} \\
866\begin{cfa}
867switch ( i ) {
868  case ®1, 3, 5®:
869        ...
870  case ®2, 4, 6®:
871        ...
872}
873\end{cfa}
874&
875\begin{cfa}
876switch ( i ) {
877  case 1: case 3 : case 5:
878        ...
879  case 2: case 4 : case 6:
880        ...
881}
882\end{cfa}
883&
884\begin{cfa}
885
886// odd values
887
888// even values
889
890
891\end{cfa}
892\end{tabular}
893\end{quote2}
894In addition, two forms of subranges are allowed to specify case values: a new \CFA form and an existing GNU C form.\footnote{
895The GNU C form \emph{requires} spaces around the ellipse.}
896\begin{quote2}
897\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
898\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{GNU C}}     \\
899\begin{cfa}
900switch ( i ) {
901  case ®1~5:®
902        ...
903  case ®10~15:®
904        ...
905}
906\end{cfa}
907&
908\begin{cfa}
909switch ( i )
910  case ®1 ... 5®:
911        ...
912  case ®10 ... 15®:
913        ...
914}
915\end{cfa}
916&
917\begin{cfa}
918
919// 1, 2, 3, 4, 5
920
921// 10, 11, 12, 13, 14, 15
922
923
924\end{cfa}
925\end{tabular}
926\end{quote2}
927Lists of subranges are also allowed.
928\begin{cfa}
929case ®1~5, 12~21, 35~42®:
930\end{cfa}
931
932
933\section{\texorpdfstring{\LstKeywordStyle{with} Clause / Statement}{with Clause / Statement}}
934\label{s:WithClauseStatement}
935
936In \Index{object-oriented} programming, there is an implicit first parameter, often names \textbf{©self©} or \textbf{©this©}, which is elided.
937\begin{C++}
938class C {
939        int i, j;
940        int mem() {              ®// implicit "this" parameter
941®               i = 1;          ®// this->i
942®               j = 3;          ®// this->j
943®       }
944}
945\end{C++}
946Since CFA is non-object-oriented, the equivalent object-oriented program looks like:
947\begin{cfa}
948struct S { int i, j; };
949int mem( S &this ) {    // explicit "this" parameter
950        ®this.®i = 1;                     // "this" is not elided
951        ®this.®j = 2;
952}
953\end{cfa}
954but it is cumbersome having to write "©this.©" many times in a member.
955
956\CFA provides a ©with© clause/statement to elided the "©this.©" by opening a scope containing field identifiers and changing the qualified fields into variables, giving an opportunity for optimizing qualified references.\footnote{
957The ©with© statement comes from Pascal~\cite[\S~4.F]{Pascal}.}
958\begin{cfa}
959int mem( S &this ) ®with this® {
960        i = 1;                  ®// this.i
961®       j = 2;                  ®// this.j
962®}
963\end{cfa}
964which extends to multiple routine parameters:
965\begin{cfa}
966struct T { double m, n; };
967int mem2( S &this1, T &this2 ) ®with this1, this2® {
968        i = 1; j = 2;
969        m = 1.0; n = 2.0;
970}
971\end{cfa}
972
973The statement form is used within a block:
974\begin{cfa}
975int foo() {
976        struct S1 { ... } s1;
977        struct S2 { ... } s2;
978        ®with s1® {
979                // access fields of s1 without qualification
980                ®with s2® {  // nesting
981                        // access fields of s1 and s2 without qualification
982                }
983        }
984        ®with s1, s2® {
985                // access unambiguous fields of s1 and s2 without qualification
986        }
987}
988\end{cfa}
989
990When opening multiple structures, fields with the same name and type are ambiguous and must be fully qualified.
991For fields with the same name but different type, context/cast can be used to disambiguate.
992\begin{cfa}
993struct S { int i; int j; double m; } a, c;
994struct T { int i; int k; int m } b, c;
995®with a, b® {
996        j + k;                                          §\C{// unambiguous, unique names define unique type}§
997        i;                                                      §\C{// ambiguous, same name and type}§
998        a.i + b.i;                                      §\C{// unambiguous, qualification defines unique type}§
999        m;                                                      §\C{// ambiguous, no context to define unique type}§
1000        m = 5.0;                                        §\C{// unambiguous, context defines unique type}§
1001        m = 1;                                          §\C{// unambiguous, context defines unique type}§
1002}
1003®with c® { ... }                                §\C{// ambiguous, no context}§
1004®with (S)c® { ... }                             §\C{// unambiguous, cast defines unique type}§
1005\end{cfa}
1006
1007
1008\section{Exception Handling}
1009\label{s:ExceptionHandling}
1010
1011Exception handling provides two mechanism: change of control flow from a raise to a handler, and communication from the raise to the handler.
1012Transfer of control can be local, within a routine, or non-local, among routines.
1013Non-local transfer can cause stack unwinding, i.e., non-local routine termination, depending on the kind of raise.
1014\begin{cfa}
1015exception_t E {};                               §\C{// exception type}§
1016void f(...) {
1017        ... throw E{}; ...                      §\C{// termination}§
1018        ... throwResume E{}; ...        §\C{// resumption}§
1019}
1020try {
1021        f(...);
1022} catch( E e : §boolean-predicate§ ) {                  §\C{// termination handler}§
1023        // recover and continue
1024} catchResume( E e : §boolean-predicate§ ) {    §\C{// resumption handler}§
1025        // repair and return
1026} finally {
1027        // always executed
1028}
1029\end{cfa}
1030The kind of raise and handler match: ©throw© with ©catch© and @throwResume@ with @catchResume@.
1031Then the exception type must match along with any additonal predicate must be true.
1032The ©catch© and ©catchResume© handlers may appear in any oder.
1033However, the ©finally© clause must
1034
1035
1036\subsection{Exception Hierarchy}
1037
1038An 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.
1039The exception-type hierarchy that is created is used to organize exception types, similar to a class hierarchy in object-oriented languages, \eg:
1040\begin{center}
1041\input{EHMHierarchy}
1042\end{center}
1043A programmer can then choose to handle an exception at different degrees of specificity along the hierarchy;
1044derived exception-types support a more flexible programming style.
1045For example, higher-level code should catch general exceptions to reduce coupling to the specific implementation at the lower levels;
1046unnecessary coupling may force changes in higher-level code when low-level code changes.
1047A consequence of derived exception-types is that multiple exceptions may match, \eg:
1048\begin{cfa}
1049catch( Arithmetic )
1050\end{cfa}
1051matches all three derived exception-types: ©DivideByZero©, ©Overflow©, and ©Underflow©.
1052Because 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:
1053\begin{cfa}
1054try {
1055        ...
1056} catch( Overflow ) {   // must appear first
1057        // handle overflow
1058} catch( Arithmetic )
1059        // handle other arithmetic issues
1060}
1061\end{cfa}
1062\newterm{Multiple derivation} among exception is not supported.
1063
1064
1065\section{Declarations}
1066\label{s:Declarations}
1067
1068C declaration syntax is notoriously confusing and error prone.
1069For example, many C programmers are confused by a declaration as simple as:
1070\begin{quote2}
1071\begin{tabular}{@{}ll@{}}
1072\begin{cfa}
1073int * x[5]
1074\end{cfa}
1075&
1076\raisebox{-0.75\totalheight}{\input{Cdecl}}
1077\end{tabular}
1078\end{quote2}
1079Is this an array of 5 pointers to integers or a \Index{pointer} to an array of 5 integers?
1080The fact this declaration is unclear to many C programmers means there are \Index{productivity} and \Index{safety} issues even for basic programs.
1081Another 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.
1082For example, a routine returning a \Index{pointer} to an array of integers is defined and used in the following way:
1083\begin{cfa}
1084int ®(*®f®())[®5®]® {...};                              §\C{definition}§
1085 ... ®(*®f®())[®3®]® += 1;                              §\C{usage}§
1086\end{cfa}
1087Essentially, the return type is wrapped around the routine name in successive layers (like an \Index{onion}).
1088While attempting to make the two contexts consistent is a laudable goal, it has not worked out in practice.
1089
1090\CFA provides its own type, variable and routine declarations, using a different syntax.
1091The new declarations place qualifiers to the left of the base type, while C declarations place qualifiers to the right of the base type.
1092In the following example, \R{red} is the base type and \B{blue} is qualifiers.
1093The \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.
1094\begin{quote2}
1095\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1096\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1097\begin{cfa}
1098ß[5] *ß ®int® x1;
1099ß* [5]ß ®int® x2;
1100ß[* [5] int]ß f®( int p )®;
1101\end{cfa}
1102&
1103\begin{cfa}
1104®int® ß*ß x1 ß[5]ß;
1105®int® ß(*ßx2ß)[5]ß;
1106ßint (*ßf®( int p )®ß)[5]ß;
1107\end{cfa}
1108\end{tabular}
1109\end{quote2}
1110The only exception is \Index{bit field} specification, which always appear to the right of the base type.
1111% 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.
1112However, unlike C, \CFA type declaration tokens are distributed across all variables in the declaration list.
1113For instance, variables ©x© and ©y© of type \Index{pointer} to integer are defined in \CFA as follows:
1114\begin{quote2}
1115\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1116\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1117\begin{cfa}
1118®*® int x, y;
1119\end{cfa}
1120&
1121\begin{cfa}
1122int ®*®x, ®*®y;
1123\end{cfa}
1124\end{tabular}
1125\end{quote2}
1126The downside of this semantics is the need to separate regular and \Index{pointer} declarations:
1127\begin{quote2}
1128\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1129\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1130\begin{cfa}
1131®*® int x;
1132int y;
1133\end{cfa}
1134&
1135\begin{cfa}
1136int ®*®x, y;
1137
1138\end{cfa}
1139\end{tabular}
1140\end{quote2}
1141which is \Index{prescribing} a safety benefit.
1142Other examples are:
1143\begin{quote2}
1144\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
1145\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}} \\
1146\begin{cfa}
1147[ 5 ] int z;
1148[ 5 ] * char w;
1149* [ 5 ] double v;
1150struct s {
1151        int f0:3;
1152        * int f1;
1153        [ 5 ] * int f2;
1154};
1155\end{cfa}
1156&
1157\begin{cfa}
1158int z[ 5 ];
1159char * w[ 5 ];
1160double (* v)[ 5 ];
1161struct s {
1162        int f0:3;
1163        int * f1;
1164        int * f2[ 5 ]
1165};
1166\end{cfa}
1167&
1168\begin{cfa}
1169// array of 5 integers
1170// array of 5 pointers to char
1171// pointer to array of 5 doubles
1172
1173// common bit field syntax
1174
1175
1176
1177\end{cfa}
1178\end{tabular}
1179\end{quote2}
1180
1181All type qualifiers, \eg ©const©, ©volatile©, etc., are used in the normal way with the new declarations and also appear left to right, \eg:
1182\begin{quote2}
1183\begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
1184\multicolumn{1}{c@{\hspace{1em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{1em}}}{\textbf{C}} \\
1185\begin{cfa}
1186const * const int x;
1187const * [ 5 ] const int y;
1188\end{cfa}
1189&
1190\begin{cfa}
1191int const * const x;
1192const int (* const y)[ 5 ]
1193\end{cfa}
1194&
1195\begin{cfa}
1196// const pointer to const integer
1197// const pointer to array of 5 const integers
1198\end{cfa}
1199\end{tabular}
1200\end{quote2}
1201All 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}
1202The 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:
1203\begin{quote2}
1204\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}}
1205\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}} \\
1206\begin{cfa}
1207extern [ 5 ] int x;
1208static * const int y;
1209\end{cfa}
1210&
1211\begin{cfa}
1212int extern x[ 5 ];
1213const int static * y;
1214\end{cfa}
1215&
1216\begin{cfa}
1217// externally visible array of 5 integers
1218// internally visible pointer to constant int
1219\end{cfa}
1220\end{tabular}
1221\end{quote2}
1222
1223The new declaration syntax can be used in other contexts where types are required, \eg casts and the pseudo-routine ©sizeof©:
1224\begin{quote2}
1225\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1226\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1227\begin{cfa}
1228y = (®* int®)x;
1229i = sizeof(®[ 5 ] * int®);
1230\end{cfa}
1231&
1232\begin{cfa}
1233y = (®int *®)x;
1234i = sizeof(®int * [ 5 ]®);
1235\end{cfa}
1236\end{tabular}
1237\end{quote2}
1238
1239Finally, new \CFA declarations may appear together with C declarations in the same program block, but cannot be mixed within a specific declaration.
1240Therefore, a programmer has the option of either continuing to use traditional C declarations or take advantage of the new style.
1241Clearly, both styles need to be supported for some time due to existing C-style header-files, particularly for UNIX systems.
1242
1243
1244\section{Pointer / Reference}
1245
1246C provides a \newterm{pointer type};
1247\CFA adds a \newterm{reference type}.
1248These types may be derived from an object or routine type, called the \newterm{referenced type}.
1249Objects of these types contain an \newterm{address}, which is normally a location in memory, but may also address memory-mapped registers in hardware devices.
1250An integer constant expression with the value 0, or such an expression cast to type ©void *©, is called a \newterm{null-pointer constant}.\footnote{
1251One 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;
1252\ie the null pointer is guaranteed to compare unequal to a pointer to any object or routine.}
1253An 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.
1254Dereferencing an \newterm{unsound} address, including the null pointer, is \Index{undefined}, often resulting in a \Index{memory fault}.
1255
1256A program \newterm{object} is a region of data storage in the execution environment, the contents of which can represent values.
1257In 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:
1258\begin{quote2}
1259\begin{tabular}{@{}ll@{\hspace{2em}}l@{}}
1260\begin{cfa}
1261int x;
1262x = 3;
1263int y;
1264y = x;
1265\end{cfa}
1266&
1267\raisebox{-0.45\totalheight}{\input{pointer1}}
1268&
1269\begin{cfa}
1270int * ®const® x = (int *)100
1271*x = 3;                 // implicit dereference
1272int * ®const® y = (int *)104;
1273*y = *x;                // implicit dereference
1274\end{cfa}
1275\end{tabular}
1276\end{quote2}
1277where the right example is how the compiler logically interprets the variables in the left example.
1278Since a variable name only points to one address during its lifetime, it is an \Index{immutable} \Index{pointer};
1279hence, the implicit type of pointer variables ©x© and ©y© are constant pointers in the compiler interpretation.
1280In general, variable addresses are stored in instructions instead of loaded from memory, and hence may not occupy storage.
1281These approaches are contrasted in the following:
1282\begin{quote2}
1283\begin{tabular}{@{}l|l@{}}
1284\multicolumn{1}{c|}{explicit variable address} & \multicolumn{1}{c}{implicit variable address} \\
1285\hline
1286\begin{cfa}
1287lda             r1,100                  // load address of x
1288ld               r2,(r1)                  // load value of x
1289lda             r3,104                  // load address of y
1290st               r2,(r3)                  // store x into y
1291\end{cfa}
1292&
1293\begin{cfa}
1294
1295ld              r2,(100)                // load value of x
1296
1297st              r2,(104)                // store x into y
1298\end{cfa}
1299\end{tabular}
1300\end{quote2}
1301Finally, 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.
1302Therefore, 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}.
1303
1304A \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.
1305(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.)
1306Hence, a pointer occupies memory to store its current address, and the pointer's value is loaded by dereferencing, \eg:
1307\begin{quote2}
1308\begin{tabular}{@{}l@{\hspace{2em}}l@{}}
1309\begin{cfa}
1310int x, y, ®*® p1, ®*® p2, ®**® p3;
1311p1 = ®&®x;               // p1 points to x
1312p2 = p1;                 // p2 points to x
1313p1 = ®&®y;               // p1 points to y
1314p3 = &p2;               // p3 points to p2
1315\end{cfa}
1316&
1317\raisebox{-0.5\totalheight}{\input{pointer2.pstex_t}}
1318\end{tabular}
1319\end{quote2}
1320
1321Notice, an address has a \Index{duality}\index{address!duality}: a location in memory or the value at that location.
1322In many cases, a compiler might be able to infer the best meaning for these two cases.
1323For example, \Index*{Algol68}~\cite{Algol68} infers pointer dereferencing to select the best meaning for each pointer usage
1324\begin{cfa}
1325p2 = p1 + x;                                    §\C{// compiler infers *p2 = *p1 + x;}§
1326\end{cfa}
1327Algol68 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.
1328Unfortunately, automatic dereferencing does not work in all cases, and so some mechanism is necessary to fix incorrect choices.
1329
1330Rather than inferring dereference, most programming languages pick one implicit dereferencing semantics, and the programmer explicitly indicates the other to resolve address-duality.
1331In C, objects of pointer type always manipulate the pointer object's address:
1332\begin{cfa}
1333p1 = p2;                                                §\C{// p1 = p2\ \ rather than\ \ *p1 = *p2}§
1334p2 = p1 + x;                                    §\C{// p2 = p1 + x\ \ rather than\ \ *p2 = *p1 + x}§
1335\end{cfa}
1336even though the assignment to ©p2© is likely incorrect, and the programmer probably meant:
1337\begin{cfa}
1338p1 = p2;                                                §\C{// pointer address assignment}§
1339®*®p2 = ®*®p1 + x;                              §\C{// pointed-to value assignment / operation}§
1340\end{cfa}
1341The 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©).
1342
1343However, in most other situations, the pointed-to value is requested more often than the pointer address.
1344\begin{cfa}
1345*p2 = ((*p1 + *p2) * (**p3 - *p1)) / (**p3 - 15);
1346\end{cfa}
1347In this case, it is tedious to explicitly write the dereferencing, and error prone when pointer arithmetic is allowed.
1348It is better to have the compiler generate the dereferencing and have no implicit pointer arithmetic:
1349\begin{cfa}
1350p2 = ((p1 + p2) * (p3 - p1)) / (p3 - 15);
1351\end{cfa}
1352
1353To 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).
1354\begin{cfa}
1355int x, y, ®&® r1, ®&® r2, ®&&® r3;
1356®&®r1 = &x;                                             §\C{// r1 points to x}§
1357®&®r2 = &r1;                                    §\C{// r2 points to x}§
1358®&®r1 = &y;                                             §\C{// r1 points to y}§
1359®&&®r3 = ®&®&r2;                                §\C{// r3 points to r2}§
1360r2 = ((r1 + r2) * (r3 - r1)) / (r3 - 15); §\C{// implicit dereferencing}§
1361\end{cfa}
1362Except for auto-dereferencing by the compiler, this reference example is the same as the previous pointer example.
1363Hence, a reference behaves like the variable name for the current variable it is pointing-to.
1364One 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:
1365\begin{cfa}
1366®*®r2 = ((®*®r1 + ®*®r2) ®*® (®**®r3 - ®*®r1)) / (®**®r3 - 15);
1367\end{cfa}
1368When a reference operation appears beside a dereference operation, \eg ©&*©, they cancel out.
1369However, in C, the cancellation always yields a value (\Index{rvalue}).\footnote{
1370The unary ©&© operator yields the address of its operand.
1371If the operand has type ``type'', the result has type ``pointer to type''.
1372If 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}}
1373For a \CFA reference type, the cancellation on the left-hand side of assignment leaves the reference as an address (\Index{lvalue}):
1374\begin{cfa}
1375(&®*®)r1 = &x;                                  §\C{// (\&*) cancel giving address in r1 not variable pointed-to by r1}§
1376\end{cfa}
1377Similarly, the address of a reference can be obtained for assignment or computation (\Index{rvalue}):
1378\begin{cfa}
1379(&(&®*®)®*®)r3 = &(&®*®)r2;             §\C{// (\&*) cancel giving address in r2, (\&(\&*)*) cancel giving address in r3}§
1380\end{cfa}
1381Cancellation\index{cancellation!pointer/reference}\index{pointer!cancellation} works to arbitrary depth.
1382
1383Fundamentally, pointer and reference objects are functionally interchangeable because both contain addresses.
1384\begin{cfa}
1385int x, *p1 = &x, **p2 = &p1, ***p3 = &p2,
1386                 &r1 = x,    &&r2 = r1,   &&&r3 = r2;
1387***p3 = 3;                                              §\C{// change x}§
1388r3 = 3;                                                 §\C{// change x, ***r3}§
1389**p3 = ...;                                             §\C{// change p1}§
1390&r3 = ...;                                              §\C{// change r1, (\&*)**r3, 1 cancellation}§
1391*p3 = ...;                                              §\C{// change p2}§
1392&&r3 = ...;                                             §\C{// change r2, (\&(\&*)*)*r3, 2 cancellations}§
1393&&&r3 = p3;                                             §\C{// change r3 to p3, (\&(\&(\&*)*)*)r3, 3 cancellations}§
1394\end{cfa}
1395Furthermore, both types are equally performant, as the same amount of dereferencing occurs for both types.
1396Therefore, 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.
1397
1398As for a pointer type, a reference type may have qualifiers:
1399\begin{cfa}
1400const int cx = 5;                                       §\C{// cannot change cx;}§
1401const int & cr = cx;                            §\C{// cannot change what cr points to}§
1402®&®cr = &cx;                                            §\C{// can change cr}§
1403cr = 7;                                                         §\C{// error, cannot change cx}§
1404int & const rc = x;                                     §\C{// must be initialized}§
1405®&®rc = &x;                                                     §\C{// error, cannot change rc}§
1406const int & const crc = cx;                     §\C{// must be initialized}§
1407crc = 7;                                                        §\C{// error, cannot change cx}§
1408®&®crc = &cx;                                           §\C{// error, cannot change crc}§
1409\end{cfa}
1410Hence, 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}:
1411\begin{cfa}
1412int & const cr = *0;                            §\C{// where 0 is the int * zero}§
1413\end{cfa}
1414Note, constant reference-types do not prevent \Index{addressing errors} because of explicit storage-management:
1415\begin{cfa}
1416int & const cr = *malloc();
1417cr = 5;
1418free( &cr );
1419cr = 7;                                                         §\C{// unsound pointer dereference}§
1420\end{cfa}
1421
1422The position of the ©const© qualifier \emph{after} the pointer/reference qualifier causes confuse for C programmers.
1423The ©const© qualifier cannot be moved before the pointer/reference qualifier for C style-declarations;
1424\CFA-style declarations (see \VRef{s:Declarations}) attempt to address this issue:
1425\begin{quote2}
1426\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1427\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1428\begin{cfa}
1429®const® * ®const® * const int ccp;
1430®const® & ®const® & const int ccr;
1431\end{cfa}
1432&
1433\begin{cfa}
1434const int * ®const® * ®const® ccp;
1435
1436\end{cfa}
1437\end{tabular}
1438\end{quote2}
1439where the \CFA declaration is read left-to-right.
1440
1441Finally, like pointers, references are usable and composable with other type operators and generators.
1442\begin{cfa}
1443int w, x, y, z, & ar[3] = { x, y, z }; §\C{// initialize array of references}§
1444&ar[1] = &w;                                            §\C{// change reference array element}§
1445typeof( ar[1] ) p;                                      §\C{// (gcc) is int, i.e., the type of referenced object}§
1446typeof( &ar[1] ) q;                                     §\C{// (gcc) is int \&, i.e., the type of reference}§
1447sizeof( ar[1] ) == sizeof( int );       §\C{// is true, i.e., the size of referenced object}§
1448sizeof( &ar[1] ) == sizeof( int *)      §\C{// is true, i.e., the size of a reference}§
1449\end{cfa}
1450
1451In 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}.
1452Also, \CC does not allow \Index{array}s\index{array!reference} of reference\footnote{
1453The reason for disallowing arrays of reference is unknown, but possibly comes from references being ethereal (like a textual macro), and hence, replaceable by the referant object.}
1454\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.
1455
1456
1457\subsection{Initialization}
1458
1459\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.
1460There are three initialization contexts in \CFA: declaration initialization, argument/parameter binding, return/temporary binding.
1461Because 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.
1462In contrast, the left-hand side of assignment has an address that has a duality.
1463Therefore, for pointer/reference initialization, the initializing value must be an address not a value.
1464\begin{cfa}
1465int * p = &x;                                           §\C{// assign address of x}§
1466®int * p = x;®                                          §\C{// assign value of x}§
1467int & r = x;                                            §\C{// must have address of x}§
1468\end{cfa}
1469Like 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).
1470Therefore, 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.
1471Note, this is strictly a convenience and safety feature for a programmer.
1472Hence, \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.
1473Unfortunately, C allows ©p© to be assigned with ©&x© (address) or ©x© (value), but most compilers warn about the latter assignment as being potentially incorrect.
1474Similarly, 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.
1475\begin{cfa}
1476int & f( int & r );                                     §\C{// reference parameter and return}§
1477z = f( x ) + f( y );                            §\C{// reference operator added, temporaries needed for call results}§
1478\end{cfa}
1479Within routine ©f©, it is possible to change the argument by changing the corresponding parameter, and parameter ©r© can be locally reassigned within ©f©.
1480Since 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.
1481\begin{cfa}
1482int temp1 = f( x ), temp2 = f( y );
1483z = temp1 + temp2;
1484\end{cfa}
1485This \Index{implicit referencing} is crucial for reducing the syntactic burden for programmers when using references;
1486otherwise references have the same syntactic  burden as pointers in these contexts.
1487
1488When a pointer/reference parameter has a ©const© value (immutable), it is possible to pass literals and expressions.
1489\begin{cfa}
1490void f( ®const® int & cr );
1491void g( ®const® int * cp );
1492f( 3 );                   g( ®&®3 );
1493f( x + y );             g( ®&®(x + y) );
1494\end{cfa}
1495Here, 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.
1496The ©&© 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©).
1497Importantly, ©&3© may not be equal to ©&3©, where the references occur across calls because the temporaries maybe different on each call.
1498
1499\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{
1500If whole program analysis is possible, and shows the parameter is not assigned, \ie it is ©const©, the temporary is unnecessary.}
1501\begin{cfa}
1502void f( int & r );
1503void g( int * p );
1504f( 3 );                   g( ®&®3 );            §\C{// compiler implicit generates temporaries}§
1505f( x + y );             g( ®&®(x + y) );        §\C{// compiler implicit generates temporaries}§
1506\end{cfa}
1507Essentially, there is an implicit \Index{rvalue} to \Index{lvalue} conversion in this case.\footnote{
1508This 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.}
1509The implicit conversion allows seamless calls to any routine without having to explicitly name/copy the literal/expression to allow the call.
1510
1511%\CFA attempts to handle pointers and references in a uniform, symmetric manner.
1512Finally, C handles \Index{routine object}s in an inconsistent way.
1513A routine object is both a pointer and a reference (\Index{particle and wave}).
1514\begin{cfa}
1515void f( int i );
1516void (*fp)( int );                                      §\C{// routine pointer}§
1517fp = f;                                                         §\C{// reference initialization}§
1518fp = &f;                                                        §\C{// pointer initialization}§
1519fp = *f;                                                        §\C{// reference initialization}§
1520fp(3);                                                          §\C{// reference invocation}§
1521(*fp)(3);                                                       §\C{// pointer invocation}§
1522\end{cfa}
1523While 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.
1524Instead, a routine object should be referenced by a ©const© reference:
1525\begin{cfa}
1526®const® void (®&® fr)( int ) = f;       §\C{// routine reference}§
1527fr = ...                                                        §\C{// error, cannot change code}§
1528&fr = ...;                                                      §\C{// changing routine reference}§
1529fr( 3 );                                                        §\C{// reference call to f}§
1530(*fr)(3);                                                       §\C{// error, incorrect type}§
1531\end{cfa}
1532because the value of the routine object is a routine literal, \ie the routine code is normally immutable during execution.\footnote{
1533Dynamic code rewriting is possible but only in special circumstances.}
1534\CFA allows this additional use of references for routine objects in an attempt to give a more consistent meaning for them.
1535
1536
1537\subsection{Address-of Semantics}
1538
1539In C, ©&E© is an rvalue for any expression ©E©.
1540\CFA extends the ©&© (address-of) operator as follows:
1541\begin{itemize}
1542\item
1543if ©R© is an \Index{rvalue} of type ©T &$_1$...&$_r$© where $r \ge 1$ references (©&© symbols) than ©&R© has type ©T ®*®&$_{\color{red}2}$...&$_{\color{red}r}$©, \ie ©T© pointer with $r-1$ references (©&© symbols).
1544
1545\item
1546if ©L© is an \Index{lvalue} of type ©T &$_1$...&$_l$© where $l \ge 0$ references (©&© symbols) then ©&L© has type ©T ®*®&$_{\color{red}1}$...&$_{\color{red}l}$©, \ie ©T© pointer with $l$ references (©&© symbols).
1547\end{itemize}
1548The following example shows the first rule applied to different \Index{rvalue} contexts:
1549\begin{cfa}
1550int x, * px, ** ppx, *** pppx, **** ppppx;
1551int & rx = x, && rrx = rx, &&& rrrx = rrx ;
1552x = rrrx;               // rrrx is an lvalue with type int &&& (equivalent to x)
1553px = &rrrx;             // starting from rrrx, &rrrx is an rvalue with type int *&&& (&x)
1554ppx = &&rrrx;   // starting from &rrrx, &&rrrx is an rvalue with type int **&& (&rx)
1555pppx = &&&rrrx; // starting from &&rrrx, &&&rrrx is an rvalue with type int ***& (&rrx)
1556ppppx = &&&&rrrx; // starting from &&&rrrx, &&&&rrrx is an rvalue with type int **** (&rrrx)
1557\end{cfa}
1558The following example shows the second rule applied to different \Index{lvalue} contexts:
1559\begin{cfa}
1560int x, * px, ** ppx, *** pppx;
1561int & rx = x, && rrx = rx, &&& rrrx = rrx ;
1562rrrx = 2;               // rrrx is an lvalue with type int &&& (equivalent to x)
1563&rrrx = px;             // starting from rrrx, &rrrx is an rvalue with type int *&&& (rx)
1564&&rrrx = ppx;   // starting from &rrrx, &&rrrx is an rvalue with type int **&& (rrx)
1565&&&rrrx = pppx; // starting from &&rrrx, &&&rrrx is an rvalue with type int ***& (rrrx)
1566\end{cfa}
1567
1568
1569\subsection{Conversions}
1570
1571C provides a basic implicit conversion to simplify variable usage:
1572\begin{enumerate}
1573\setcounter{enumi}{-1}
1574\item
1575lvalue to rvalue conversion: ©cv T© converts to ©T©, which allows implicit variable dereferencing.
1576\begin{cfa}
1577int x;
1578x + 1;                  // lvalue variable (int) converts to rvalue for expression
1579\end{cfa}
1580An rvalue has no type qualifiers (©cv©), so the lvalue qualifiers are dropped.
1581\end{enumerate}
1582\CFA provides three new implicit conversion for reference types to simplify reference usage.
1583\begin{enumerate}
1584\item
1585reference to rvalue conversion: ©cv T &© converts to ©T©, which allows implicit reference dereferencing.
1586\begin{cfa}
1587int x, &r = x, f( int p );
1588x = ®r® + f( ®r® );  // lvalue reference converts to rvalue
1589\end{cfa}
1590An rvalue has no type qualifiers (©cv©), so the reference qualifiers are dropped.
1591
1592\item
1593lvalue to reference conversion: \lstinline[deletekeywords=lvalue]$lvalue-type cv1 T$ converts to ©cv2 T &©, which allows implicitly converting variables to references.
1594\begin{cfa}
1595int x, &r = ®x®, f( int & p ); // lvalue variable (int) convert to reference (int &)
1596f( ®x® );               // lvalue variable (int) convert to reference (int &)
1597\end{cfa}
1598Conversion can restrict a type, where ©cv1© $\le$ ©cv2©, \eg passing an ©int© to a ©const volatile int &©, which has low cost.
1599Conversion can expand a type, where ©cv1© $>$ ©cv2©, \eg passing a ©const volatile int© to an ©int &©, which has high cost (\Index{warning});
1600furthermore, if ©cv1© has ©const© but not ©cv2©, a temporary variable is created to preserve the immutable lvalue.
1601
1602\item
1603rvalue to reference conversion: ©T© converts to ©cv T &©, which allows binding references to temporaries.
1604\begin{cfa}
1605int x, & f( int & p );
1606f( ®x + 3® );   // rvalue parameter (int) implicitly converts to lvalue temporary reference (int &)
1607®&f®(...) = &x; // rvalue result (int &) implicitly converts to lvalue temporary reference (int &)
1608\end{cfa}
1609In both case, modifications to the temporary are inaccessible (\Index{warning}).
1610Conversion expands the temporary-type with ©cv©, which is low cost since the temporary is inaccessible.
1611\end{enumerate}
1612
1613
1614\begin{comment}
1615From: Richard Bilson <rcbilson@gmail.com>
1616Date: Wed, 13 Jul 2016 01:58:58 +0000
1617Subject: Re: pointers / references
1618To: "Peter A. Buhr" <pabuhr@plg2.cs.uwaterloo.ca>
1619
1620As a general comment I would say that I found the section confusing, as you move back and forth
1621between various real and imagined programming languages. If it were me I would rewrite into two
1622subsections, one that specifies precisely the syntax and semantics of reference variables and
1623another that provides the rationale.
1624
1625I don't see any obvious problems with the syntax or semantics so far as I understand them. It's not
1626obvious that the description you're giving is complete, but I'm sure you'll find the special cases
1627as you do the implementation.
1628
1629My big gripes are mostly that you're not being as precise as you need to be in your terminology, and
1630that you say a few things that aren't actually true even though I generally know what you mean.
1631
163220 C provides a pointer type; CFA adds a reference type. Both types contain an address, which is normally a
163321 location in memory.
1634
1635An address is not a location in memory; an address refers to a location in memory. Furthermore it
1636seems weird to me to say that a type "contains" an address; rather, objects of that type do.
1637
163821 Special addresses are used to denote certain states or access co-processor memory. By
163922 convention, no variable is placed at address 0, so addresses like 0, 1, 2, 3 are often used to denote no-value
164023 or other special states.
1641
1642This isn't standard C at all. There has to be one null pointer representation, but it doesn't have
1643to be a literal zero representation and there doesn't have to be more than one such representation.
1644
164523 Often dereferencing a special state causes a memory fault, so checking is necessary
164624 during execution.
1647
1648I don't see the connection between the two clauses here. I feel like if a bad pointer will not cause
1649a memory fault then I need to do more checking, not less.
1650
165124 If the programming language assigns addresses, a program's execution is sound, \ie all
165225 addresses are to valid memory locations.
1653
1654You haven't said what it means to "assign" an address, but if I use my intuitive understanding of
1655the term I don't see how this can be true unless you're assuming automatic storage management.
1656
16571 Program variables are implicit pointers to memory locations generated by the compiler and automatically
16582 dereferenced, as in:
1659
1660There is no reason why a variable needs to have a location in memory, and indeed in a typical
1661program many variables will not. In standard terminology an object identifier refers to data in the
1662execution environment, but not necessarily in memory.
1663
166413 A pointer/reference is a generalization of a variable name, \ie a mutable address that can point to more
166514 than one memory location during its lifetime.
1666
1667I feel like you're off the reservation here. In my world there are objects of pointer type, which
1668seem to be what you're describing here, but also pointer values, which can be stored in an object of
1669pointer type but don't necessarily have to be. For example, how would you describe the value denoted
1670by "&main" in a C program? I would call it a (function) pointer, but that doesn't satisfy your
1671definition.
1672
167316 not occupy storage as the literal is embedded directly into instructions.) Hence, a pointer occupies memory
167417 to store its current address, and the pointer's value is loaded by dereferencing, \eg:
1675
1676As with my general objection regarding your definition of variables, there is no reason why a
1677pointer variable (object of pointer type) needs to occupy memory.
1678
167921 p2 = p1 + x; // compiler infers *p2 = *p1 + x;
1680
1681What language are we in now?
1682
168324 pointer usage. However, in C, the following cases are ambiguous, especially with pointer arithmetic:
168425 p1 = p2; // p1 = p2 or *p1 = *p2
1685
1686This isn't ambiguous. it's defined to be the first option.
1687
168826 p1 = p1 + 1; // p1 = p1 + 1 or *p1 = *p1 + 1
1689
1690Again, this statement is not ambiguous.
1691
169213 example. Hence, a reference behaves like the variable name for the current variable it is pointing-to. The
169314 simplest way to understand a reference is to imagine the compiler inserting a dereference operator before
169415 the reference variable for each reference qualifier in a declaration, \eg:
1695
1696It's hard for me to understand who the audience for this part is. I think a practical programmer is
1697likely to be satisfied with "a reference behaves like the variable name for the current variable it
1698is pointing-to," maybe with some examples. Your "simplest way" doesn't strike me as simpler than
1699that. It feels like you're trying to provide a more precise definition for the semantics of
1700references, but it isn't actually precise enough to be a formal specification. If you want to
1701express the semantics of references using rewrite rules that's a great way to do it, but lay the
1702rules out clearly, and when you're showing an example of rewriting keep your
1703references/pointers/values separate (right now, you use \eg "r3" to mean a reference, a pointer,
1704and a value).
1705
170624 Cancellation works to arbitrary depth, and pointer and reference values are interchangeable because both
170725 contain addresses.
1708
1709Except they're not interchangeable, because they have different and incompatible types.
1710
171140 Interestingly, C++ deals with the address duality by making the pointed-to value the default, and prevent-
171241 ing changes to the reference address, which eliminates half of the duality. Java deals with the address duality
171342 by making address assignment the default and requiring field assignment (direct or indirect via methods),
171443 \ie there is no builtin bit-wise or method-wise assignment, which eliminates half of the duality.
1715
1716I can follow this but I think that's mostly because I already understand what you're trying to
1717say. I don't think I've ever heard the term "method-wise assignment" and I don't see you defining
1718it. Furthermore Java does have value assignment of basic (non-class) types, so your summary here
1719feels incomplete. (If it were me I'd drop this paragraph rather than try to save it.)
1720
172111 Hence, for type & const, there is no pointer assignment, so &rc = &x is disallowed, and the address value
172212 cannot be 0 unless an arbitrary pointer is assigned to the reference.
1723
1724Given the pains you've taken to motivate every little bit of the semantics up until now, this last
1725clause ("the address value cannot be 0") comes out of the blue. It seems like you could have
1726perfectly reasonable semantics that allowed the initialization of null references.
1727
172812 In effect, the compiler is managing the
172913 addresses for type & const not the programmer, and by a programming discipline of only using references
173014 with references, address errors can be prevented.
1731
1732Again, is this assuming automatic storage management?
1733
173418 rary binding. For reference initialization (like pointer), the initializing value must be an address (lvalue) not
173519 a value (rvalue).
1736
1737This sentence appears to suggest that an address and an lvalue are the same thing.
1738
173920 int * p = &x; // both &x and x are possible interpretations
1740
1741Are you saying that we should be considering "x" as a possible interpretation of the initializer
1742"&x"? It seems to me that this expression has only one legitimate interpretation in context.
1743
174421 int & r = x; // x unlikely interpretation, because of auto-dereferencing
1745
1746You mean, we can initialize a reference using an integer value? Surely we would need some sort of
1747cast to induce that interpretation, no?
1748
174922 Hence, the compiler implicitly inserts a reference operator, &, before the initialization expression.
1750
1751But then the expression would have pointer type, which wouldn't be compatible with the type of r.
1752
175322 Similarly,
175423 when a reference is used for a parameter/return type, the call-site argument does not require a reference
175524 operator.
1756
1757Furthermore, it would not be correct to use a reference operator.
1758
175945 The implicit conversion allows
17601 seamless calls to any routine without having to explicitly name/copy the literal/expression to allow the call.
17612 While C' attempts to handle pointers and references in a uniform, symmetric manner, C handles routine
17623 variables in an inconsistent way: a routine variable is both a pointer and a reference (particle and wave).
1763
1764After all this talk of how expressions can have both pointer and value interpretations, you're
1765disparaging C because it has expressions that have both pointer and value interpretations?
1766
1767On Sat, Jul 9, 2016 at 4:18 PM Peter A. Buhr <pabuhr@plg.uwaterloo.ca> wrote:
1768> Aaron discovered a few places where "&"s are missing and where there are too many "&", which are
1769> corrected in the attached updated. None of the text has changed, if you have started reading
1770> already.
1771\end{comment}
1772
1773
1774\section{Routine Definition}
1775
1776\CFA also supports a new syntax for routine definition, as well as \Celeven and K\&R routine syntax.
1777The point of the new syntax is to allow returning multiple values from a routine~\cite{Galletly96,CLU}, \eg:
1778\begin{cfa}
1779®[ int o1, int o2, char o3 ]® f( int i1, char i2, char i3 ) {
1780        §\emph{routine body}§
1781}
1782\end{cfa}
1783where routine ©f© has three output (return values) and three input parameters.
1784Existing C syntax cannot be extended with multiple return types because it is impossible to embed a single routine name within multiple return type specifications.
1785
1786In 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{
1787\Index*{Michael Tiemann}, with help from \Index*{Doug Lea}, provided named return values in g++, circa 1989.}
1788The value of each local return variable is automatically returned at routine termination.
1789Declaration qualifiers can only appear at the start of a routine definition, \eg:
1790\begin{cfa}
1791®extern® [ int x ] g( int y ) {§\,§}
1792\end{cfa}
1793Lastly, if there are no output parameters or input parameters, the brackets and/or parentheses must still be specified;
1794in 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:
1795\begin{cfa}
1796\,§] g();                                                     §\C{// no input or output parameters}§
1797[ void ] g( void );                                     §\C{// no input or output parameters}§
1798\end{cfa}
1799
1800Routine f is called as follows:
1801\begin{cfa}
1802[ i, j, ch ] = f( 3, 'a', ch );
1803\end{cfa}
1804The 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.
1805
1806\CFA style declarations cannot be used to declare parameters for K\&R style routine definitions because of the following ambiguity:
1807\begin{cfa}
1808int (*f(x))[ 5 ] int x; {}
1809\end{cfa}
1810The 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.
1811Since the strings overlap starting with the open bracket, ©[©, there is an ambiguous interpretation for the string.
1812As well, \CFA-style declarations cannot be used to declare parameters for C-style routine-definitions because of the following ambiguity:
1813\begin{cfa}
1814typedef int foo;
1815int f( int (* foo) );                           §\C{// foo is redefined as a parameter name}§
1816\end{cfa}
1817The 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.
1818The 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.
1819The 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.
1820
1821C-style declarations can be used to declare parameters for \CFA style routine definitions, \eg:
1822\begin{cfa}
1823[ int ] f( * int, int * );                      §\C{// returns an integer, accepts 2 pointers to integers}§
1824[ * int, int * ] f( int );                      §\C{// returns 2 pointers to integers, accepts an integer}§
1825\end{cfa}
1826The 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:
1827\begin{cfa}
1828#define ptoa( n, d ) int (*n)[ d ]
1829int f( ptoa( p, 5 ) ) ...                       §\C{// expands to int f( int (*p)[ 5 ] )}§
1830[ int ] f( ptoa( p, 5 ) ) ...           §\C{// expands to [ int ] f( int (*p)[ 5 ] )}§
1831\end{cfa}
1832Again, programmers are highly encouraged to use one declaration form or the other, rather than mixing the forms.
1833
1834
1835\subsection{Named Return Values}
1836
1837\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:
1838\begin{cfa}
1839int f() {
1840        int x;
1841        ... x = 0; ... x = y; ...
1842        return x;
1843}
1844\end{cfa}
1845Because 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:
1846\newline
1847\begin{minipage}{\linewidth}
1848\begin{cfa}
1849®[ int x, int y ]® f() {
1850        int z;
1851        ... x = 0; ... y = z; ...
1852        ®return;®                                                       §\C{// implicitly return x, y}§
1853}
1854\end{cfa}
1855\end{minipage}
1856\newline
1857When the return is encountered, the current values of ©x© and ©y© are returned to the calling routine.
1858As well, ``falling off the end'' of a routine without a ©return© statement is permitted, as in:
1859\begin{cfa}
1860[ int x, int y ] f() {
1861        ...
1862}                                                                               §\C{// implicitly return x, y}§
1863\end{cfa}
1864In this case, the current values of ©x© and ©y© are returned to the calling routine just as if a ©return© had been encountered.
1865
1866Named return values may be used in conjunction with named parameter values;
1867specifically, a return and parameter can have the same name.
1868\begin{cfa}
1869[ int x, int y ] f( int, x, int y ) {
1870        ...
1871}                                                                               §\C{// implicitly return x, y}§
1872\end{cfa}
1873This notation allows the compiler to eliminate temporary variables in nested routine calls.
1874\begin{cfa}
1875[ int x, int y ] f( int, x, int y );    §\C{// prototype declaration}§
1876int a, b;
1877[a, b] = f( f( f( a, b ) ) );
1878\end{cfa}
1879While 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.
1880Hence, even without the body of routine ©f© (separate compilation), it is possible to perform a global optimization across routine calls.
1881The compiler warns about naming inconsistencies between routine prototype and definition in this case, and behaviour is \Index{undefined} if the programmer is inconsistent.
1882
1883
1884\subsection{Routine Prototype}
1885
1886The syntax of the new routine prototype declaration follows directly from the new routine definition syntax;
1887as well, parameter names are optional, \eg:
1888\begin{cfa}
1889[ int x ] f ();                                                 §\C{// returning int with no parameters}§
1890[ * int ] g (int y);                                    §\C{// returning pointer to int with int parameter}§
1891[ ] h ( int, char );                                    §\C{// returning no result with int and char parameters}§
1892[ * int, int ] j ( int );                               §\C{// returning pointer to int and int, with int parameter}§
1893\end{cfa}
1894This syntax allows a prototype declaration to be created by cutting and pasting source text from the routine definition header (or vice versa).
1895It is possible to declare multiple routine-prototypes in a single declaration, but the entire type specification is distributed across \emph{all} routine names in the declaration list (see~\VRef{s:Declarations}), \eg:
1896\begin{quote2}
1897\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
1898\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{C}}        \\
1899\begin{cfa}
1900[ int ] f( int ), g;
1901\end{cfa}
1902&
1903\begin{cfa}
1904int f( int ), g( int );
1905\end{cfa}
1906\end{tabular}
1907\end{quote2}
1908Declaration qualifiers can only appear at the start of a \CFA routine declaration,\footref{StorageClassSpecifier} \eg:
1909\begin{cfa}
1910extern [ int ] f ( int );
1911static [ int ] g ( int );
1912\end{cfa}
1913
1914
1915\section{Routine Pointers}
1916
1917The syntax for pointers to \CFA routines specifies the pointer name on the right, \eg:
1918\begin{cfa}
1919* [ int x ] () fp;                                              §\C{// pointer to routine returning int with no parameters}§
1920* [ * int ] (int y) gp;                                 §\C{// pointer to routine returning pointer to int with int parameter}§
1921* [ ] (int,char) hp;                                    §\C{// pointer to routine returning no result with int and char parameters}§
1922* [ * int,int ] ( int ) jp;                             §\C{// pointer to routine returning pointer to int and int, with int parameter}§
1923\end{cfa}
1924While parameter names are optional, \emph{a routine name cannot be specified};
1925for example, the following is incorrect:
1926\begin{cfa}
1927* [ int x ] f () fp;                                    §\C{// routine name "f" is not allowed}§
1928\end{cfa}
1929
1930
1931\section{Named and Default Arguments}
1932
1933Named\index{named arguments}\index{arguments!named} and default\index{default arguments}\index{arguments!default} arguments~\cite{Hardgrave76}\footnote{
1934Francez~\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.}
1935are two mechanisms to simplify routine call.
1936Both mechanisms are discussed with respect to \CFA.
1937\begin{description}
1938\item[Named (or Keyword) Arguments:]
1939provide the ability to specify an argument to a routine call using the parameter name rather than the position of the parameter.
1940For example, given the routine:
1941\begin{cfa}
1942void p( int x, int y, int z ) {...}
1943\end{cfa}
1944a positional call is:
1945\begin{cfa}
1946p( 4, 7, 3 );
1947\end{cfa}
1948whereas a named (keyword) call may be:
1949\begin{cfa}
1950p( z : 3, x : 4, y : 7 );       §\C{// rewrite $\Rightarrow$ p( 4, 7, 3 )}§
1951\end{cfa}
1952Here the order of the arguments is unimportant, and the names of the parameters are used to associate argument values with the corresponding parameters.
1953The compiler rewrites a named call into a positional call.
1954The advantages of named parameters are:
1955\begin{itemize}
1956\item
1957Remembering the names of the parameters may be easier than the order in the routine definition.
1958\item
1959Parameter names provide documentation at the call site (assuming the names are descriptive).
1960\item
1961Changes can be made to the order or number of parameters without affecting the call (although the call must still be recompiled).
1962\end{itemize}
1963
1964Unfortunately, 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.
1965For example, the following routine prototypes and definition are all valid.
1966\begin{cfa}
1967void p( int, int, int );                        §\C{// equivalent prototypes}§
1968void p( int x, int y, int z );
1969void p( int y, int x, int z );
1970void p( int z, int y, int x );
1971void p( int q, int r, int s ) {}        §\C{// match with this definition}§
1972\end{cfa}
1973Forcing matching parameter names in routine prototypes with corresponding routine definitions is possible, but goes against a strong tradition in C programming.
1974Alternatively, prototype definitions can be eliminated by using a two-pass compilation, and implicitly creating header files for exports.
1975The former is easy to do, while the latter is more complex.
1976
1977Furthermore, named arguments do not work well in a \CFA-style programming-languages because they potentially introduces a new criteria for type matching.
1978For example, it is technically possible to disambiguate between these two overloaded definitions of ©f© based on named arguments at the call site:
1979\begin{cfa}
1980int f( int i, int j );
1981int f( int x, double y );
1982
1983f( j : 3, i : 4 );                              §\C{// 1st f}§
1984f( x : 7, y : 8.1 );                    §\C{// 2nd f}§
1985f( 4, 5 );                                              §\C{// ambiguous call}§
1986\end{cfa}
1987However, named arguments compound routine resolution in conjunction with conversions:
1988\begin{cfa}
1989f( i : 3, 5.7 );                                §\C{// ambiguous call ?}§
1990\end{cfa}
1991Depending on the cost associated with named arguments, this call could be resolvable or ambiguous.
1992Adding named argument into the routine resolution algorithm does not seem worth the complexity.
1993Therefore, \CFA does \emph{not} attempt to support named arguments.
1994
1995\item[Default Arguments]
1996provide the ability to associate a default value with a parameter so it can be optionally specified in the argument list.
1997For example, given the routine:
1998\begin{cfa}
1999void p( int x = 1, int y = 2, int z = 3 ) {...}
2000\end{cfa}
2001the allowable positional calls are:
2002\begin{cfa}
2003p();                                                    §\C{// rewrite $\Rightarrow$ p( 1, 2, 3 )}§
2004p( 4 );                                                 §\C{// rewrite $\Rightarrow$ p( 4, 2, 3 )}§
2005p( 4, 4 );                                              §\C{// rewrite $\Rightarrow$ p( 4, 4, 3 )}§
2006p( 4, 4, 4 );                                   §\C{// rewrite $\Rightarrow$ p( 4, 4, 4 )}§
2007// empty arguments
2008p(  , 4, 4 );                                   §\C{// rewrite $\Rightarrow$ p( 1, 4, 4 )}§
2009p( 4,  , 4 );                                   §\C{// rewrite $\Rightarrow$ p( 4, 2, 4 )}§
2010p( 4, 4,   );                                   §\C{// rewrite $\Rightarrow$ p( 4, 4, 3 )}§
2011p( 4,  ,   );                                   §\C{// rewrite $\Rightarrow$ p( 4, 2, 3 )}§
2012p(  , 4,   );                                   §\C{// rewrite $\Rightarrow$ p( 1, 4, 3 )}§
2013p(  ,  , 4 );                                   §\C{// rewrite $\Rightarrow$ p( 1, 2, 4 )}§
2014p(  ,  ,   );                                   §\C{// rewrite $\Rightarrow$ p( 1, 2, 3 )}§
2015\end{cfa}
2016Here the missing arguments are inserted from the default values in the parameter list.
2017The compiler rewrites missing default values into explicit positional arguments.
2018The advantages of default values are:
2019\begin{itemize}
2020\item
2021Routines with a large number of parameters are often very generalized, giving a programmer a number of different options on how a computation is performed.
2022For many of these kinds of routines, there are standard or default settings that work for the majority of computations.
2023Without 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.
2024\item
2025When a routine's interface is augmented with new parameters, it extends the interface providing generalizability\footnote{
2026``It should be possible for the implementor of an abstraction to increase its generality.
2027So long as the modified abstraction is a generalization of the original, existing uses of the abstraction will not require change.
2028It 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.
2029This 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}}
2030(somewhat like the generalization provided by inheritance for classes).
2031That is, all existing calls are still valid, although the call must still be recompiled.
2032\end{itemize}
2033The only disadvantage of default arguments is that unintentional omission of an argument may not result in a compiler-time error.
2034Instead, a default value is used, which may not be the programmer's intent.
2035
2036Default values may only appear in a prototype versus definition context:
2037\begin{cfa}
2038void p( int x, int y = 2, int z = 3 );          §\C{// prototype: allowed}§
2039void p( int, int = 2, int = 3 );                        §\C{// prototype: allowed}§
2040void p( int x, int y = 2, int z = 3 ) {}        §\C{// definition: not allowed}§
2041\end{cfa}
2042The reason for this restriction is to allow separate compilation.
2043Multiple prototypes with different default values is an error.
2044\end{description}
2045
2046Ellipse (``...'') arguments present problems when used with default arguments.
2047The conflict occurs because both named and ellipse arguments must appear after positional arguments, giving two possibilities:
2048\begin{cfa}
2049p( /* positional */, ... , /* named */ );
2050p( /* positional */, /* named */, ... );
2051\end{cfa}
2052While it is possible to implement both approaches, the first possibly is more complex than the second, \eg:
2053\begin{cfa}
2054p( int x, int y, int z, ... );
2055p( 1, 4, 5, 6, z : 3, y : 2 ); §\C{// assume p( /* positional */, ... , /* named */ );}§
2056p( 1, z : 3, y : 2, 4, 5, 6 ); §\C{// assume p( /* positional */, /* named */, ... );}§
2057\end{cfa}
2058In 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.
2059Hence, this approach seems significantly more difficult, and hence, confusing and error prone.
2060In the second call, the named arguments separate the positional and ellipse arguments, making it trivial to read the call.
2061
2062The problem is exacerbated with default arguments, \eg:
2063\begin{cfa}
2064void p( int x, int y = 2, int z = 3... );
2065p( 1, 4, 5, 6, z : 3 );         §\C{// assume p( /* positional */, ... , /* named */ );}§
2066p( 1, z : 3, 4, 5, 6 );         §\C{// assume p( /* positional */, /* named */, ... );}§
2067\end{cfa}
2068The first call is an error because arguments 4 and 5 are actually positional not ellipse arguments;
2069therefore, argument 5 subsequently conflicts with the named argument z : 3.
2070In 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.
2071For these reasons, \CFA requires named arguments before ellipse arguments.
2072Finally, 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 Section 24), making much of this discussion moot.
2073
2074Default arguments and overloading (see Section 24) are complementary.
2075While in theory default arguments can be simulated with overloading, as in:
2076\begin{quote2}
2077\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
2078\multicolumn{1}{c@{\hspace{3em}}}{\textbf{default arguments}}   & \multicolumn{1}{c}{\textbf{overloading}}      \\
2079\begin{cfa}
2080void p( int x, int y = 2, int z = 3 ) {...}
2081
2082
2083\end{cfa}
2084&
2085\begin{cfa}
2086void p( int x, int y, int z ) {...}
2087void p( int x ) { p( x, 2, 3 ); }
2088void p( int x, int y ) { p( x, y, 3 ); }
2089\end{cfa}
2090\end{tabular}
2091\end{quote2}
2092the number of required overloaded routines is linear in the number of default values, which is unacceptable growth.
2093In general, overloading should only be used over default arguments if the body of the routine is significantly different.
2094Furthermore, overloading cannot handle accessing default arguments in the middle of a positional list, via a missing argument, such as:
2095\begin{cfa}
2096p( 1, /* default */, 5 );               §\C{// rewrite $\Rightarrow$ p( 1, 2, 5 )}§
2097\end{cfa}
2098
2099Given the \CFA restrictions above, both named and default arguments are backwards compatible.
2100\Index*[C++]{\CC{}} only supports default arguments;
2101\Index*{Ada} supports both named and default arguments.
2102
2103
2104\section{Unnamed Structure Fields}
2105
2106C requires each field of a structure to have a name, except for a bit field associated with a basic type, \eg:
2107\begin{cfa}
2108struct {
2109        int f1;                                 §\C{// named field}§
2110        int f2 : 4;                             §\C{// named field with bit field size}§
2111        int : 3;                                §\C{// unnamed field for basic type with bit field size}§
2112        int ;                                   §\C{// disallowed, unnamed field}§
2113        int *;                                  §\C{// disallowed, unnamed field}§
2114        int (*)( int );                 §\C{// disallowed, unnamed field}§
2115};
2116\end{cfa}
2117This requirement is relaxed by making the field name optional for all field declarations; therefore, all the field declarations in the example are allowed.
2118As for unnamed bit fields, an unnamed field is used for padding a structure to a particular size.
2119A list of unnamed fields is also supported, \eg:
2120\begin{cfa}
2121struct {
2122        int , , ;                               §\C{// 3 unnamed fields}§
2123}
2124\end{cfa}
2125
2126
2127\section{Nesting}
2128
2129Nesting of types and routines is useful for controlling name visibility (\newterm{name hiding}).
2130
2131
2132\subsection{Type Nesting}
2133
2134\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.
2135\begin{figure}
2136\centering
2137\begin{tabular}{@{}l@{\hspace{3em}}l|l@{}}
2138\multicolumn{1}{c@{\hspace{3em}}}{\textbf{C Type Nesting}}      & \multicolumn{1}{c}{\textbf{C Implicit Hoisting}}      & \multicolumn{1}{|c}{\textbf{\CFA}}    \\
2139\hline
2140\begin{cfa}
2141struct S {
2142        enum C { R, G, B };
2143        struct T {
2144                union U { int i, j; };
2145                enum C c;
2146                short int i, j;
2147        };
2148        struct T t;
2149} s;
2150
2151int fred() {
2152        s.t.c = R;
2153        struct T t = { R, 1, 2 };
2154        enum C c;
2155        union U u;
2156}
2157\end{cfa}
2158&
2159\begin{cfa}
2160enum C { R, G, B };
2161union U { int i, j; };
2162struct T {
2163        enum C c;
2164        short int i, j;
2165};
2166struct S {
2167        struct T t;
2168} s;
2169       
2170
2171
2172
2173
2174
2175
2176\end{cfa}
2177&
2178\begin{cfa}
2179struct S {
2180        enum C { R, G, B };
2181        struct T {
2182                union U { int i, j; };
2183                enum C c;
2184                short int i, j;
2185        };
2186        struct T t;
2187} s;
2188
2189int fred() {
2190        s.t.c = ®S.®R;  // type qualification
2191        struct ®S.®T t = { ®S.®R, 1, 2 };
2192        enum ®S.®C c;
2193        union ®S.T.®U u;
2194}
2195\end{cfa}
2196\end{tabular}
2197\caption{Type Nesting / Qualification}
2198\label{f:TypeNestingQualification}
2199\end{figure}
2200In the left example in C, types ©C©, ©U© and ©T© are implicitly hoisted outside of type ©S© into the containing block scope.
2201In 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 ``©::©''.
2202
2203
2204\subsection{Routine Nesting}
2205
2206While \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.
2207For example, the C quick-sort is wrapped into the following polymorphic \CFA routine:
2208\begin{cfa}
2209forall( otype T | { int ?<?( T, T ); } )
2210void qsort( const T * arr, size_t dimension );
2211\end{cfa}
2212which can be used to sort in ascending and descending order by locally redefining the less-than operator into greater-than.
2213\begin{cfa}
2214const unsigned int size = 5;
2215int ia[size];
2216...                                             §\C{// assign values to array ia}§
2217qsort( ia, size );              §\C{// sort ascending order using builtin ?<?}§
2218{
2219        ®int ?<?( int x, int y ) { return x > y; }® §\C{// nested routine}§
2220        qsort( ia, size );      §\C{// sort descending order by local redefinition}§
2221}
2222\end{cfa}
2223
2224Nested routines are not first-class, meaning a nested routine cannot be returned if it has references to variables in its enclosing blocks;
2225the only exception is references to the external block of the translation unit, as these variables persist for the duration of the program.
2226The following program in undefined in \CFA (and Indexc{gcc})
2227\begin{cfa}
2228[* [int]( int )] foo() {                §\C{// int (*foo())( int )}§
2229        int ®i® = 7;
2230        int bar( int p ) {
2231                ®i® += 1;                               §\C{// dependent on local variable}§
2232                sout | ®i® | endl;
2233        }
2234        return bar;                                     §\C{// undefined because of local dependence}§
2235}
2236int main() {
2237        * [int]( int ) fp = foo();      §\C{// int (*fp)( int )}§
2238        sout | fp( 3 ) | endl;
2239}
2240\end{cfa}
2241because
2242
2243Currently, there are no \Index{lambda} expressions, \ie unnamed routines because routine names are very important to properly select the correct routine.
2244
2245
2246\section{Tuples}
2247
2248In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
2249(More contexts are added shortly.)
2250A list of such elements is called a \newterm{lexical list}.
2251The general syntax of a lexical list is:
2252\begin{cfa}
2253[ §\emph{exprlist}§ ]
2254\end{cfa}
2255where ©$\emph{exprlist}$© is a list of one or more expressions separated by commas.
2256The brackets, ©[]©, allow differentiating between lexical lists and expressions containing the C comma operator.
2257The following are examples of lexical lists:
2258\begin{cfa}
2259[ x, y, z ]
2260[ 2 ]
2261[ v+w, x*y, 3.14159, f() ]
2262\end{cfa}
2263Tuples 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.
2264Note, a tuple is not a record (structure);
2265a record denotes a single value with substructure, whereas a tuple is multiple values with no substructure (see flattening coercion in Section 12.1).
2266In essence, tuples are largely a compile time phenomenon, having little or no runtime presence.
2267
2268Tuples can be organized into compile-time tuple variables;
2269these variables are of \newterm{tuple type}.
2270Tuple variables and types can be used anywhere lists of conventional variables and types can be used.
2271The general syntax of a tuple type is:
2272\begin{cfa}
2273[ §\emph{typelist}§ ]
2274\end{cfa}
2275where ©$\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.
2276Examples of tuple types include:
2277\begin{cfa}
2278[ unsigned int, char ]
2279[ double, double, double ]
2280[ * int, int * ]                §\C{// mix of CFA and ANSI}§
2281[ * [ 5 ] int, * * char, * [ [ int, int ] ] (int, int) ]
2282\end{cfa}
2283Like 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.
2284
2285Examples of declarations using tuple types are:
2286\begin{cfa}
2287[ int, int ] x;                 §\C{// 2 element tuple, each element of type int}§
2288* [ char, char ] y;             §\C{// pointer to a 2 element tuple}§
2289[ [ int, int ] ] z ([ int, int ]);
2290\end{cfa}
2291The 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.
2292
2293As mentioned, tuples can appear in contexts requiring a list of value, such as an argument list of a routine call.
2294In unambiguous situations, the tuple brackets may be omitted, \eg a tuple that appears as an argument may have its
2295square brackets omitted for convenience; therefore, the following routine invocations are equivalent:
2296\begin{cfa}
2297f( [ 1, x+2, fred() ] );
2298f( 1, x+2, fred() );
2299\end{cfa}
2300Also, 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.
2301For example, the following are all legal:
2302\begin{cfa}
2303[ int, int ] w1;
2304[ int, int, int ] w2;
2305[ void ] f (int, int, int); /* three input parameters of type int */
2306[ void ] g ([ int, int, int ]); /* 3 element tuple as input */
2307f( [ 1, 2, 3 ] );
2308f( w1, 3 );
2309f( 1, w1 );
2310f( w2 );
2311g( [ 1, 2, 3 ] );
2312g( w1, 3 );
2313g( 1, w1 );
2314g( w2 );
2315\end{cfa}
2316Note, in all cases 3 arguments are supplied even though the syntax may appear to supply less than 3. As mentioned, a
2317tuple does not have structure like a record; a tuple is simply converted into a list of components.
2318\begin{rationale}
2319The 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.
2320Using a temporary variable to store the  results of the inner routine and then passing this variable to the outer routine works, however.
2321\end{rationale}
2322
2323A tuple can contain a C comma expression, provided the expression containing the comma operator is enclosed in parentheses.
2324For instance, the following tuples are equivalent:
2325\begin{cfa}
2326[ 1, 3, 5 ]
2327[ 1, (2, 3), 5 ]
2328\end{cfa}
2329The second element of the second tuple is the expression (2, 3), which yields the result 3.
2330This requirement is the same as for comma expressions in argument lists.
2331
2332Type qualifiers, \ie const and volatile, may modify a tuple type.
2333The 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:
2334\begin{cfa}
2335const volatile [ int, float, const int ] x;
2336\end{cfa}
2337is equivalent to:
2338\begin{cfa}
2339[ const volatile int, const volatile float, const volatile int ] x;
2340\end{cfa}
2341Declaration qualifiers can only appear at the start of a \CFA tuple declaration4, \eg:
2342\begin{cfa}
2343extern [ int, int ] w1;
2344static [ int, int, int ] w2;
2345\end{cfa}
2346\begin{rationale}
2347Unfortunately, C's syntax for subscripts precluded treating them as tuples.
2348The C subscript list has the form ©[i][j]...© and not ©[i, j, ...]©.
2349Therefore, 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.
2350Fixing 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.
2351\end{rationale}
2352
2353
2354\subsection{Tuple Coercions}
2355
2356There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
2357In addition, the coercion of dereferencing can be performed on a tuple variable to yield its value(s), as for other variables.
2358A \newterm{closing coercion} takes a set of values and converts it into a tuple value, which is a contiguous set of values, as in:
2359\begin{cfa}
2360[ int, int, int, int ] w;
2361w = [ 1, 2, 3, 4 ];
2362\end{cfa}
2363First the right-hand tuple is closed into a tuple value and then the tuple value is assigned.
2364
2365An \newterm{opening coercion} is the opposite of closing; a tuple value is converted into a tuple of values, as in:
2366\begin{cfa}
2367[ a, b, c, d ] = w
2368\end{cfa}
2369©w© is implicitly opened to yield a tuple of four values, which are then assigned individually.
2370
2371A \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:
2372\begin{cfa}
2373[ a, b, c, d ] = [ 1, [ 2, 3 ], 4 ];
2374\end{cfa}
2375First the right-hand tuple is flattened and then the values are assigned individually.
2376Flattening is also performed on tuple types.
2377For example, the type ©[ int, [ int, int ], int ]© can be coerced, using flattening, into the type ©[ int, int, int, int ]©.
2378
2379A \newterm{structuring coercion} is the opposite of flattening;
2380a tuple is structured into a more complex nested tuple.
2381For 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 ]©.
2382In the following example, the last assignment illustrates all the tuple coercions:
2383\begin{cfa}
2384[ int, int, int, int ] w = [ 1, 2, 3, 4 ];
2385int x = 5;
2386[ x, w ] = [ w, x ];            §\C{// all four tuple coercions}§
2387\end{cfa}
2388Starting on the right-hand tuple in the last assignment statement, w is opened, producing a tuple of four values;
2389therefore, the right-hand tuple is now the tuple ©[ [ 1, 2, 3, 4 ], 5 ]©.
2390This 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.
2391The tuple ©[ 2, 3, 4, 5 ]© is then closed to create a tuple value.
2392Finally, ©x© is assigned ©1© and ©w© is assigned the tuple value using multiple assignment (see Section 14).
2393\begin{rationale}
2394A possible additional language extension is to use the structuring coercion for tuples to initialize a complex record with a tuple.
2395\end{rationale}
2396
2397
2398\section{Mass Assignment}
2399
2400\CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
2401Mass assignment has the following form:
2402\begin{cfa}
2403[ §\emph{lvalue}§, ... , §\emph{lvalue}§ ] = §\emph{expr}§;
2404\end{cfa}
2405\index{lvalue}
2406The 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.
2407©$\emph{expr}$© is any standard arithmetic expression.
2408Clearly, the types of the entities being assigned must be type compatible with the value of the expression.
2409
2410Mass assignment has parallel semantics, \eg the statement:
2411\begin{cfa}
2412[ x, y, z ] = 1.5;
2413\end{cfa}
2414is equivalent to:
2415\begin{cfa}
2416x = 1.5; y = 1.5; z = 1.5;
2417\end{cfa}
2418This semantics is not the same as the following in C:
2419\begin{cfa}
2420x = y = z = 1.5;
2421\end{cfa}
2422as conversions between intermediate assignments may lose information.
2423A more complex example is:
2424\begin{cfa}
2425[ i, y[i], z ] = a + b;
2426\end{cfa}
2427which is equivalent to:
2428\begin{cfa}
2429t = a + b;
2430a1 = &i; a2 = &y[i]; a3 = &z;
2431*a1 = t; *a2 = t; *a3 = t;
2432\end{cfa}
2433The temporary ©t© is necessary to store the value of the expression to eliminate conversion issues.
2434The temporaries for the addresses are needed so that locations on the left-hand side do not change as the values are assigned.
2435In this case, ©y[i]© uses the previous value of ©i© and not the new value set at the beginning of the mass assignment.
2436
2437
2438\section{Multiple Assignment}
2439
2440\CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
2441Multiple assignment has the following form:
2442\begin{cfa}
2443[ §\emph{lvalue}§, ... , §\emph{lvalue}§ ] = [ §\emph{expr}§, ... , §\emph{expr}§ ];
2444\end{cfa}
2445\index{lvalue}
2446The left-hand side is a tuple of \emph{lvalues}, and the right-hand side is a tuple of \emph{expr}s.
2447Each \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.
2448An example of multiple assignment is:
2449\begin{cfa}
2450[ x, y, z ] = [ 1, 2, 3 ];
2451\end{cfa}
2452Here, the values ©1©, ©2© and ©3© are assigned, respectively, to the variables ©x©, ©y© and ©z©.
2453 A more complex example is:
2454\begin{cfa}
2455[ i, y[ i ], z ] = [ 1, i, a + b ];
2456\end{cfa}
2457Here, the values ©1©, ©i© and ©a + b© are assigned to the variables ©i©, ©y[i]© and ©z©, respectively.
2458 Note, the parallel semantics of
2459multiple assignment ensures:
2460\begin{cfa}
2461[ x, y ] = [ y, x ];
2462\end{cfa}
2463correctly interchanges (swaps) the values stored in ©x© and ©y©.
2464The following cases are errors:
2465\begin{cfa}
2466[ a, b, c ] = [ 1, 2, 3, 4 ];
2467[ a, b, c ] = [ 1, 2 ];
2468\end{cfa}
2469because the number of entities in the left-hand tuple is unequal with the right-hand tuple.
2470
2471As 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;
2472both these examples produce indeterminate results:
2473\begin{cfa}
2474f( x++, x++ );                          §\C{// C routine call with side effects in arguments}§
2475[ v1, v2 ] = [ x++, x++ ];      §\C{// side effects in righthand side of multiple assignment}§
2476\end{cfa}
2477
2478
2479\section{Cascade Assignment}
2480
2481As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
2482Cascade assignment has the following form:
2483\begin{cfa}
2484§\emph{tuple}§ = §\emph{tuple}§ = ... = §\emph{tuple}§;
2485\end{cfa}
2486and it has the same parallel semantics as for mass and multiple assignment.
2487Some examples of cascade assignment are:
2488\begin{cfa}
2489x1 = y1 = x2 = y2 = 0;
2490[ x1, y1 ] = [ x2, y2 ] = [ x3, y3 ];
2491[ x1, y1 ] = [ x2, y2 ] = 0;
2492[ x1, y1 ] = z = 0;
2493\end{cfa}
2494As in C, the rightmost assignment is performed first, \ie assignment parses right to left.
2495
2496
2497\section{Field Tuples}
2498
2499Tuples may be used to select multiple fields of a record by field name.
2500Its general form is:
2501\begin{cfa}
2502§\emph{expr}§ . [ §\emph{fieldlist}§ ]
2503§\emph{expr}§ -> [ §\emph{fieldlist}§ ]
2504\end{cfa}
2505\emph{expr} is any expression yielding a value of type record, \eg ©struct©, ©union©.
2506Each element of \emph{ fieldlist} is an element of the record specified by \emph{expr}.
2507A record-field tuple may be used anywhere a tuple can be used. An example of the use of a record-field tuple is
2508the following:
2509\begin{cfa}
2510struct s {
2511        int f1, f2;
2512        char f3;
2513        double f4;
2514} v;
2515v.[ f3, f1, f2 ] = ['x', 11, 17 ];      §\C{// equivalent to v.f3 = 'x', v.f1 = 11, v.f2 = 17}§
2516f( v.[ f3, f1, f2 ] );                          §\C{// equivalent to f( v.f3, v.f1, v.f2 )}§
2517\end{cfa}
2518Note, the fields appearing in a record-field tuple may be specified in any order;
2519also, it is unnecessary to specify all the fields of a struct in a multiple record-field tuple.
2520
2521If a field of a ©struct© is itself another ©struct©, multiple fields of this subrecord can be specified using a nested record-field tuple, as in the following example:
2522\begin{cfa}
2523struct inner {
2524        int f2, f3;
2525};
2526struct outer {
2527        int f1;
2528        struct inner i;
2529        double f4;
2530} o;
2531
2532o.[ f1, i.[ f2, f3 ], f4 ] = [ 11, 12, 13, 3.14159 ];
2533\end{cfa}
2534
2535
2536\section{I/O Library}
2537\label{s:IOLibrary}
2538\index{input/output library}
2539
2540The goal of \CFA 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.
2541The approach combines ideas from \CC and Python.
2542The \CFA header file for the I/O library is \Indexc{fstream}.
2543
2544The common case is printing out a sequence of variables separated by whitespace.
2545\begin{quote2}
2546\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
2547\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}}        & \multicolumn{1}{c}{\textbf{\CC}}      \\
2548\begin{cfa}
2549int x = 1, y = 2, z = 3;
2550sout | x ®|® y ®|® z | endl;
2551\end{cfa}
2552&
2553\begin{cfa}
2554
2555cout << x ®<< " "® << y ®<< " "® << z << endl;
2556\end{cfa}
2557\\
2558\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
25591® ®2® ®3
2560\end{cfa}
2561&
2562\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
25631 2 3
2564\end{cfa}
2565\end{tabular}
2566\end{quote2}
2567The \CFA form has half the characters of the \CC form, and is similar to \Index*{Python} I/O with respect to implicit separators.
2568Similar simplification occurs for \Index{tuple} I/O, which prints all tuple values separated by ``\lstinline[showspaces=true]@, @''.
2569\begin{cfa}
2570[int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
2571sout | t1 | t2 | endl;                                  §\C{// print tuples}§
2572\end{cfa}
2573\begin{cfa}[showspaces=true,aboveskip=0pt]
25741®, ®2®, ®3 4®, ®5®, ®6
2575\end{cfa}
2576Finally, \CFA uses the logical-or operator for I/O as it is the lowest-priority overloadable operator, other than assignment.
2577Therefore, fewer output expressions require parenthesis.
2578\begin{quote2}
2579\begin{tabular}{@{}ll@{}}
2580\textbf{\CFA:}
2581&
2582\begin{cfa}
2583sout | x * 3 | y + 1 | z << 2 | x == y | (x | y) | (x || y) | (x > z ? 1 : 2) | endl;
2584\end{cfa}
2585\\
2586\textbf{\CC:}
2587&
2588\begin{cfa}
2589cout << x * 3 << y + 1 << ®(®z << 2®)® << ®(®x == y®)® << (x | y) << (x || y) << (x > z ? 1 : 2) << endl;
2590\end{cfa}
2591\\
2592&
2593\begin{cfa}[showspaces=true,aboveskip=0pt]
25943 3 12 0 3 1 2
2595\end{cfa}
2596\end{tabular}
2597\end{quote2}
2598There is a weak similarity between the \CFA logical-or operator and the Shell pipe-operator for moving data, where data flows in the correct direction for input but the opposite direction for output.
2599
2600
2601\subsection{Implicit Separator}
2602
2603The \Index{implicit separator}\index{I/O!separator} character (space/blank) is a separator not a terminator.
2604The rules for implicitly adding the separator are:
2605\begin{enumerate}
2606\item
2607A separator does not appear at the start or end of a line.
2608\begin{cfa}[belowskip=0pt]
2609sout | 1 | 2 | 3 | endl;
2610\end{cfa}
2611\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
26121 2 3
2613\end{cfa}
2614
2615\item
2616A separator does not appear before or after a character literal or variable.
2617\begin{cfa}
2618sout | '1' | '2' | '3' | endl;
2619123
2620\end{cfa}
2621
2622\item
2623A separator does not appear before or after a null (empty) C string.
2624\begin{cfa}
2625sout | 1 | "" | 2 | "" | 3 | endl;
2626123
2627\end{cfa}
2628which is a local mechanism to disable insertion of the separator character.
2629
2630\item
2631A separator does not appear before a C string starting with the (extended) \Index*{ASCII}\index{ASCII!extended} characters: \lstinline[mathescape=off,basicstyle=\tt]@([{=$£¥¡¿«@
2632%$
2633\begin{cfa}[mathescape=off]
2634sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x £" | 6 | "x ¥"
2635                | 7 | "x ¡" | 8 | "x ¿" | 9 | "x «" | 10 | endl;
2636\end{cfa}
2637%$
2638\begin{cfa}[mathescape=off,basicstyle=\tt,showspaces=true,aboveskip=0pt,belowskip=0pt]
2639x ®(®1 x ®[®2 x ®{®3 x ®=®4 x ®$®5 x ®£®6 x ®¥®7 x ®¡®8 x ®¿®9 x ®«®10
2640\end{cfa}
2641%$
2642where \lstinline[basicstyle=\tt]@¡¿@ are inverted opening exclamation and question marks, and \lstinline[basicstyle=\tt]@«@ is an opening citation mark.
2643
2644\item
2645{\lstset{language=CFA,deletedelim=**[is][]{¢}{¢}}
2646A seperator does not appear after a C string ending with the (extended) \Index*{ASCII}\index{ASCII!extended} characters: \lstinline[basicstyle=\tt]@,.;!?)]}%¢»@
2647\begin{cfa}[belowskip=0pt]
2648sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
2649                | 7 | "¢ x" | 8 | "» x" | 9 | ") x" | 10 | "] x" | 11 | "} x" | endl;
2650\end{cfa}
2651\begin{cfa}[basicstyle=\tt,showspaces=true,aboveskip=0pt,belowskip=0pt]
26521®,® x 2®.® x 3®;® x 4®!® x 5®?® x 6®%® x 7§\color{red}\textcent§ x 8®»® x 9®)® x 10®]® x 11®}® x
2653\end{cfa}}%
2654where \lstinline[basicstyle=\tt]@»@ is a closing citation mark.
2655
2656\item
2657A seperator does not appear before or after a C string begining/ending with the \Index*{ASCII} quote or whitespace characters: \lstinline[basicstyle=\tt,showspaces=true]@`'": \t\v\f\r\n@
2658\begin{cfa}[belowskip=0pt]
2659sout | "x`" | 1 | "`x'" | 2 | "'x\"" | 3 | "\"x:" | 4 | ":x " | 5 | " x\t" | 6 | "\tx" | endl;
2660\end{cfa}
2661\begin{cfa}[basicstyle=\tt,showspaces=true,showtabs=true,aboveskip=0pt,belowskip=0pt]
2662x®`®1®`®x§\color{red}\texttt{'}§2§\color{red}\texttt{'}§x§\color{red}\texttt{"}§3§\color{red}\texttt{"}§x®:®4®:®x® ®5® ®x®      ®6®     ®x
2663\end{cfa}
2664
2665\item
2666If a space is desired before or after one of the special string start/end characters, simply insert a space.
2667\begin{cfa}[belowskip=0pt]
2668sout | "x (§\color{red}\texttt{\textvisiblespace}§" | 1 | "§\color{red}\texttt{\textvisiblespace) x" | 2 | "§\color{red}\texttt{\textvisiblespace}§, x" | 3 | "§\color{red}\texttt{\textvisiblespace}§:x:§\color{red}\texttt{\textvisiblespace}§" | 4 | endl;
2669\end{cfa}
2670\begin{cfa}[basicstyle=\tt,showspaces=true,showtabs=true,aboveskip=0pt,belowskip=0pt]
2671x (® ®1® ®) x 2® ®, x 3® ®:x:® ®4
2672\end{cfa}
2673\end{enumerate}
2674
2675
2676\subsection{Manipulator}
2677
2678The following \CC-style \Index{manipulator}s and routines control implicit seperation.
2679\begin{enumerate}
2680\item
2681Routines \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.
2682The separator string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
2683\begin{cfa}[mathescape=off,belowskip=0pt]
2684sepSet( sout, ", $" );                                          §\C{// set separator from " " to ", \$"}§
2685sout | 1 | 2 | 3 | " \"" | ®sep® | "\"" | endl;
2686\end{cfa}
2687%$
2688\begin{cfa}[mathescape=off,showspaces=true,aboveskip=0pt]
26891®, $®2®, $®3 ®", $
2690\end{cfa}
2691%$
2692\begin{cfa}[belowskip=0pt]
2693sepSet( sout, " " );                                            §\C{// reset separator to " "}§
2694sout | 1 | 2 | 3 | " \"" | ®sepGet( sout )® | "\"" | endl;
2695\end{cfa}
2696\begin{cfa}[showspaces=true,aboveskip=0pt]
26971® ®2® ®3 ®" "®
2698\end{cfa}
2699©sepGet© can be used to store a separator and then restore it:
2700\begin{cfa}[belowskip=0pt]
2701char store[®sepSize®];                                          §\C{// sepSize is the maximum separator size}§
2702strcpy( store, sepGet( sout ) );                          §\C{// copy current separator}§
2703sepSet( sout, "_" );                                            §\C{// change separator to underscore}§
2704sout | 1 | 2 | 3 | endl;
2705\end{cfa}
2706\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27071®_®2®_®3
2708\end{cfa}
2709\begin{cfa}[belowskip=0pt]
2710sepSet( sout, store );                                          §\C{// change separator back to original}§
2711sout | 1 | 2 | 3 | endl;
2712\end{cfa}
2713\begin{cfa}[showspaces=true,aboveskip=0pt]
27141® ®2® ®3
2715\end{cfa}
2716
2717\item
2718Routine \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.
2719The tuple separator-string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
2720\begin{cfa}[belowskip=0pt]
2721sepSetTuple( sout, " " );                                       §\C{// set tuple separator from ", " to " "}§
2722sout | t1 | t2 | " \"" | ®sepTuple® | "\"" | endl;
2723\end{cfa}
2724\begin{cfa}[showspaces=true,aboveskip=0pt]
27251 2 3 4 5 6 ®" "®
2726\end{cfa}
2727\begin{cfa}[belowskip=0pt]
2728sepSetTuple( sout, ", " );                                      §\C{// reset tuple separator to ", "}§
2729sout | t1 | t2 | " \"" | ®sepGetTuple( sout )® | "\"" | endl;
2730\end{cfa}
2731\begin{cfa}[showspaces=true,aboveskip=0pt]
27321, 2, 3 4, 5, 6 ®", "®
2733\end{cfa}
2734As for ©sepGet©, ©sepGetTuple© can be use to store a tuple separator and then restore it.
2735
2736\item
2737Manipulators \Indexc{sepDisable}\index{manipulator!sepDisable@©sepDisable©} and \Indexc{sepEnable}\index{manipulator!sepEnable@©sepEnable©} \emph{globally} toggle printing the separator, \ie the seperator is adjusted with respect to all subsequent printed items.
2738\begin{cfa}[belowskip=0pt]
2739sout | sepDisable | 1 | 2 | 3 | endl;           §\C{// globally turn off implicit separator}§
2740\end{cfa}
2741\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
2742123
2743\end{cfa}
2744\begin{cfa}[belowskip=0pt]
2745sout | sepEnable | 1 | 2 | 3 | endl;            §\C{// globally turn on implicit separator}§
2746\end{cfa}
2747\begin{cfa}[mathescape=off,showspaces=true,aboveskip=0pt,belowskip=0pt]
27481 2 3
2749\end{cfa}
2750
2751\item
2752Manipulators \Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} \emph{locally} toggle printing the separator, \ie the seperator is adjusted only with respect to the next printed item.
2753\begin{cfa}[belowskip=0pt]
2754sout | 1 | sepOff | 2 | 3 | endl;                       §\C{// locally turn off implicit separator}§
2755\end{cfa}
2756\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
275712 3
2758\end{cfa}
2759\begin{cfa}[belowskip=0pt]
2760sout | sepDisable | 1 | sepOn | 2 | 3 | endl; §\C{// locally turn on implicit separator}§
2761\end{cfa}
2762\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27631 23
2764\end{cfa}
2765The tuple separator also responses to being turned on and off.
2766\begin{cfa}[belowskip=0pt]
2767sout | t1 | sepOff | t2 | endl;                         §\C{// locally turn on/off implicit separator}§
2768\end{cfa}
2769\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27701, 2, 34, 5, 6
2771\end{cfa}
2772©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;
2773use ©sep© to accomplish this functionality.
2774\begin{cfa}[belowskip=0pt]
2775sout | sepOn | 1 | 2 | 3 | sepOn | endl ;       §\C{// sepOn does nothing at start/end of line}§
2776\end{cfa}
2777\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
27781 2 3
2779\end{cfa}
2780\begin{cfa}[belowskip=0pt]
2781sout | sep | 1 | 2 | 3 | sep | endl ;           §\C{// use sep to print separator at start/end of line}§
2782\end{cfa}
2783\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
2784® ®1 2 3® ®
2785\end{cfa}
2786\end{enumerate}
2787
2788\begin{comment}
2789#include <fstream>
2790#include <string.h>                                                                             // strcpy
2791
2792int main( void ) {
2793        int x = 1, y = 2, z = 3;
2794        sout | x | y | z | endl;
2795        [int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
2796        sout | t1 | t2 | endl;                                          // print tuples
2797        sout | x * 3 | y + 1 | z << 2 | x == y | (x | y) | (x || y) | (x > z ? 1 : 2) | endl;
2798        sout | 1 | 2 | 3 | endl;
2799        sout | '1' | '2' | '3' | endl;
2800        sout | 1 | "" | 2 | "" | 3 | endl;
2801        sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $" | 5 | "x £" | 6 | "x ¥"
2802                | 7 | "x ¡" | 8 | "x ¿" | 9 | "x «" | 10 | endl;
2803        sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
2804                | 7 | "¢ x" | 8 | "» x" | 9 | ") x" | 10 | "] x" | 11 | "} x" | endl;
2805        sout | "x`" | 1 | "`x'" | 2 | "'x\"" | 3 | "\"x:" | 4 | ":x " | 5 | " x\t" | 6 | "\tx" | endl;
2806        sout | "x ( " | 1 | " ) x" | 2 | " , x" | 3 | " :x: " | 4 | endl;
2807
2808        sepSet( sout, ", $" );                                          // set separator from " " to ", $"
2809        sout | 1 | 2 | 3 | " \"" | sep | "\"" | endl;
2810        sepSet( sout, " " );                                            // reset separator to " "
2811        sout | 1 | 2 | 3 | " \"" | sepGet( sout ) | "\"" | endl;
2812
2813        char store[sepSize];
2814        strcpy( store, sepGet( sout ) );
2815        sepSet( sout, "_" );
2816        sout | 1 | 2 | 3 | endl;
2817        sepSet( sout, store );
2818        sout | 1 | 2 | 3 | endl;
2819
2820        sepSetTuple( sout, " " );                                       // set tuple separator from ", " to " "
2821        sout | t1 | t2 | " \"" | sepTuple | "\"" | endl;
2822        sepSetTuple( sout, ", " );                                      // reset tuple separator to ", "
2823        sout | t1 | t2 | " \"" | sepGetTuple( sout ) | "\"" | endl;
2824
2825        sout | sepDisable | 1 | 2 | 3 | endl;           // globally turn off implicit separator
2826        sout | sepEnable | 1 | 2 | 3 | endl;            // globally turn on implicit separator
2827       
2828        sout | 1 | sepOff | 2 | 3 | endl;                       // locally turn on implicit separator
2829        sout | sepDisable | 1 | sepOn | 2 | 3 | endl; // globally turn off implicit separator
2830        sout | sepEnable;
2831        sout | t1 | sepOff | t2 | endl;                         // locally turn on/off implicit separator
2832
2833        sout | sepOn | 1 | 2 | 3 | sepOn | endl ;       // sepOn does nothing at start/end of line
2834        sout | sep | 1 | 2 | 3 | sep | endl ;           // use sep to print separator at start/end of line
2835}
2836
2837// Local Variables: //
2838// tab-width: 4 //
2839// fill-column: 100 //
2840// End: //
2841\end{comment}
2842%$
2843
2844
2845\section{Types}
2846
2847\subsection{Type Definitions}
2848
2849\CFA allows users to define new types using the keyword type.
2850
2851\begin{cfa}
2852// SensorValue is a distinct type and represented as an int
2853type SensorValue = int;
2854\end{cfa}
2855
2856A 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.
2857This means that users can define distinct function overloads for the new type (see Overloading for more information).
2858For example:
2859
2860\begin{cfa}
2861type SensorValue = int;
2862void printValue(int v) {...}
2863void printValue(SensorValue v) {...}
2864void process(int v) {...}
2865
2866SensorValue s = ...;
2867
2868printValue(s); // calls version with SensorValue argument
2869
2870printValue((int) s); // calls version with int argument
2871
2872process(s); // implicit conversion to int
2873\end{cfa}
2874
2875If SensorValue was defined with a typedef, then these two print functions would not have unique signatures.
2876This can be very useful to create a distinct type that has the same representation as another type.
2877
2878The compiler will assume it can safely convert from the old type to the new type, implicitly.
2879Users may override this and define a function that must be called to convert from one type to another.
2880
2881\begin{cfa}
2882type SensorValue = int;
2883// ()? is the overloaded conversion operator identifier
2884// This function converts an int to a SensorValue
2885SensorValue ()?(int val) {
2886        ...
2887}
2888void process(int v) {...}
2889
2890SensorValue s = ...;
2891process(s); // implicit call to conversion operator
2892\end{cfa}
2893
2894In many cases, it is not desired for the compiler to do this implicit conversion.
2895To avoid that, the user can use the explicit modifier on the conversion operator.
2896Any places where the conversion is needed but not explicit (with a cast), will result in a compile-time error.
2897
2898\begin{cfa}
2899type SensorValue = int;
2900
2901// conversion from int to SensorValue; must be explicit
2902explicit SensorValue ()?(int val) {
2903        ...
2904}
2905
2906void process(int v) {...}
2907
2908SensorValue s = ...;
2909process(s); // implicit cast to int: compile-time error
2910process((int) s); // explicit cast to int: calls conversion func
2911\end{cfa}
2912
2913The conversion may not require any code, but still need to be explicit; in that case, the syntax can be simplified to:
2914\begin{cfa}
2915type SensorValue = int;
2916explicit SensorValue ()?(int);
2917void process(int v) {...}
2918
2919SensorValue s = ...;
2920process(s); // compile-time error
2921process((int) s); // type is converted, no function is called
2922\end{cfa}
2923
2924
2925\subsection{Structures}
2926
2927Structures in \CFA are basically the same as structures in C.
2928A structure is defined with the same syntax as in C.
2929When referring to a structure in \CFA, users may omit the struct keyword.
2930\begin{cfa}
2931struct Point {
2932        double x;
2933        double y;
2934};
2935
2936Point p = {0.0, 0.0};
2937\end{cfa}
2938
2939\CFA does not support inheritance among types, but instead uses composition to enable reuse of structure fields.
2940Composition is achieved by embedding one type into another.
2941When 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.
2942Embedding types is achieved using anonymous members.
2943For example, using Point from above:
2944\begin{cfa}
2945void foo(Point p);
2946
2947struct ColoredPoint {
2948        Point; // anonymous member (no identifier)
2949        int Color;
2950};
2951...
2952        ColoredPoint cp = ...;
2953        cp.x = 10.3; // x from Point is accessed directly
2954        cp.color = 0x33aaff; // color is accessed normally
2955        foo(cp); // cp can be used directly as a Point
2956\end{cfa}
2957
2958
2959\section{Constructors and Destructors}
2960
2961\CFA supports C initialization of structures, but it also adds constructors for more advanced initialization.
2962Additionally, \CFA adds destructors that are called when a variable is deallocated (variable goes out of scope or object is deleted).
2963These functions take a reference to the structure as a parameter (see References for more information).
2964
2965\begin{figure}
2966\begin{cfa}
2967struct Widget {
2968        int id;
2969        float size;
2970        Parts *optionalParts;
2971};
2972
2973// ?{} is the constructor operator identifier
2974// The first argument is a reference to the type to initialize
2975// Subsequent arguments can be specified for initialization
2976
2977void ?{}(Widget &w) { // default constructor
2978        w.id = -1;
2979        w.size = 0.0;
2980        w.optionalParts = 0;
2981}
2982
2983// constructor with values (does not need to include all fields)
2984void ?{}(Widget &w, int id, float size) {
2985        w.id = id;
2986        w.size = size;
2987        w.optionalParts = 0;
2988}
2989
2990// ^? is the destructor operator identifier
2991void ^?(Widget &w) { // destructor
2992        w.id = 0;
2993        w.size = 0.0;
2994        if (w.optionalParts != 0) {
2995        // This is the only pointer to optionalParts, free it
2996        free(w.optionalParts);
2997        w.optionalParts = 0;
2998        }
2999}
3000
3001Widget baz; // reserve space only
3002Widget foo{}; // calls default constructor
3003Widget bar{23, 2.45}; // calls constructor with values
3004baz{24, 0.91}; // calls constructor with values
3005?{}(baz, 24, 0.91}; // explicit call to constructor
3006^bar; // explicit call to destructor
3007^?(bar); // explicit call to destructor
3008\end{cfa}
3009\caption{Constructors and Destructors}
3010\end{figure}
3011
3012
3013\section{Overloading}
3014
3015Overloading refers to the capability of a programmer to define and use multiple objects in a program with the same name.
3016In \CFA, a declaration may overload declarations from outer scopes with the same name, instead of hiding them as is the case in C.
3017This may cause identical C and \CFA programs to behave differently.
3018The compiler selects the appropriate object (overload resolution) based on context information at the place where it is used.
3019Overloading allows programmers to give functions with different signatures but similar semantics the same name, simplifying the interface to users.
3020Disadvantages 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.
3021\CFA allows overloading of functions, operators, variables, and even the constants 0 and 1.
3022
3023The compiler follows some overload resolution rules to determine the best interpretation of all of these overloads.
3024The best valid interpretations are the valid interpretations that use the fewest unsafe conversions.
3025Of these, the best are those where the functions and objects involved are the least polymorphic.
3026Of these, the best have the lowest total conversion cost, including all implicit conversions in the argument expressions.
3027Of these, the best have the highest total conversion cost for the implicit conversions (if any) applied to the argument expressions.
3028If there is no single best valid interpretation, or if the best valid interpretation is ambiguous, then the resulting interpretation is ambiguous.
3029For details about type inference and overload resolution, please see the \CFA Language Specification.
3030\begin{cfa}
3031int foo(int a, int b) {
3032        float sum = 0.0;
3033        float special = 1.0;
3034        {
3035                int sum = 0;
3036                // both the float and int versions of sum are available
3037                float special = 4.0;
3038                // this inner special hides the outer version
3039                ...
3040        }
3041        ...
3042}
3043\end{cfa}
3044
3045
3046\subsection{Overloaded Constant}
3047
3048The constants 0 and 1 have special meaning.
3049In \CFA, as in C, all scalar types can be incremented and
3050decremented, which is defined in terms of adding or subtracting 1.
3051The 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)©).
3052
3053In 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.
3054However, 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.
3055Defining special constants for a user-defined type is more efficient than defining a conversion to the type from ©_Bool©.
3056
3057Why just 0 and 1? Why not other integers? No other integers have special status in C.
3058A facility that let programmers declare specific constants..const Rational 12., for instance. would not be much of an improvement.
3059Some facility for defining the creation of values of programmer-defined types from arbitrary integer tokens would be needed.
3060The complexity of such a feature does not seem worth the gain.
3061
3062For example, to define the constants for a complex type, the programmer would define the following:
3063
3064\begin{cfa}
3065struct Complex {
3066        double real;
3067        double imaginary;
3068}
3069
3070const Complex 0 = {0, 0};
3071const Complex 1 = {1, 0};
3072...
3073
3074        Complex a = 0;
3075...
3076
3077        a++;
3078...
3079        if (a) { // same as if (a == 0)
3080...
3081}
3082\end{cfa}
3083
3084
3085\subsection{Variable Overloading}
3086
3087The overload rules of \CFA allow a programmer to define multiple variables with the same name, but different types.
3088Allowing 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.
3089For example, a developer may want to do the following:
3090\begin{cfa}
3091int pi = 3;
3092float pi = 3.14;
3093char pi = .p.;
3094\end{cfa}
3095
3096
3097\subsection{Function Overloading}
3098
3099Overloaded 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).
3100
3101The examples below give some basic intuition about how the resolution works.
3102\begin{cfa}
3103// Choose the one with less conversions
3104int doSomething(int value) {...} // option 1
3105int doSomething(short value) {...} // option 2
3106
3107int a, b = 4;
3108short c = 2;
3109
3110a = doSomething(b); // chooses option 1
3111a = doSomething(c); // chooses option 2
3112
3113// Choose the specialized version over the generic
3114
3115generic(type T)
3116T bar(T rhs, T lhs) {...} // option 3
3117float bar(float rhs, float lhs){...} // option 4
3118float a, b, c;
3119double d, e, f;
3120c = bar(a, b); // chooses option 4
3121
3122// specialization is preferred over unsafe conversions
3123
3124f = bar(d, e); // chooses option 5
3125\end{cfa}
3126
3127
3128\subsection{Operator Overloading}
3129
3130\CFA also allows operators to be overloaded, to simplify the use of user-defined types.
3131Overloading 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.
3132\CFA uses the following special identifiers to name overloaded operators:
3133
3134\begin{table}[hbt]
3135\hfil
3136\begin{tabular}[t]{ll}
3137%identifier & operation \\ \hline
3138©?[?]© & subscripting \impl{?[?]}\\
3139©?()© & function call \impl{?()}\\
3140©?++© & postfix increment \impl{?++}\\
3141©?--© & postfix decrement \impl{?--}\\
3142©++?© & prefix increment \impl{++?}\\
3143©--?© & prefix decrement \impl{--?}\\
3144©*?© & dereference \impl{*?}\\
3145©+?© & unary plus \impl{+?}\\
3146©-?© & arithmetic negation \impl{-?}\\
3147©~?© & bitwise negation \impl{~?}\\
3148©!?© & logical complement \impl{"!?}\\
3149©?*?© & multiplication \impl{?*?}\\
3150©?/?© & division \impl{?/?}\\
3151\end{tabular}\hfil
3152\begin{tabular}[t]{ll}
3153%identifier & operation \\ \hline
3154©?%?© & remainder \impl{?%?}\\
3155©?+?© & addition \impl{?+?}\\
3156©?-?© & subtraction \impl{?-?}\\
3157©?<<?© & left shift \impl{?<<?}\\
3158©?>>?© & right shift \impl{?>>?}\\
3159©?<?© & less than \impl{?<?}\\
3160©?<=?© & less than or equal \impl{?<=?}\\
3161©?>=?© & greater than or equal \impl{?>=?}\\
3162©?>?© & greater than \impl{?>?}\\
3163©?==?© & equality \impl{?==?}\\
3164©?!=?© & inequality \impl{?"!=?}\\
3165©?&& bitwise AND \impl{?&?}\\
3166\end{tabular}\hfil
3167\begin{tabular}[t]{ll}
3168%identifier & operation \\ \hline
3169©?^& exclusive OR \impl{?^?}\\
3170©?|?© & inclusive OR \impl{?"|?}\\
3171©?=?© & simple assignment \impl{?=?}\\
3172©?*=?© & multiplication assignment \impl{?*=?}\\
3173©?/=?© & division assignment \impl{?/=?}\\
3174©?%=?© & remainder assignment \impl{?%=?}\\
3175©?+=?© & addition assignment \impl{?+=?}\\
3176©?-=?© & subtraction assignment \impl{?-=?}\\
3177©?<<=?© & left-shift assignment \impl{?<<=?}\\
3178©?>>=?© & right-shift assignment \impl{?>>=?}\\
3179©?&=?© & bitwise AND assignment \impl{?&=?}\\
3180©?^=?© & exclusive OR assignment \impl{?^=?}\\
3181©?|=?© & inclusive OR assignment \impl{?"|=?}\\
3182\end{tabular}
3183\hfil
3184\caption{Operator Identifiers}
3185\label{opids}
3186\end{table}
3187
3188These identifiers are defined such that the question marks in the name identify the location of the operands.
3189These operands represent the parameters to the functions, and define how the operands are mapped to the function call.
3190For example, ©a + b© becomes ©?+?(a, b)©.
3191
3192In the example below, a new type, myComplex, is defined with an overloaded constructor, + operator, and string operator.
3193These operators are called using the normal C syntax.
3194
3195\begin{cfa}
3196type Complex = struct { // define a Complex type
3197        double real;
3198        double imag;
3199}
3200
3201// Constructor with default values
3202
3203void ?{}(Complex &c, double real = 0.0, double imag = 0.0) {
3204        c.real = real;
3205        c.imag = imag;
3206}
3207
3208Complex ?+?(Complex lhs, Complex rhs) {
3209        Complex sum;
3210        sum.real = lhs.real + rhs.real;
3211        sum.imag = lhs.imag + rhs.imag;
3212        return sum;
3213}
3214
3215String ()?(const Complex c) {
3216        // use the string conversions for the structure members
3217        return (String)c.real + . + . + (String)c.imag + .i.;
3218}
3219...
3220
3221Complex a, b, c = {1.0}; // constructor for c w/ default imag
3222...
3223c = a + b;
3224print(.sum = . + c);
3225\end{cfa}
3226
3227
3228\section{Auto Type-Inferencing}
3229
3230Auto type-inferencing occurs in a declaration where a variable's type is inferred from its initialization expression type.
3231\begin{quote2}
3232\begin{tabular}{@{}l@{\hspace{3em}}ll@{}}
3233\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CC}} & \multicolumn{1}{c}{\textbf{\Indexc{gcc}}} \\
3234\begin{cfa}
3235
3236auto j = 3.0 * 4;
3237int i;
3238auto k = i;
3239\end{cfa}
3240&
3241\begin{cfa}
3242#define expr 3.0 * i
3243typeof(expr) j = expr;
3244int i;
3245typeof(i) k = i;
3246\end{cfa}
3247&
3248\begin{cfa}
3249
3250// use type of initialization expression
3251
3252// use type of primary variable
3253\end{cfa}
3254\end{tabular}
3255\end{quote2}
3256The two important capabilities are:
3257\begin{itemize}
3258\item
3259preventing having to determine or write out long generic types,
3260\item
3261ensure secondary variables, related to a primary variable, always have the same type.
3262\end{itemize}
3263
3264In \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.
3265\Indexc{gcc} provides ©typeof© to declare a secondary variable from a primary variable.
3266\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.
3267Only for overloaded routines with the same return type is variable type-inferencing possible.
3268Finally, ©auto© presents the programming problem of tracking down a type when the type is actually needed.
3269For example, given
3270\begin{cfa}
3271auto j = ®...®
3272\end{cfa}
3273and the need to write a routine to compute using ©j©
3274\begin{cfa}
3275void rtn( ®...® parm );
3276rtn( j );
3277\end{cfa}
3278A programmer must work backwards to determine the type of ©j©'s initialization expression, reconstructing the possibly long generic type-name.
3279In this situation, having the type name or a short alias is very useful.
3280
3281There is also the conundrum in type inferencing of when to \emph{\Index{brand}} a type.
3282That is, when is the type of the variable more important than the type of its initialization expression.
3283For example, if a change is made in an initialization expression, it can cause hundreds or thousands of cascading type changes and/or errors.
3284At some point, a programmer wants the type of the variable to remain constant and the expression to be in error when it changes.
3285
3286Given ©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.
3287Should a significant need arise, this feature can be revisited.
3288
3289
3290\begin{comment}
3291\section{Generics}
3292
3293\CFA supports parametric polymorphism to allow users to define generic functions and types.
3294Generics allow programmers to use type variables in place of concrete types so that the code can be reused with multiple types.
3295The type parameters can be restricted to satisfy a set of constraints.
3296This 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.
3297
3298
3299\subsection{Generic Functions}
3300
3301Generic functions in \CFA are similar to template functions in \Index*[C++]{\CC{}}, and will sometimes be expanded into specialized versions, just like in \CC.
3302The 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.
3303This means that compiled libraries can contain generic functions that can be used by programs linked with them (statically or dynamically).
3304Another advantage over \CC templates is unlike templates, generic functions are statically checked, even without being instantiated.
3305
3306A simple example of using Do.s parametric polymorphism to create a generic swap function would look like this:
3307
3308\begin{cfa}
3309generic(type T)
3310void swap(T &a, T &b) {
3311        T tmp = a;
3312        a = b;
3313        b = a;
3314}
3315
3316int a, b;
3317swap(a, b);
3318
3319Point p1, p2;
3320swap(p1, p2);
3321\end{cfa}
3322
3323Here, instead of specifying types for the parameters a and b, the function has a generic type parameter, type T.
3324This 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.
3325
3326
3327\subsection{Bounded Quantification}
3328
3329Some generic functions only work (or make sense) for any type that satisfies a given property.
3330For example, here is a function to pick the minimum of two values of some type.
3331\begin{cfa}
3332generic (type T | bool ?<?(T, T) )
3333
3334T min( T a, T b ) {
3335        return a < b ? a : b;
3336}
3337\end{cfa}
3338
3339It 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.
3340The ordering function used here is the less than operator, <.
3341The syntax used to reference the operator is discussed in further detail in Operator Overloading.
3342In \CFA, this assertion on the type of a generic is written as the bound, (type T | bool ?<?(T, T)).
3343The \CFA compiler enforces that minis only called with types for which the less than operator is defined, and reports a compile-time error otherwise.
3344
3345Bounds can also involve multiple types, and multiple requirements, as shown below:
3346\begin{cfa}
3347generic (type T, type U | { T foo(T, U); U bar(U); })
3348
3349T baz(T t, U u) {
3350        return foo(t, bar(u));
3351}
3352\end{cfa}
3353
3354
3355\subsection{Interfaces}
3356
3357Type bounds as shown above are not very informative, merely requiring that a function exists with the right name and type.
3358Suppose you try to call a polymorphic function and \CFA gives you an error that int combine(int, int) is not defined.
3359Can 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.
3360The function signature doesn't say.
3361
3362Interfaces gather together a set of function signatures under a common name, which solves two problems.
3363First, an interface name can be used in type bounds instead of function signatures.
3364This avoids repetition when a bound is used in many functions.
3365Second, interfaces explicitly document the existence of a commonly used set of functionality, making programs easier to understand.
3366\begin{cfa}
3367generic (type T)
3368interface Orderable {
3369        bool ?<?(T, T);
3370};
3371
3372generic (type T | Orderable(T))
3373T min( T a, T b ) {
3374        return a < b ? a : b;
3375}
3376\end{cfa}
3377
3378This definition of the interface Orderable makes the generic function min easier to read and understand.
3379Orderable can also be reused for other generic functions, max for example.
3380Interfaces can also build on top of other interfaces.
3381For example:
3382\begin{cfa}
3383generic (type T | Orderable(T)
3384interface FooBarable {
3385        int foo(T, T);
3386        int Bar(T, T);
3387};
3388\end{cfa}
3389
3390The FooBarable interface specifies all of the bounds of the Orderable interface, plus the additional bounds specified in its definition.
3391A type does not need to specify that it satisfies any interface, the compiler can figure this out at compile time.
3392For 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.
3393
3394
3395\subsection{Generic Typedefs}
3396
3397Type synonyms can be defined generically using the typedef keyword together with a generic type annotation.
3398These can be used to abbreviate complicated type expressions, especially in generic code.
3399\begin{cfa}
3400// typedef the generic function pointers for later use
3401
3402generic(type T)
3403typedef int (*predicate)(T);
3404generic(type Captured, type T)
3405typedef void (*callback)(Captured, T);
3406
3407generic(type T)
3408void find(int length, T *array,
3409        predicate(T) p, callback(void *, T)f) {
3410        int i;
3411        for (i = 0; i < length; i++)
3412        if (p(array[i])) f(NULL, array[i]);
3413}
3414\end{cfa}
3415
3416
3417\subsection{Generic Types}
3418
3419Generic types are defined using the same mechanisms as those described above for generic functions.
3420This 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{}}.
3421For 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.
3422In C, something like this would have to be done using void pointers and unsafe casting.
3423As 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.
3424This means that a \CFA generic type from a compiled library can be used with any type that satisfies the bounds.
3425
3426The syntax for defining a generic type looks very similar to that of a generic function.
3427Generic types support bounds and interfaces, using the same syntax as generic functions.
3428\begin{cfa}
3429generic (type T)
3430struct LinkedListElem {
3431        T elem;
3432        LinkedListElem(T) *next;
3433};
3434
3435LinkedListElem *++?(LinkedListElem **elem) {
3436        return *elem = elem->next;
3437}
3438
3439generic (type T)
3440struct LinkedList {
3441        LinkedListElem(T) *head;
3442        unsigned int size;
3443}
3444
3445generic (type T | bool ?==?(T, T))
3446bool contains(LinkedList(T) *list, T elem) {
3447        for(LinkedListElem *iter = list->head; iter != 0; ++iter) {
3448        if (iter->elem == elem) return true;
3449        }
3450        return false;
3451}
3452\end{cfa}
3453
3454
3455\section{Safety}
3456
3457Safety, along with productivity, is a key goal of Do.
3458This section discusses the safety features that have been included in \CFA to help programmers create more stable, reliable, and secure code.
3459
3460
3461\subsection{Exceptions}
3462
3463\CFA introduces support for exceptions as an easier way to recover from exceptional conditions that may be detected within a block of code.
3464In C, developers can use error codes and special return values to report to a caller that an error occurred in a function.
3465The major problem with error codes is that they can be easily ignored by the caller.
3466Failure 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.
3467An unhandled exception on the other hand will cause a crash, revealing the original source of the erroneous state.
3468
3469Exceptions in \CFA allow a different type of control flow.
3470Throwing 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.
3471The exception is immediately re-thrown from the parent block unless it is caught as described below.
3472\CFA uses keywords similar to \Index*[C++]{\CC{}} for exception handling.
3473An exception is thrown using a throw statement, which accepts one argument.
3474
3475\begin{cfa}
3476        ...
3477
3478        throw 13;
3479
3480        ...
3481\end{cfa}
3482
3483An exception can be caught using a catch statement, which specifies the type of the exception it can catch.
3484A catch is specified immediately after a guarded block to signify that it can catch an exception from that block.
3485A guarded block is specified using the try keyword, followed by a block of code inside of curly braces.
3486
3487\begin{cfa}
3488        ...
3489
3490        try {
3491                throw 13;
3492        }
3493        catch(int e) {
3494                printf(.caught an exception: %d\n., e);
3495        }
3496\end{cfa}
3497\end{comment}
3498
3499
3500\subsection{Memory Management}
3501
3502
3503\subsubsection{Manual Memory Management}
3504
3505Using malloc and free to dynamically allocate memory exposes several potential, and common, errors.
3506First, malloc breaks type safety because it returns a pointer to void.
3507There is no relationship between the type that the returned pointer is cast to, and the amount of memory allocated.
3508This problem is solved with a type-safe malloc.
3509Do.s type-safe malloc does not take any arguments for size.
3510Instead, it infers the type based on the return value, and then allocates space for the inferred type.
3511
3512\begin{cfa}
3513float *f = malloc(); // allocates the size of a float
3514
3515struct S {
3516        int i, j, k;
3517};
3518
3519struct S *s = malloc(); // allocates the size of a struct S
3520\end{cfa}
3521
3522In addition to the improved malloc, \CFA also provides a technique for combining allocation and initialization into one step, using the new function.
3523For all constructors defined for a given type (see Operator Overloading), a corresponding call to new can be used to allocate and construct that type.
3524
3525\begin{cfa}
3526type Complex = struct {
3527        float real;
3528        float imag;
3529};
3530
3531// default constructor
3532
3533void ?{}(Complex &c) {
3534        c.real = 0.0;
3535        c.imag = 0.0;
3536}
3537
3538
3539
3540// 2 parameter constructor
3541
3542void ?{}(Complex &c, float real, float imag) {
3543        c.real = real;
3544        c.imag = imag;
3545}
3546
3547
3548int main() {
3549        Complex c1; // No constructor is called
3550        Complex c2{}; // Default constructor called
3551        Complex c3{1.0, -1.0}; // 2 parameter constructor is called
3552
3553        Complex *p1 = malloc(); // allocate
3554        Complex *p2 = new(); // allocate + default constructor
3555        Complex *p3 = new(0.5, 1.0); // allocate + 2 param constructor
3556}
3557\end{cfa}
3558
3559
3560\subsubsection{Automatic Memory Management}
3561
3562\CFA may also support automatic memory management to further improve safety.
3563If the compiler can insert all of the code needed to manage dynamically allocated memory (automatic reference counting), then developers can avoid problems with dangling pointers, double frees, memory leaks, etc.
3564This feature requires further investigation.
3565\CFA will not have a garbage collector, but might use some kind of region-based memory management.
3566
3567
3568\begin{comment}
3569\subsection{Unsafe C Constructs}
3570
3571C programmers are able to access all of the low-level tricks that are sometimes needed for close-to-the-hardware programming.
3572Some of these practices however are often error-prone and difficult to read and maintain.
3573Since \CFA is designed to be safer than C, such constructs are disallowed in \CFA code.
3574If a programmer wants to use one of these unsafe C constructs, the unsafe code must be contained in a C linkage block (see Interoperability), which will be compiled like C code.
3575This block means that the user is telling the tools, .I know this is unsafe, but I.m going to do it anyway..
3576
3577The exact set of unsafe C constructs that will be disallowed in \CFA has not yet been decided, but is sure to include pointer arithmetic, pointer casting, etc.
3578Once the full set is decided, the rules will be listed here.
3579\end{comment}
3580
3581
3582\section{Concurrency}
3583
3584Concurrency support in \CFA is implemented on top of a highly efficient runtime system of light-weight, M:N, user level threads.
3585The model integrates concurrency features into the language by making the structure type the core unit of concurrency.
3586All communication occurs through method calls, where data is sent via method arguments, and received via the return value.
3587This enables a very familiar interface to all programmers, even those with no parallel programming experience.
3588It also allows the compiler to do static type checking of all communication, a very important safety feature.
3589This 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.
3590Mutex objects, monitors, are used to contain mutual exclusion within an object and synchronization across concurrent threads.
3591
3592\begin{figure}
3593\begin{cfa}
3594#include <fstream>
3595#include <coroutine>
3596
3597coroutine Fibonacci {
3598        int fn;                                                         §\C{// used for communication}§
3599};
3600void ?{}( Fibonacci * this ) {
3601        this->fn = 0;
3602}
3603void main( Fibonacci * this ) {
3604        int fn1, fn2;                                           §\C{// retained between resumes}§
3605        this->fn = 0;                                           §\C{// case 0}§
3606        fn1 = this->fn;
3607        suspend();                                                      §\C{// return to last resume}§
3608
3609        this->fn = 1;                                           §\C{// case 1}§
3610        fn2 = fn1;
3611        fn1 = this->fn;
3612        suspend();                                                      §\C{// return to last resume}§
3613
3614        for ( ;; ) {                                            §\C{// general case}§
3615                this->fn = fn1 + fn2;
3616                fn2 = fn1;
3617                fn1 = this->fn;
3618                suspend();                                              §\C{// return to last resume}§
3619        } // for
3620}
3621int next( Fibonacci * this ) {
3622        resume( this );                                         §\C{// transfer to last suspend}§
3623        return this->fn;
3624}
3625int main() {
3626        Fibonacci f1, f2;
3627        for ( int i = 1; i <= 10; i += 1 ) {
3628                sout | next( &f1 ) | ' ' | next( &f2 ) | endl;
3629        } // for
3630}
3631\end{cfa}
3632\caption{Fibonacci Coroutine}
3633\label{f:FibonacciCoroutine}
3634\end{figure}
3635
3636
3637\subsection{Coroutine}
3638
3639\Index{Coroutines} are the precursor to tasks.
3640\VRef[Figure]{f:FibonacciCoroutine} shows a coroutine that computes the \Index*{Fibonacci} numbers.
3641
3642
3643\subsection{Monitors}
3644
3645A monitor is a structure in \CFA which includes implicit locking of its fields.
3646Users of a monitor interact with it just like any structure, but the compiler handles code as needed to ensure mutual exclusion.
3647An example of the definition of a monitor is shown here:
3648\begin{cfa}
3649type Account = monitor {
3650        const unsigned long number; // account number
3651        float balance; // account balance
3652};
3653\end{cfa}
3654
3655\begin{figure}
3656\begin{cfa}
3657#include <fstream>
3658#include <kernel>
3659#include <monitor>
3660#include <thread>
3661
3662monitor global_t {
3663        int value;
3664};
3665
3666void ?{}(global_t * this) {
3667        this->value = 0;
3668}
3669
3670static global_t global;
3671
3672void increment3( global_t * mutex this ) {
3673        this->value += 1;
3674}
3675void increment2( global_t * mutex this ) {
3676        increment3( this );
3677}
3678void increment( global_t * mutex this ) {
3679        increment2( this );
3680}
3681
3682thread MyThread {};
3683
3684void main( MyThread* this ) {
3685        for(int i = 0; i < 1_000_000; i++) {
3686                increment( &global );
3687        }
3688}
3689int main(int argc, char* argv[]) {
3690        processor p;
3691        {
3692                MyThread f[4];
3693        }
3694        sout | global.value | endl;
3695}
3696\end{cfa}
3697\caption{Atomic-Counter Monitor}
3698\caption{f:AtomicCounterMonitor}
3699\end{figure}
3700
3701\begin{comment}
3702Since a monitor structure includes an implicit locking mechanism, it does not make sense to copy a monitor;
3703it is always passed by reference.
3704Users can specify to the compiler whether or not a function will require mutual exclusion of the monitor using the mutex modifier on the parameter.
3705When mutex is specified, the compiler inserts locking before executing the body of the function, and unlocking after the body.
3706This means that a function requiring mutual exclusion could block if the lock is already held by another thread.
3707Blocking 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.
3708If multiple mutex parameters are specified, they will be locked in parameter order (\ie first parameter is locked first) and unlocked in the
3709reverse order.
3710\begin{cfa}
3711// This function accesses a constant field, it does not require
3712// mutual exclusion
3713
3714export unsigned long getAccountNumber(Account &a) {
3715        return a.number;
3716}
3717
3718// This function accesses and modifies a shared field; it
3719// requires mutual exclusion
3720
3721export float withdrawal(mutex Account &a, float amount) {
3722        a.balance -= amount;
3723        return a.balance;
3724}
3725\end{cfa}
3726
3727Often, one function using a monitor will call another function using that same monitor.
3728If both require mutual exclusion, then the thread would be waiting for itself to release the lock when it calls the inner function.
3729This 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.
3730It will still be unlocked the same number of times.
3731An example of this situation is shown below:
3732
3733\begin{cfa}
3734// deleting a job from a worker requires mutual exclusion
3735
3736void deleteJob(mutex Worker &w, Job &j) {
3737        ...
3738}
3739
3740// transferring requires mutual exclusion and calls deleteJob
3741
3742void transferJob(mutex Worker &from, Worker &to) {
3743        ...
3744        deleteJob(j);
3745        ...
3746}
3747\end{cfa}
3748\end{comment}
3749
3750
3751\subsection{Tasks}
3752
3753\CFA also provides a simple mechanism for creating and utilizing user level threads.
3754A task provides mutual exclusion like a monitor, and also has its own execution state and a thread of control.
3755Similar to a monitor, a task is defined like a structure:
3756
3757\begin{figure}
3758\begin{cfa}
3759#include <fstream>
3760#include <kernel>
3761#include <stdlib>
3762#include <thread>
3763
3764thread First  { signal_once * lock; };
3765thread Second { signal_once * lock; };
3766
3767void ?{}( First * this, signal_once* lock ) { this->lock = lock; }
3768void ?{}( Second * this, signal_once* lock ) { this->lock = lock; }
3769
3770void main( First * this ) {
3771        for ( int i = 0; i < 10; i += 1 ) {
3772                sout | "First : Suspend No." | i + 1 | endl;
3773                yield();
3774        }
3775        signal( this->lock );
3776}
3777
3778void main( Second * this ) {
3779        wait( this->lock );
3780        for ( int i = 0; i < 10; i += 1 ) {
3781                sout | "Second : Suspend No." | i + 1 | endl;
3782                yield();
3783        }
3784}
3785
3786int main( void ) {
3787        signal_once lock;
3788        sout | "User main begin" | endl;
3789        {
3790                processor p;
3791                {
3792                        First  f = { &lock };
3793                        Second s = { &lock };
3794                }
3795        }
3796        sout | "User main end" | endl;
3797}
3798\end{cfa}
3799\caption{Simple Tasks}
3800\label{f:SimpleTasks}
3801\end{figure}
3802
3803
3804\begin{comment}
3805\begin{cfa}
3806type Adder = task {
3807        int *row;
3808        int size;
3809        int &subtotal;
3810}
3811\end{cfa}
3812
3813A task may define a constructor, which will be called upon allocation and run on the caller.s thread.
3814A destructor may also be defined, which is called at deallocation (when a dynamic object is deleted or when a local object goes out of scope).
3815After a task is allocated and initialized, its thread is spawned implicitly and begins executing in its function call method.
3816All tasks must define this function call method, with a void return value and no additional parameters, or the compiler will report an error.
3817Below are example functions for the above Adder task, and its usage to sum up a matrix on multiple threads.
3818(Note that this example is designed to display the syntax and functionality, not the best method to solve this problem)
3819\begin{cfa}
3820void ?{}(Adder &a, int r[], int s, int &st) { // constructor
3821        a.row = r;
3822        a.size = s;
3823        a.subtotal = st;
3824}
3825
3826// implicitly spawn thread and begin execution here
3827
3828void ?()(Adder &a) {
3829        int c;
3830        subtotal = 0;
3831        for (c=0; c<a.size; ++c) {
3832        subtotal += row[c];
3833        }
3834}
3835
3836int main() {
3837        const int rows = 100, cols = 1000000;
3838        int matrix[rows][cols];
3839        int subtotals[rows];
3840        int total = 0;
3841        int r;
3842
3843        { // create a new scope here for our adders
3844        Adder adders[rows];
3845        // read in the matrix
3846        ...
3847        for (r=0; r<rows; ++r) {
3848        // tasks are initialized on this thread
3849        Adders[r] = {matrix[r], cols, subtotals[r]};
3850        Adders[r](); // spawn thread and begin execution
3851        }
3852        } // adders go out of scope; block here until they all finish
3853        total += subtotals[r];
3854        printf(.total is %d\n., total);
3855}
3856\end{cfa}
3857
3858\subsection{Cooperative Scheduling}
3859
3860Tasks in \CFA are cooperatively scheduled, meaning that a task will not be interrupted by another task, except at specific yield points.
3861In Listing 31, there are no yield points, so each task runs to completion with no interruptions.
3862Places where a task could yield include waiting for a lock (explicitly or implicitly), waiting for I/O, or waiting for a specific function (or one of a set of functions) to be called.
3863This last option is introduced with the yield function. yield is used to indicate that this task should yield its thread until the specified function is called.
3864For example, the code below defines a monitor that maintains a generic list.
3865When a task tries to pop from the list, but it is empty, the task should yield until another task puts something into the list, with the push function.
3866Similarly, when a task tries to push something onto the list, but it is full, it will yield until another task frees some space with the pop function.
3867
3868\begin{cfa}
3869// type T is used as a generic type for all definitions inside
3870// the curly brackets
3871
3872generic(type T) {
3873        type Channel = monitor {
3874        List(T) list; // list is a simple generic list type
3875        };
3876
3877        T pop(mutex &Channel(T) ch) {
3878        if (ch.list.empty()) {
3879        // yield until push is called for this channel
3880        yield(push);
3881        }
3882        return ch.list.pop();
3883        }
3884
3885        void push(mutex &Channel(T)ch, T val) {
3886        if (ch.list.full()) {
3887        // yield until pop is called for this channel
3888        yield(pop);
3889        }
3890        ch.list.push(val);
3891        }
3892}
3893\end{cfa}
3894
3895A task can also yield indefinitely by calling yield with no arguments.
3896This will tell the scheduler to yield this task until it is resumed by some other task.
3897A task can resume another task by using its functional call operator.
3898The code below shows a simple ping-pong example, where two tasks yield back and forth to each other using these methods.
3899
3900\begin{cfa}
3901type Ping = task {
3902        Pong *partner;
3903};
3904
3905void ?{}(Ping &p, Pong *partner = 0) {
3906        p.partner = partner;
3907}
3908
3909void ?()(Ping &p) {
3910        for(;;) { // loop forever
3911        printf(.ping\n.);
3912        partner(); // resumes the partner task
3913        yield(); // yields this task
3914        }
3915}
3916
3917type Pong = task {
3918        Ping *partner;
3919};
3920
3921void ?{}(Pong &p, Ping *partner = 0) {
3922        p.partner = partner;
3923}
3924
3925void ?()(Pong &p) {
3926        for(;;) { // loop forever
3927        yield(); // yields this task
3928        printf(.pong/n.);
3929        partner(); // resumes the partner task
3930        }
3931}
3932
3933void main() {
3934        Ping ping; // allocate ping
3935        Pong pong{ping}; // allocate, initialize, and start pong
3936        Ping{pong}; // initialize and start ping
3937}
3938\end{cfa}
3939
3940The same functionality can be accomplished by providing functions to be called by the partner task.
3941\begin{cfa}
3942type Pingpong = task {
3943        String msg;
3944        Pingpong *partner;
3945};
3946
3947void ?{}(Pingpong &p, String msg, Pingpong *partner = 0) {
3948        p.msg = msg;
3949        p.partner = partner;
3950}
3951
3952void ?()(Pingpong &p) {
3953        for(;;) {
3954        yield(go);
3955        }
3956}
3957
3958void go(Pingpong &p) {
3959        print(.%(p.msg)\n.);
3960        go(p.partner);
3961}
3962
3963void main() {
3964        Pingpong ping = {.ping.};
3965        Pingpong pong = {.pong., ping};
3966        ping.partner = pong;
3967        go(ping);
3968}
3969\end{cfa}
3970\end{comment}
3971
3972
3973\begin{comment}
3974\section{Modules and Packages }
3975
3976High-level encapsulation is useful for organizing code into reusable units, and accelerating compilation speed.
3977\CFA provides a convenient mechanism for creating, building and sharing groups of functionality that enhances productivity and improves compile time.
3978
3979There are two levels of encapsulation in \CFA, module and package.
3980A 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}.
3981A module forms a namespace to limit the visibility and prevent naming conflicts of variables.
3982Furthermore, a module is an independent translation unit, which can be compiled separately to accelerate the compilation speed.
3983
3984A package is a physical grouping of one or more modules that is used for code distribution and version management.
3985Package is also the level of granularity at which dependences are managed.
3986A package is similar to the Crate in \Index*{Rust}.
3987
3988
3989\subsection{No Declarations, No Header Files}
3990
3991In 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.
3992Header files and a preprocessor are normally used to avoid repeating code.
3993Thus, many variables, functions, and types are described twice, which exposes an opportunity for errors and causes additional maintenance work.
3994Instead of following this model, the \CFA tools can extract all of the same information from the code automatically.
3995This 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.
3996In 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.
3997This 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.
3998
3999In \CFA, multiple definitions are not necessary.
4000Within a module, all of the module's global definitions are visible throughout the module.
4001For example, the following code compiles, even though ©isOdd© was not declared before being called:
4002\begin{cfa}
4003bool isEven(unsigned int x) {
4004        if (x == 0) return true;
4005        else return !isOdd(x);
4006}
4007
4008bool isOdd(unsigned int x) {
4009        if (x == 1) return true;
4010        else return !isEven(x - 2);
4011}
4012\end{cfa}
4013
4014Header files in C are used to expose the declarations from a library, so that they can be used externally.
4015With \CFA, this functionality is replaced with module exports, discussed below.
4016When 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.
4017
4018In 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 Interoperability for more information).
4019
4020
4021\subsection{Modules}
4022
4023A 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.
4024These modules can then be easily shared and reused in multiple projects.
4025As modules are intended to be distributed for reuse, they should generally have stable, well-defined interfaces.
4026
4027\CFA adds the following keywords to express the module systems: module, export, import, as.
4028
4029
4030\subsubsection{Module Declaration}
4031
4032The syntax to declare a module is module moduleName;.
4033
4034The module declaration must be at the beginning of a file, and each file can only belong to one module.
4035If there is no module declaration at the beginning of a file, the file belongs to the global module.
4036A module can span several files.
4037By convention, a module and the files belonging to the module have additional mapping relationship which is described in the Do-Lang Tooling documentation.
4038
4039The moduleName follows the same rules of a variable name, except that it can use slash "/" to indicate the module/sub-module relationship.
4040For example, container/vector is a valid module name, where container is the parent module name, and vector is the sub-module under container.
4041
4042Only the interfaces of a module are visible from outside, when the module is imported. export is a type decorator to declare a module interface.
4043A method, a global variable or a type can be declared as a module interface.
4044Types defined in a module and referenced by an exported function or a variable must be exported, too.
4045
4046The following code is a simple module declaration example.
4047\begin{cfa}
4048module M;
4049
4050//visible outside module M
4051
4052export int f(int i) { return i + 1; }
4053export double aCounter;
4054
4055//not visible outside module M
4056
4057int g(int i) { return i - 1; }
4058
4059double bCounter;
4060\end{cfa}
4061
4062export module moduleName; can be use to re-export all the visible (exported) names in moduleName from the current module.
4063
4064
4065\subsubsection{Module Import}
4066
4067The syntax to import a module is import moduleName; or import moduleName as anotherName;.
4068One package cannot be imported with both of the two types of syntax in one file.
4069A package imported in one file will only be visible in this file.
4070For example, two files, A and B belong to the same module.
4071If file A imports another module, M, the exported names in M are not visible in file B.
4072
4073All of the exported names are visible in the file that imports the module.
4074The exported names can be accessed within a namespace based on the module name in the first syntax (ex moduleName.foo).
4075If 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(...);).
4076The 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.
4077Conflicts in namespaces will be reported by the compiler.
4078The second method can be used to solve conflicting name problems.
4079The following code snippets show the two situations.
4080
4081\begin{cfa}
4082module util/counter;
4083export int f(int i) { return i+1; }
4084
4085import util/counter;
4086
4087int main() {
4088        return counter.f(200); // f() from the package counter
4089}
4090
4091import util/counter as ct;
4092int main() {
4093        return ct.f(200); // f() from the package counter
4094}
4095\end{cfa}
4096
4097
4098Additionally, 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.
4099
4100\begin{cfa}
4101module M1;
4102export int f(int i) { return i+1;} // visible outside
4103
4104int g(int i) { return i-1;} // not visible outside
4105
4106module M2;
4107int f(int i) { return i * 2; } // not visible outside
4108export int g(int g) { return i / 2; } // visible outside
4109
4110import M1 as .;
4111
4112import M2 as .;
4113
4114
4115int main() {
4116        return f(3) + g(4); //f() from M1 and g() from M2;
4117}
4118\end{cfa}
4119
4120
4121\subsubsection{Sub-Module and Module Aggregation}
4122
4123Several modules can be organized in a parent module and sub-modules relationship.
4124The sub-module names are based on hierarchical naming, and use slash, "/", to indicate the relationship.
4125For example, std/vector and std/io are sub-modules of module std.
4126The 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
4127not implicitly exported in the parent module.
4128
4129Aggregation is a mechanism to support components and simplified importing.
4130The mechanism is not based on naming but based on manual declaration.
4131For example, the following is the aggregated sequence module.
4132The export {...} is syntactic sugar for many lines of export module aModule;.
4133If an aggregated module is imported, all the included modules in the aggregation are imported.
4134
4135\begin{cfa}
4136module std/sequence;
4137
4138export {
4139        module std/vector;
4140        module std/list;
4141        module std/array;
4142        module std/deque;
4143        module std/forward_list;
4144        module std/queue;
4145        module std/stack;
4146};
4147\end{cfa}
4148
4149After importing the aggregated module, each individual name is still contained in the original name space.
4150For 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.
4151
4152
4153\subsubsection{Import from Repository}
4154
4155When 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).
4156The tools also support retrieving modules of a package from external repositories.
4157See Listing 40: Package directory structure
4158
4159
4160\subsubsection{Package Import}
4161
4162Because 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.
4163In 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;
4164or 2) Adding the package dependence into the current project's Do.prj.
4165More details about locating a module in a package are explained in the next section.
4166
4167
4168\subsubsection{Package Versioning}
4169
4170A package must have a version number.
4171The version number is a string.
4172For example "1.0", "1.a", "A1", and "1ec5fab753eb979d3886a491845b8ae152d58c8f" are all valid version numbers.
4173By convention, a package is stored in a directory named packageName-packageVersion.
4174For example, the util package with version 1.1 is stored in a directory named util-1.1.
4175
4176The project description file can optionally specify the version of the package used in the current project.
4177If 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.
4178The builder tool will record the specific package version used in the build in the project's "Do.lock" file to enable fully repeatable builds.
4179
4180
4181\subsection{Module and Package Organization}
4182
4183\CFA has two level of encapsulations, module and package.
4184This section explains the object model of modules, packages and other language concepts.
4185It also explains how programmers should organize their code, and the method used by the build tools to locate packages, and import modules for compilation.
4186
4187
4188\subsubsection{Object Model}
4189
4190There are several concepts in Do.
4191\begin{itemize}
4192\item
4193File: a \CFA source file
4194\item
4195Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
4196\item
4197Package: a container to organize modules for distribution; It has attributes like name, author,
4198version, dependences, etc.
4199\item
4200Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
4201\end{itemize}
4202
4203The following rules summarize the object model of all the above concepts:
4204\begin{itemize}
4205\item
4206A module contains one or more files
4207\begin{itemize}
4208\item
4209One file can only belong to one module
4210\item
4211A module has its name and interfaces exported
4212\item
4213A file without a module declaration at the beginning belongs to the global module
4214\item
4215\end{itemize}
4216
4217\item
4218A package contains one or more modules
4219\begin{itemize}
4220\item
4221A package has additional meta info described in Do.prj file
4222\item
4223A package may be dependent on other packages.
4224\end{itemize}
4225
4226\item
4227A project contains one or more modules in its source code
4228\begin{itemize}
4229\item
4230A project has additional meta info described in Do.prj file
4231\item
4232A project may be dependent on other packages
4233\item
4234A project can be transformed into a package for distribution
4235\item
4236A project can generate one or more executable binaries
4237\end{itemize}
4238\end{itemize}
4239
4240
4241\subsubsection{Module File Organization}
4242
4243The rules of this section are the conventions to organize module files in one package.
4244
4245The file location of a module in a package must match the module/submodule naming hierarchy.
4246The names separated by slash "/" must match the directory levels.
4247If only one file is used to implement one module, there is no need to put the module implementation file inside a sub-directory.
4248The file can be put inside its parent module's sub-directory with the sub module's name as the file name.
4249
4250Here is an example of a package, util.
4251\begin{cfa}
4252+ util
4253Do.prj #package description file
4254        heap.do #Case 1: module heap;
4255        list.do #Case 1: mdoule list;
4256        ring.do #Case 1: module ring;
4257        + string #Case 2
4258        impl1.do #module string;
4259        + std
4260        vector.do
4261        list.do
4262        + array #Case 3
4263        array1.do #module std/array;
4264        array2.do #module std/array;
4265        sequence.do #Case 4, module std/sequence;
4266        test.do #Case 5
4267\end{cfa}
4268
4269\begin{itemize}
4270\item
4271Case 1: Each individual file implements a module
4272\item
4273Case 2: Put the implementation of a module under the sub-directory, but there is only one file
4274\item
4275Case 3: Put the implementation of a module under the sub-directory; There are several files to
4276implement one module
4277\item
4278Case 4: One file to express one aggregation
4279\item
4280Case 5: The file does not belong to any module; It is used for testing purpose
4281\end{itemize}
4282
4283The example only uses source code, ".do" files, to show the module file organization.
4284Other module packaging formats, like binary, must also follow the same rules.
4285
4286
4287\subsection{Module File Format}
4288
4289\CFA supports different types of module file formats.
4290
4291\begin{itemize}
4292\item
4293Pure source code format: The files should be organized following the previous section's definition.
4294\item
4295IR format (TBD): The \CFA compiler IR format, similar to the source code format
4296\item
4297Binary format, including ".a" static library or ".so" dynamic linkage library
4298\begin{itemize}
4299\item
4300The file's name must match the right level's module name defined in the previous section
4301\item
4302E.g. "util.so" includes all modules for the package util.
4303\item
4304E.g. "string.so" under the package directory to include files belonging to "module string;"
4305\end{itemize}
4306\item.
4307Archive format
4308\begin{itemize}
4309\item
4310The archive is named as ".dar", and is a zip archive of the source code or the binary for a package
4311\item
4312E.g. "util.dar" is the whole package for util package including the package direction file
4313\end{itemize}
4314\item
4315Hybrid format
4316\begin{itemize}
4317\item
4318A package can be distributed partly in source code, partly in binary format, and/or packaged in the archive format
4319\item
4320The only limitation is that the names of the files must match the module location names defined in previous section
4321\end{itemize}
4322\end{itemize}
4323Package and Module Locating and the \CFA Language Tooling documentation for more details.
4324
4325
4326\subsection{Packages}
4327
4328A package is synonymous with a library in other languages.
4329The intent of the package level encapsulation is to facilitate code distribution, version control, and dependence management.
4330A package is a physical grouping of one or more modules in a directory (an archive file for a directory).
4331The 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.
4332
4333
4334\subsubsection{Package Definition}
4335
4336A package is defined by putting a project description file, Do.prj, with one or more modules into a directory.
4337This project description file contains the package's meta data, including package name, author, version, dependences, etc.
4338It should be in the root of the package directory.
4339
4340The modules in the package could be either source code, or compiled binary format.
4341The location of the module files should follow the module name's path.
4342
4343Here is a simple example of the directory structure of a package, core.
4344It contains a module std and several sub-modules under std.
4345\begin{cfa}
4346+ core
4347        Do.prj
4348        + std
4349        + io
4350        file.do # module std/io/file;
4351        network.do #module std/io/network;
4352        + container
4353        vector.do #module std/container/vector;
4354        list.do #module std/container/list;
4355\end{cfa}
4356
4357
4358\subsubsection{Package Import}
4359
4360Because 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.
4361In 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.
4362More details about locating a module in a package are explained in the next section.
4363
4364
4365\subsubsection{Package Versioning}
4366
4367A package must have a version number.
4368The version number is a string.
4369For example "1.0", "1.a", "A1", and "1ec5fab753eb979d3886a491845b8ae152d58c8f" are all valid version numbers.
4370By convention, a package is stored in a directory named packageName-packageVersion.
4371For example, the util package with version 1.1 is stored in a directory named util-1.1.
4372
4373The project description file can optionally specify the version of the package used in the current project.
4374If 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.
4375The builder tool will record the specific package version used in the build in the project's "Do.lock" file to enable fully repeatable builds.
4376
4377
4378\subsection{Module and Package Organization}
4379
4380\CFA has two level of encapsulations, module and package.
4381This section explains the object model of modules, packages and other language concepts.
4382It also explains how programmers should organize their code, and the method used by the build tools to locate packages, and import modules for compilation.
4383
4384
4385\subsubsection{Object Model}
4386
4387There are several concepts in Do.
4388\begin{itemize}
4389\item
4390File: a \CFA source file
4391\item
4392Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
4393\item
4394Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, etc.
4395\item
4396Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
4397\end{itemize}
4398
4399The following rules summarize the object model of all the above concepts:
4400\begin{itemize}
4401\item
4402A module contains one or more files
4403\begin{itemize}
4404\item
4405One file can only belong to one module
4406\item
4407A module has its name and interfaces exported
4408\item
4409A file without a module declaration at the beginning belongs to the global module
4410\end{itemize}
4411\item
4412A package contains one or more modules
4413\begin{itemize}
4414\item
4415A package has additional meta info described in Do.prj file
4416\item
4417A package may be dependent on other packages.
4418\end{itemize}
4419\item
4420A project contains one or more modules in its source code
4421\begin{itemize}
4422\item
4423A project has additional meta info described in Do.prj file
4424\item
4425A project may be dependent on other packages
4426\item
4427A project can be transformed into a package for distribution
4428\item
4429A project can generate one or more executable binaries
4430\end{itemize}
4431\end{itemize}
4432
4433
4434\subsubsection{Module File Organization}
4435
4436The rules of this section are the conventions to organize module files in one package.
4437
4438The file location of a module in a package must match the module/submodule naming hierarchy.
4439The names separated by slash "/" must match the directory levels.
4440If only one file is used to implement one module, there is no need to put the module implementation file inside a sub-directory.
4441The file can be put inside its parent module's sub-directory with the sub module's name as the file name.
4442
4443Here is an example of a package, util.
4444\begin{cfa}
4445+ util
4446        Do.prj #package description file
4447        heap.do #Case 1: module heap;
4448        list.do #Case 1: mdoule list;
4449        ring.do #Case 1: module ring;
4450        + string #Case 2
4451        impl1.do #module string;
4452        + std
4453        vector.do
4454        list.do
4455        + array #Case 3
4456        array1.do #module std/array;
4457        array2.do #module std/array;
4458        sequence.do #Case 4, module std/sequence;
4459        test.do #Case 5
4460\end{cfa}
4461
4462
4463\begin{itemize}
4464\item
4465Case 1: Each individual file implements a module
4466\item
4467Case 2: Put the implementation of a module under the sub-directory, but there is only one file
4468\item
4469Case 3: Put the implementation of a module under the sub-directory; There are several files to implement one module
4470\item
4471Case 4: One file to express one aggregation
4472\item
4473Case 5: The file does not belong to any module; It is used for testing purpose
4474\end{itemize}
4475
4476The example only uses source code, ".do" files, to show the module file organization.
4477Other module packaging formats, like binary, must also follow the same rules.
4478
4479
4480\subsubsection{Module File Format}
4481
4482\CFA supports different types of module file formats.
4483
4484\begin{itemize}
4485\item
4486Pure source code format: The files should be organized following the previous section's definition.
4487\item
4488IR format (TBD): The \CFA compiler IR format, similar to the source code format
4489\item
4490Binary format, including ".a" static library or ".so" dynamic linkage library
4491\begin{itemize}
4492\item
4493The file's name must match the right level's module name defined in the previous section
4494\item
4495E.g. "util.so" includes all modules for the package util.
4496\item
4497E.g. "string.so" under the package directory to include files belonging to "module string;"
4498\end{itemize}
4499\item
4500Archive format
4501\begin{itemize}
4502\item
4503The archive is named as ".dar", and is a zip archive of the source code or the binary for a package
4504\item
4505E.g. "util.dar" is the whole package for util package including the package direction file
4506\end{itemize}
4507\item
4508Hybrid format
4509\begin{itemize}
4510\item
4511A package can be distributed partly in source code, partly in binary format, and/or packaged in the archive format
4512\item
4513The only limitation is that the names of the files must match the module location names defined in previous section
4514\end{itemize}
4515\end{itemize}
4516
4517
4518\subsection{Package and Module Locating}
4519
4520The 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.
4521If a programmer prefers, one can directly call the compiler, docc to build the source files and create and link to static libraries.
4522
4523When a source file imports a module, the \CFA build tool and docc compiler will locate the module according to the following order:
4524
4525\begin{enumerate}
4526\item
4527This source file's directory tree, which is typically the project's src directory
4528\item
4529All of the dependent packages (in a directory or in an archive file) under the current \CFA project's pkg directory
4530\item
4531The dependent packages (in a directory or in an archive file) inside the paths defined in the DOPATH environment variable
4532\item
4533The dependent packages (in a directory or in an archive file) inside the global \CFA SDK installation's pkg directory
4534\item
4535If 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
4536\end{enumerate}
4537
4538The module found first in a package will shadow the modules with the same name in the later packages in the search sequence.
4539
4540
4541\subsubsection{Dependent Package}
4542
4543Dependent packages are those packages containing modules that the current project's source code will import from.
4544Dependent packages are defined implicitly or explicitly in one \CFA project.
4545All of the packages under the current project's pkg directory are implicitly dependent packages.
4546For others, the dependent packages must be defined in the project's Do.prj file.
4547
4548
4549\subsubsection{Package and Module Locating Example}
4550
4551\begin{cfa}
4552# A project's source code tree
4553
4554--------------------------------------
4555
4556+ testProject
4557        Do.prj
4558        + src
4559        main.do
4560        + pkg
4561        + security-1.1
4562        Do.prj
4563        security.do #module security
4564
4565--------------------------------------
4566
4567# Do.prj
4568
4569--------------------------------------
4570
4571[dependences]
4572std
4573util = "0.2"
4574
4575--------------------------------------
4576
4577# main.do
4578
4579---------------------------------------
4580
4581import security;
4582import std/vector;
4583import container;
4584
4585----------------------------------------
4586\end{cfa}
4587
4588
4589\begin{cfa}
4590# pkg directory's source code tree
4591
4592-----------------------------------------
4593
4594+ pkg
4595        + std-1.0
4596        Do.prj
4597        vector.do #module std/vector;
4598        queue.do #module std/queue;
4599        + std-1.1
4600        Do.prj
4601        vector.do #module std/vector;
4602        queue.do #module std/queue;
4603        list.do #module std/list;
4604        + util-0.1
4605        Do.prj
4606        container.do #module container;
4607        + security-1.0
4608        security.do #module security;
4609------------------------------------------
4610\end{cfa}
4611
4612
4613During the compiling of main.do file import security;
4614The security module appears in both the local security-1.1 package, and the global security-1.0 package.
4615According to the locating sequence, the local security module in security-1.1 will be used.
4616And because the security-1.1 package is under local's pkg directory.
4617No dependence description is required in the project Do.prj file.
4618
4619import std/vector;
4620
4621The 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.
4622
4623import container;
4624
4625The 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.
4626The builder tool then will try to retrieve it from the web and store it in the global pkg directory.
4627After that, the container module from the newly downloaded package will be used in the compilation.
4628\end{comment}
4629
4630
4631\section{Comparison with Other Languages}
4632
4633\CFA is one of many languages that attempts to improve upon C.
4634In developing \CFA, many other languages were consulted for ideas, constructs, and syntax.
4635Therefore, it is important to show how these languages each compare with Do.
4636In 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}.
4637
4638
4639\begin{comment}
4640\subsection[Comparing Key Features of CFA]{Comparing Key Features of \CFA}
4641
4642
4643{% local change to lstlising to reduce font size
4644
4645
4646\lstset{basicstyle=\linespread{0.9}\sf\relsize{-2}}
4647
4648
4649\subsubsection{Constructors and Destructors}
4650
4651\begin{flushleft}
4652\begin{tabular}{@{}l|l|l|l@{}}
4653\multicolumn{1}{c|}{\textbf{\CFA}}      & \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}      \\
4654\hline
4655\begin{cfa}
4656struct Line {
4657        float lnth;
4658}
4659// default constructor
4660void ?{}( Line * l ) {
4661        l->lnth = 0.0;
4662        sout | "default" | endl;
4663}
4664
4665
4666// constructor with length
4667void ?{}( Line * l, float lnth ) {
4668        l->lnth = lnth;
4669        sout | "lnth" | l->lnth | endl;
4670
4671}
4672
4673// destructor
4674void ^?() {
4675        sout | "destroyed" | endl;
4676        l.lnth = 0.0;
4677}
4678
4679// usage
4680Line line1;
4681Line line2 = { 3.4 };
4682\end{cfa}
4683&
4684\begin{lstlisting}[language=C++]
4685class Line {
4686        float lnth;
4687
4688        // default constructor
4689        Line() {
4690                cout << "default" << endl;
4691                lnth = 0.0;
4692        }
4693
4694
4695        // constructor with lnth
4696        Line( float l ) {
4697                cout << "length " << length
4698                         << endl;
4699                length = l;
4700        }
4701
4702        // destructor
4703        ~Line() {
4704                cout << "destroyed" << endl;
4705                length = 0.0;
4706        }
4707}
4708// usage
4709Line line1;
4710Line line2( 3.4 );
4711\end{lstlisting}
4712&
4713\begin{lstlisting}[language=Golang]
4714type Line struct {
4715        length float32
4716}
4717// default constructor
4718func makeLine() Line {
4719        fmt.PrintLn( "default" )
4720        return Line{0.0}
4721}
4722
4723
4724// constructor with length
4725func makeLine( length float32 ) Line {
4726        fmt.Printf( "length %v", length )
4727
4728        return Line{length}
4729}
4730
4731// no destructor
4732
4733
4734
4735
4736
4737// usage
4738line1 := makeLine()
4739line2 := makeLine( 3.4 )
4740\end{lstlisting}
4741&
4742\begin{cfa}
4743struct Line {
4744        length: f32
4745}
4746// default constructor
4747impl Default for Line {
4748        fn default () -> Line {
4749                println!( "default" );
4750                Line{ length: 0.0 }
4751        }
4752}
4753// constructor with length
4754impl Line {
4755        fn make( len: f32 ) -> Line {
4756                println!( "length: {}", len );
4757                Line{ length: len }
4758        }
4759}
4760// destructor
4761impl Drop for Line {
4762        fn drop( &mut self ) {
4763                self.length = 0.0
4764        }
4765}
4766// usage
4767let line1:Line = Default::default();
4768Line line2( 3.4 );
4769\end{cfa}
4770\end{tabular}
4771\end{flushleft}
4772
4773
4774\subsubsection{Operator Overloading}
4775
4776\begin{flushleft}
4777\begin{tabular}{@{}l|l|l|l@{}}
4778\multicolumn{1}{c|}{\textbf{\CFA}}      & \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}      \\
4779\hline
4780\begin{cfa}
4781struct Cpx {
4782        double re, im;
4783};
4784// overload addition operator
4785Cpx ?+?( Cpx l, const Cpx r ) {
4786        return (Cpx){l.re+l.im, l.im+r.im};
4787}
4788Cpx a, b, c;
4789c = a + b;
4790\end{cfa}
4791&
4792\begin{cfa}
4793struct Cpx {
4794        double re, im;
4795};
4796// overload addition operator
4797Cpx operator+( Cpx l, const Cpx r ) {
4798        return (Cpx){l.re+l.im, l.im+r.im};
4799}
4800Cpx a, b, c;
4801c = a + b;
4802\end{cfa}
4803&
4804\begin{cfa}
4805// no operator overloading
4806
4807
4808
4809
4810
4811
4812
4813\end{cfa}
4814&
4815\begin{cfa}
4816struct Cpx {
4817        re: f32,
4818        im: f32
4819}
4820// overload addition operator
4821impl Add for Cpx {
4822        type Output = Cpx
4823        fn add(self, r: Cpx) -> Cpx {
4824                let mut res = Cpx{re: 0.0, im: 0.0};
4825                res.re = self.re + r.re;
4826                res.im = self.im + r.im;
4827                return res
4828        }
4829}
4830let (a, b, mut c) = ...;
4831c = a + b
4832\end{cfa}
4833\end{tabular}
4834\end{flushleft}
4835
4836
4837\subsubsection{Calling C Functions}
4838
4839\begin{flushleft}
4840\begin{tabular}{@{}l|l|l@{}}
4841\multicolumn{1}{c|}{\textbf{\CFA/\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}   \\
4842\hline
4843\begin{cfa}[boxpos=t]
4844extern "C" {
4845#include <sys/types.h>
4846#include <sys/stat.h>
4847#include <unistd.h>
4848}
4849size_t fileSize( const char *path ) {
4850        struct stat s;
4851        stat(path, &s);
4852        return s.st_size;
4853}
4854\end{cfa}
4855&
4856\begin{cfa}[boxpos=t]
4857/*
4858#cgo
4859#include <sys/types.h>
4860#include <sys/stat.h>
4861#include <unistd.h>
4862*/
4863import "C"
4864import "unsafe"
4865
4866func fileSize(path string) C.size_t {
4867        var buf C.struct_stat
4868        c_string := C.CString(path)
4869        C.stat(p, &buf)
4870        C.free(unsafe.Pointer(c_string))
4871        return buf._st_size
4872}
4873\end{cfa}
4874&
4875\begin{cfa}[boxpos=t]
4876use libc::{c_int, size_t};
4877// translated from sys/stat.h
4878#[repr(C)]
4879struct stat_t {
4880        ...
4881        st_size: size_t,
4882        ...
4883}
4884#[link(name = "libc")]
4885extern {
4886        fn stat(path: *const u8,
4887        buf: *mut stat_t) -> c_int;
4888}
4889fn fileSize(path: *const u8) -> size_t
4890{
4891        unsafe {
4892                let mut buf: stat_t = uninit();
4893                stat(path, &mut buf);
4894                buf.st_size
4895        }
4896}
4897\end{cfa}
4898\end{tabular}
4899\end{flushleft}
4900
4901
4902\subsubsection{Generic Functions}
4903
4904\begin{flushleft}
4905\begin{tabular}{@{}l|l|l|l@{}}
4906\multicolumn{1}{c|}{\textbf{\CFA}}      & \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}      \\
4907\hline
4908\begin{cfa}
4909generic(type T, type N |
4910        { int ?<?(N, N); })
4911T *maximize(N (*f)(const T&),
4912        int n, T *a) {
4913        T *bestX = NULL;
4914        N bestN;
4915        for (int i = 0; i < n; i++) {
4916        N curN = f(a[i]);
4917        if (bestX == NULL ||
4918        curN > bestN) {
4919        bestX = &a[i]; bestN = curN;
4920        }
4921        }
4922        return bestX;
4923}
4924
4925string *longest(int n, string *p)
4926{
4927        return maximize(length, n, p);
4928}
4929\end{cfa}
4930&
4931\begin{cfa}
4932template<typename T, typename F>
4933T *maximize(const F &f,
4934        int n, T *a) {
4935        typedef decltype(f(a[0])) N;
4936        T *bestX = NULL;
4937        N bestN;
4938        for (int i = 0; i < n; i++) {
4939        N curN = f(a[i]);
4940        if (bestX == NULL || curN > bestN)
4941        {
4942        bestX = &a[i]; bestN = curN;
4943        }
4944        }
4945        return bestX;
4946}
4947
4948string *longest(int n, string *p) {
4949        return maximize(
4950        [](const string &s) {
4951        return s.length();
4952        }, n, p);
4953}
4954\end{cfa}
4955&
4956\begin{cfa}
4957// Go does not support generics!
4958func maximize(
4959        gt func(interface{}, interface{}) bool,
4960        f func(interface{}) interface{},
4961        a []interface{}) interface{} {
4962        var bestX interface{} = nil
4963        var bestN interface{} = nil
4964        for _, x := range a {
4965        curN := f(x)
4966        if bestX == nil || gt(curN, bestN)
4967        {
4968        bestN = curN
4969        bestX = x
4970        }
4971        }
4972        return bestX
4973}
4974
4975func longest(
4976        a []interface{}) interface{} {
4977        return maximize(
4978        func(a, b interface{}) bool {
4979        return a.(int) > b.(int) },
4980        func(s interface{}) interface{} {
4981        return len(s.(string)) },
4982        a).(string)
4983}
4984\end{cfa}
4985&
4986\begin{cfa}
4987use std::cmp::Ordering;
4988
4989fn maximize<N: Ord + Copy, T, F:
4990Fn(&T) -> N>(f: F, a: &Vec<T>) ->
4991Option<&T> {
4992        let mut best_x: Option<&T> = None;
4993        let mut best_n: Option<N> = None;
4994        for x in a {
4995        let n = f(x);
4996        if (match best_n { None => true,
4997        Some(bn) =>
4998        n.cmp(&bn) == Ordering::Greater })
4999        {
5000        best_x = Some(x);
5001        best_n = Some(n);
5002        }
5003        }
5004        return best_x
5005}
5006
5007fn longest(a: &Vec<String>) ->
5008        Option<&String> {
5009        return
5010        maximize(|x: &String| x.len(), a)
5011}
5012\end{cfa}
5013\end{tabular}
5014\end{flushleft}
5015
5016
5017\subsubsection{Modules / Packages}
5018
5019\begin{cfa}
5020\CFA
5021\CC
5022
5023
5024module example/M;
5025
5026export int inc(int val) {
5027        return val + 1;
5028}
5029
5030
5031
5032
5033--------------------------------------
5034//Use the module in another file
5035import example/M;
5036int main() {
5037        print(M.inc(100));
5038        return 0;
5039}
5040// Using \CC17 module proposal
5041
5042module example.M;
5043
5044export {
5045        int inc(int val);
5046}
5047
5048int inc(inv val) {
5049        return val + 1;
5050}
5051--------------------------------------
5052// Use the module in another file
5053import example.M;
5054int main() {
5055        cout << inc(100) << endl;
5056        return 0;
5057}
5058
5059Go
5060Rust
5061package example/M;
5062
5063func Inc(val int32) int32 {
5064        // Capitalization indicates exported
5065        return val + 100
5066}
5067
5068
5069--------------------------------------
5070//Use the package in another file
5071package main
5072import .fmt.
5073import "example/M"
5074
5075func main() int32 {
5076        fmt.Printf(.%v., M.Inc(100))
5077}
5078pub mod example {
5079        pub mod M {
5080        pub inc(val i32) -> i32 {
5081        return val + 100;
5082        }
5083        }
5084}
5085
5086--------------------------------------
5087//Use the module in another file
5088use example::M;
5089
5090
5091
5092fn main() {
5093        println!(.{}., M::inc(100));
5094}
5095\end{cfa}
5096
5097
5098\subsubsection{Parallel Tasks}
5099
5100\begin{flushleft}
5101\begin{tabular}{@{}l|l|l|l@{}}
5102\multicolumn{1}{c|}{\textbf{\CFA}}      & \multicolumn{1}{c|}{\textbf{\CC}} & \multicolumn{1}{c|}{\textbf{Go}} & \multicolumn{1}{c}{\textbf{Rust}}      \\
5103\hline
5104\begin{cfa}
5105task Nonzero {
5106        int *data;
5107        int start;
5108        int end;
5109        int* res;
5110};
5111
5112void ?{}(Nonzero &a, int d[], int s,
5113        int e, int* subres) {
5114        // constructor
5115        a.data = d;
5116        a.start = s;
5117        a.end = e;
5118        a.res = subres;
5119}
5120
5121// implicitly spawn thread here
5122void ?()(NonzeroCounter &a) {
5123        int i;
5124        int nonzero = 0;
5125        for (i=start; c<end; ++i) {
5126        if(a.data[i]!=0){ nonzero++;}
5127        }
5128        *a.res = nonzero;
5129}
5130
5131int main() {
5132        int sz = ...
5133        int data[sz] = ...;
5134        int r1 = 0, r2=0;
5135        int res;
5136        { // create a scope for Nonzero
5137        Nonzero n1{data, 0, sz/2, &n1};
5138        Nonzero n2{data, sz/2, sz, &n2};
5139        n1();//spawn
5140        n2();//spawn
5141        }
5142        res = r1+r2;
5143        return res;
5144}
5145\end{cfa}
5146&
5147\begin{cfa}
5148#include <thread>
5149#include <mutex>
5150
5151std::mutex m;
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164void task(const vector<int>&v,
5165        int* res, size_t s,
5166        size_t e) {
5167        int non_zero = 0;
5168        for(size_t i = s; i < e; ++i){
5169        if(v[i]!=0) { non_zero++;}
5170        }
5171        std::unique_lock<mutex> lck {m};
5172        *res += non_zero;
5173}
5174
5175int main() {
5176        vector<int> data = ...; //data
5177        int res = 0;
5178        std::thread t1 {task, ref(data),
5179        &res, 0,
5180        data.size()/2};
5181        std::thread t2 {task, ref(data),
5182        &res, data.size()/2,
5183        data.size()};
5184        t1.join();
5185        t2.join();
5186        return res;
5187}
5188\end{cfa}
5189&
5190\begin{cfa}
5191package main
5192
5193import "fmt"
5194
5195func nonzero(data []int, c chan int) {
5196        nz := 0
5197        for _, v:=range data {
5198        if(v!=0) { nz := nz+1 }
5199        }
5200        c <- nz
5201}
5202
5203func main() {
5204        sz := ...
5205        data := make([]int, sz)
5206        ... // data init
5207        go nonzero(data[:len(data)/2], c)
5208        go nonzero(data[len(data)/2:], c)
5209        n1, n2 := <-c, <-c
5210        res := n1 + n2
5211        fmt.Println(res)
5212}
5213\end{cfa}
5214&
5215\begin{cfa}
5216use std::thread;
5217use std::sync:mpsc::channel;
5218
5219fn main() {
5220        let sz = ...;
5221        let mut data:Vec<i32> =
5222        Vec::with_capacity(sz as usize);
5223        ... //init data
5224        let (tx, rx) = channel();
5225        for i in 0..1 {
5226        let tx = tx.clone();
5227        let data = data.clone()
5228        thread::spawn(move|| {
5229        let mut nz := 0;
5230        let mut s = 0;
5231        let mut e = sz / 2;
5232        if i == 1 {
5233        s = sz/2;
5234        e = data.len();
5235        }
5236        for i in s..(e - 1) {
5237        if data[i] != 0 (
5238        nz = nz + 1
5239        }
5240        }
5241        tx.send(nz).unwrap();
5242        });
5243        }
5244        let res = rx.recv().unwrap() +
5245        rx.recv().unwrap();
5246        println!(.{}., res);
5247}
5248\end{cfa}
5249\end{tabular}
5250\end{flushleft}
5251
5252}% local change to lstlising to reduce font size
5253
5254
5255\subsection{Summary of Language Comparison}
5256\end{comment}
5257
5258
5259\subsection[C++]{\CC}
5260
5261\Index*[C++]{\CC{}} is a general-purpose programming language.
5262It has imperative, object-oriented and generic programming features, while also providing facilities for low-level memory manipulation. (Wikipedia)
5263
5264The primary focus of \CC seems to be adding object-oriented programming to C, and this is the primary difference between \CC and Do.
5265\CC uses classes to encapsulate data and the functions that operate on that data, and to hide the internal representation of the data.
5266\CFA uses modules instead to perform these same tasks.
5267Classes in \CC also enable inheritance among types.
5268Instead of inheritance, \CFA embraces composition and interfaces to achieve the same goals with more flexibility.
5269There 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).
5270
5271Overloading 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.
5272References and exceptions in \CFA are heavily based on the same features from \CC.
5273The mechanism for interoperating with C code in \CFA is also borrowed from \CC.
5274
5275Both \CFA and \CC provide generics, and the syntax is quite similar.
5276The 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.
5277This means that a generic function can be defined in a compiled library, and still be used as expected from source.
5278
5279
5280\subsection{Go}
5281
5282\Index*{Go}, also commonly referred to as golang, is a programming language developed at Google in 2007 [.].
5283It is a statically typed language with syntax loosely derived from that of C, adding garbage collection, type
5284safety, some structural typing capabilities, additional built-in types such as variable-length arrays and key-value maps, and a large standard library. (Wikipedia)
5285
5286Go and \CFA differ significantly in syntax and implementation, but the underlying core concepts of the two languages are aligned.
5287Both Go and \CFA use composition and interfaces as opposed to inheritance to enable encapsulation and abstraction.
5288Both languages (along with their tooling ecosystem) provide a simple packaging mechanism for building units of code for easy sharing and reuse.
5289Both 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.
5290
5291Go has a significant runtime which handles the scheduling of its light weight threads, and performs garbage collection, among other tasks.
5292\CFA uses a cooperative scheduling algorithm for its tasks, and uses automatic reference counting to enable advanced memory management without garbage collection.
5293This results in Go requiring significant overhead to interface with C libraries while \CFA has no overhead.
5294
5295
5296\subsection{Rust}
5297
5298\Index*{Rust} is a general-purpose, multi-paradigm, compiled programming language developed by Mozilla Research.
5299It is designed to be a "safe, concurrent, practical language", supporting pure-functional, concurrent-actor[dubious . discuss][citation needed], imperative-procedural, and object-oriented styles.
5300
5301The primary focus of Rust is in safety, especially in concurrent programs.
5302To enforce a high level of safety, Rust has added ownership as a core feature of the language to guarantee memory safety.
5303This safety comes at the cost of a difficult learning curve, a change in the thought model of the program, and often some runtime overhead.
5304
5305Aside from those key differences, Rust and \CFA also have several similarities.
5306Both languages support no overhead interoperability with C and have minimal runtimes.
5307Both languages support inheritance and polymorphism through the use of interfaces (traits).
5308
5309
5310\subsection{D}
5311
5312The \Index*{D} programming language is an object-oriented, imperative, multi-paradigm system programming
5313language created by Walter Bright of Digital Mars and released in 2001. [.]
5314Though 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.
5315
5316D and \CFA both start with C and add productivity features.
5317The obvious difference is that D uses classes and inheritance while \CFA uses composition and interfaces.
5318D is closer to \CFA than \CC since it is limited to single inheritance and also supports interfaces.
5319Like \CC, and unlike \CFA, D uses garbage collection and has compile-time expanded templates.
5320D does not have any built-in concurrency constructs in the
5321language, though it does have a standard library for concurrency which includes the low-level primitives for concurrency.
5322
5323
5324\appendix
5325
5326
5327\section{Syntax Ambiguities}
5328
5329C has a number of syntax ambiguities, which are resolved by taking the longest sequence of overlapping characters that constitute a token.
5330For example, the program fragment ©x+++++y© is parsed as \lstinline[showspaces=true]@x ++ ++ + y@ because operator tokens ©++© and ©+© overlap.
5331Unfortunately, the longest sequence violates a constraint on increment operators, even though the parse \lstinline[showspaces=true]@x ++ + ++ y@ might yield a correct expression.
5332Hence, C programmers are aware that spaces have to added to disambiguate certain syntactic cases.
5333
5334In \CFA, there are ambiguous cases with dereference and operator identifiers, \eg ©int *?*?()©, where the string ©*?*?© can be interpreted as:
5335\begin{cfa}
5336*?§\color{red}\textvisiblespace§*?              §\C{// dereference operator, dereference operator}§
5337\color{red}\textvisiblespace§?*?              §\C{// dereference, multiplication operator}§
5338\end{cfa}
5339By default, the first interpretation is selected, which does not yield a meaningful parse.
5340Therefore, \CFA does a lexical look-ahead for the second case, and backtracks to return the leading unary operator and reparses the trailing operator identifier.
5341Otherwise a space is needed between the unary operator and operator identifier to disambiguate this common case.
5342
5343A similar issue occurs with the dereference, ©*?(...)©, and routine-call, ©?()(...)© identifiers.
5344The ambiguity occurs when the deference operator has no parameters:
5345\begin{cfa}
5346*?()§\color{red}\textvisiblespace...§ ;
5347*?()§\color{red}\textvisiblespace...§(...) ;
5348\end{cfa}
5349requiring arbitrary whitespace look-ahead for the routine-call parameter-list to disambiguate.
5350However, the dereference operator \emph{must} have a parameter/argument to dereference ©*?(...)©.
5351Hence, always interpreting the string ©*?()© as \lstinline[showspaces=true]@* ?()@ does not preclude any meaningful program.
5352
5353The remaining cases are with the increment/decrement operators and conditional expression, \eg:
5354\begin{cfa}
5355i++?§\color{red}\textvisiblespace...§(...);
5356i?++§\color{red}\textvisiblespace...§(...);
5357\end{cfa}
5358requiring arbitrary whitespace look-ahead for the operator parameter-list, even though that interpretation is an incorrect expression (juxtaposed identifiers).
5359Therefore, it is necessary to disambiguate these cases with a space:
5360\begin{cfa}
5361i++§\color{red}\textvisiblespace§? i : 0;
5362i?§\color{red}\textvisiblespace§++i : 0;
5363\end{cfa}
5364
5365
5366\section{\texorpdfstring{\CFA Keywords}{Cforall Keywords}}
5367\label{s:CFAKeywords}
5368
5369\CFA introduces the following new keywords.
5370
5371\begin{quote2}
5372\begin{tabular}{lllll}
5373\begin{tabular}{@{}l@{}}
5374©_At©                   \\
5375©catch©                 \\
5376©catchResume©   \\
5377©choose©                \\
5378©coroutine©             \\
5379\end{tabular}
5380&
5381\begin{tabular}{@{}l@{}}
5382©disable©               \\
5383©dtype©                 \\
5384©enable©                \\
5385©fallthrough©   \\
5386©fallthru©              \\
5387\end{tabular}
5388&
5389\begin{tabular}{@{}l@{}}
5390©finally©               \\
5391©forall©                \\
5392©ftype©                 \\
5393©lvalue©                \\
5394©monitor©               \\
5395\end{tabular}
5396&
5397\begin{tabular}{@{}l@{}}
5398©mutex©                 \\
5399©one_t©                 \\
5400©otype©                 \\
5401©throw©                 \\
5402©throwResume©   \\
5403\end{tabular}
5404&
5405\begin{tabular}{@{}l@{}}
5406©trait©                 \\
5407©try©                   \\
5408©ttype©                 \\
5409©zero_t©                \\
5410                                \\
5411\end{tabular}
5412\end{tabular}
5413\end{quote2}
5414
5415
5416\section{Incompatible}
5417
5418The following incompatibles exist between \CFA and C, and are similar to Annex C for \CC~\cite{C++14}.
5419
5420
5421\begin{enumerate}
5422\item
5423\begin{description}
5424\item[Change:] add new keywords \\
5425New keywords are added to \CFA (see~\VRef{s:CFAKeywords}).
5426\item[Rationale:] keywords added to implement new semantics of \CFA.
5427\item[Effect on original feature:] change to semantics of well-defined feature. \\
5428Any \Celeven programs using these keywords as identifiers are invalid \CFA programs.
5429\item[Difficulty of converting:] keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism (see~\VRef{s:BackquoteIdentifiers}).
5430\item[How widely used:] clashes among new \CFA keywords and existing identifiers are rare.
5431\end{description}
5432
5433\item
5434\begin{description}
5435\item[Change:] drop K\&R C declarations \\
5436K\&R declarations allow an implicit base-type of ©int©, if no type is specified, plus an alternate syntax for declaring parameters.
5437\eg:
5438\begin{cfa}
5439x;                                                              §\C{// int x}§
5440*y;                                                             §\C{// int *y}§
5441f( p1, p2 );                                    §\C{// int f( int p1, int p2 );}§
5442g( p1, p2 ) int p1, p2;                 §\C{// int g( int p1, int p2 );}§
5443\end{cfa}
5444\CFA supports K\&R routine definitions:
5445\begin{cfa}
5446f( a, b, c )                                    §\C{// default int return}§
5447        int a, b; char c                        §\C{// K\&R parameter declarations}§
5448{
5449        ...
5450}
5451\end{cfa}
5452\item[Rationale:] dropped from \Celeven standard.\footnote{
5453At 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}}
5454\item[Effect on original feature:] original feature is deprecated. \\
5455Any old C programs using these K\&R declarations are invalid \CFA programs.
5456\item[Difficulty of converting:] trivial to convert to \CFA.
5457\item[How widely used:] existing usages are rare.
5458\end{description}
5459
5460\item
5461\begin{description}
5462\item[Change:] type of character literal ©int© to ©char© to allow more intuitive overloading:
5463\begin{cfa}
5464int rtn( int i );
5465int rtn( char c );
5466rtn( 'x' );                                             §\C{// programmer expects 2nd rtn to be called}§
5467\end{cfa}
5468\item[Rationale:] it is more intuitive for the call to ©rtn© to match the second version of definition of ©rtn© rather than the first.
5469In particular, output of ©char© variable now print a character rather than the decimal ASCII value of the character.
5470\begin{cfa}
5471sout | 'x' | " " | (int)'x' | endl;
5472x 120
5473\end{cfa}
5474Having to cast ©'x'© to ©char© is non-intuitive.
5475\item[Effect on original feature:] change to semantics of well-defined feature that depend on:
5476\begin{cfa}
5477sizeof( 'x' ) == sizeof( int )
5478\end{cfa}
5479no long work the same in \CFA programs.
5480\item[Difficulty of converting:] simple
5481\item[How widely used:] programs that depend upon ©sizeof( 'x' )© are rare and can be changed to ©sizeof(char)©.
5482\end{description}
5483
5484\item
5485\begin{description}
5486\item[Change:] make string literals ©const©:
5487\begin{cfa}
5488char * p = "abc";                               §\C{// valid in C, deprecated in \CFA}§
5489char * q = expr ? "abc" : "de"; §\C{// valid in C, invalid in \CFA}§
5490\end{cfa}
5491The type of a string literal is changed from ©[] char© to ©const [] char©.
5492Similarly, the type of a wide string literal is changed from ©[] wchar_t© to ©const [] wchar_t©.
5493\item[Rationale:] This change is a safety issue:
5494\begin{cfa}
5495char * p = "abc";
5496p[0] = 'w';                                             §\C{// segment fault or change constant literal}§
5497\end{cfa}
5498The same problem occurs when passing a string literal to a routine that changes its argument.
5499\item[Effect on original feature:] change to semantics of well-defined feature.
5500\item[Difficulty of converting:] simple syntactic transformation, because string literals can be converted to ©char *©.
5501\item[How widely used:] programs that have a legitimate reason to treat string literals as pointers to potentially modifiable memory are rare.
5502\end{description}
5503
5504\item
5505\begin{description}
5506\item[Change:] remove \newterm{tentative definitions}, which only occurs at file scope:
5507\begin{cfa}
5508int i;                                                  §\C{// forward definition}§
5509int *j = ®&i®;                                  §\C{// forward reference, valid in C, invalid in \CFA}§
5510int i = 0;                                              §\C{// definition}§
5511\end{cfa}
5512is valid in C, and invalid in \CFA because duplicate overloaded object definitions at the same scope level are disallowed.
5513This change makes it impossible to define mutually referential file-local static objects, if initializers are restricted to the syntactic forms of C. For example,
5514\begin{cfa}
5515struct X { int i; struct X *next; };
5516static struct X a;                              §\C{// forward definition}§
5517static struct X b = { 0, ®&};        §\C{// forward reference, valid in C, invalid in \CFA}§
5518static struct X a = { 1, &b };  §\C{// definition}§
5519\end{cfa}
5520\item[Rationale:] avoids having different initialization rules for builtin types and user-defined types.
5521\item[Effect on original feature:] change to semantics of well-defined feature.
5522\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.
5523\item[How widely used:] seldom
5524\end{description}
5525
5526\item
5527\begin{description}
5528\item[Change:] have ©struct© introduce a scope for nested types:
5529\begin{cfa}
5530enum ®Colour® { R, G, B, Y, C, M };
5531struct Person {
5532        enum ®Colour® { R, G, B };      §\C{// nested type}§
5533        struct Face {                           §\C{// nested type}§
5534                ®Colour® Eyes, Hair;    §\C{// type defined outside (1 level)}§
5535        };
5536        ®.Colour® shirt;                        §\C{// type defined outside (top level)}§
5537        ®Colour® pants;                         §\C{// type defined same level}§
5538        Face looks[10];                         §\C{// type defined same level}§
5539};
5540®Colour® c = R;                                 §\C{// type/enum defined same level}§
5541Person®.Colour® pc = Person®.®R;        §\C{// type/enum defined inside}§
5542Person®.®Face pretty;                   §\C{// type defined inside}§
5543\end{cfa}
5544In 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.
5545\CFA is C \emph{incompatible} on this issue, and provides semantics similar to \Index*[C++]{\CC{}}.
5546Nested types are not hoisted and can be referenced using the field selection operator ``©.©'', unlike the \CC scope-resolution operator ``©::©''.
5547\item[Rationale:] ©struct© scope is crucial to \CFA as an information structuring and hiding mechanism.
5548\item[Effect on original feature:] change to semantics of well-defined feature.
5549\item[Difficulty of converting:] Semantic transformation.
5550\item[How widely used:] C programs rarely have nest types because they are equivalent to the hoisted version.
5551\end{description}
5552
5553\item
5554\begin{description}
5555\item[Change:] In C++, the name of a nested class is local to its enclosing class.
5556\item[Rationale:] C++ classes have member functions which require that classes establish scopes.
5557\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:
5558\begin{cfa}
5559struct Y;                                               §\C{// struct Y and struct X are at the same scope}§
5560struct X {
5561        struct Y { /* ... */ } y;
5562};
5563\end{cfa}
5564All 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.
5565Note: this is a consequence of the difference in scope rules, which is documented in 3.3.
5566\item[How widely used:] Seldom.
5567\end{description}
5568
5569\item
5570\begin{description}
5571\item[Change:] comma expression is disallowed as subscript
5572\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.
5573\item[Effect on original feature:] change to semantics of well-defined feature.
5574\item[Difficulty of converting:] semantic transformation of ©x[i,j]© to ©x[(i,j)]©
5575\item[How widely used:] seldom.
5576\end{description}
5577\end{enumerate}
5578
5579
5580\section{Standard Headers}
5581\label{s:StandardHeaders}
5582
5583\Celeven prescribes the following standard header-files~\cite[\S~7.1.2]{C11} and \CFA adds to this list:
5584\begin{quote2}
5585\begin{tabular}{@{}lllll|l@{}}
5586\multicolumn{5}{c|}{C11} & \multicolumn{1}{c}{\CFA}             \\
5587\hline
5588\begin{tabular}{@{}l@{}}
5589\Indexc{assert.h}               \\
5590\Indexc{complex.h}              \\
5591\Indexc{ctype.h}                \\
5592\Indexc{errno.h}                \\
5593\Indexc{fenv.h}                 \\
5594\Indexc[deletekeywords=float]{float.h} \\
5595\end{tabular}
5596&
5597\begin{tabular}{@{}l@{}}
5598\Indexc{inttypes.h}             \\
5599\Indexc{iso646.h}               \\
5600\Indexc{limits.h}               \\
5601\Indexc{locale.h}               \\
5602\Indexc{math.h}                 \\
5603\Indexc{setjmp.h}               \\
5604\end{tabular}
5605&
5606\begin{tabular}{@{}l@{}}
5607\Indexc{signal.h}               \\
5608\Indexc{stdalign.h}             \\
5609\Indexc{stdarg.h}               \\
5610\Indexc{stdatomic.h}    \\
5611\Indexc{stdbool.h}              \\
5612\Indexc{stddef.h}               \\
5613\end{tabular}
5614&
5615\begin{tabular}{@{}l@{}}
5616\Indexc{stdint.h}               \\
5617\Indexc{stdio.h}                \\
5618\Indexc{stdlib.h}               \\
5619\Indexc{stdnoreturn.h}  \\
5620\Indexc{string.h}               \\
5621\Indexc{tgmath.h}               \\
5622\end{tabular}
5623&
5624\begin{tabular}{@{}l@{}}
5625\Indexc{threads.h}              \\
5626\Indexc{time.h}                 \\
5627\Indexc{uchar.h}                \\
5628\Indexc{wchar.h}                \\
5629\Indexc{wctype.h}               \\
5630                                                \\
5631\end{tabular}
5632&
5633\begin{tabular}{@{}l@{}}
5634\Indexc{unistd.h}               \\
5635\Indexc{gmp.h}                  \\
5636                                                \\
5637                                                \\
5638                                                \\
5639                                                \\
5640\end{tabular}
5641\end{tabular}
5642\end{quote2}
5643For the prescribed head-files, \CFA uses header interposition to wraps these includes in an ©extern "C"©;
5644hence, names in these include files are not mangled\index{mangling!name} (see~\VRef{s:Interoperability}).
5645All other C header files must be explicitly wrapped in ©extern "C"© to prevent name mangling.
5646For \Index*[C++]{\CC{}}, the name-mangling issue is handled implicitly because most C header-files are augmented with checks for preprocessor variable ©__cplusplus©, which adds appropriate ©extern "C"© qualifiers.
5647
5648
5649\section{Standard Library}
5650\label{s:StandardLibrary}
5651
5652The \CFA standard-library wraps explicitly-polymorphic C routines into implicitly-polymorphic versions.
5653
5654
5655\subsection{Storage Management}
5656
5657The 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.
5658
5659Storage management provides the following capabilities:
5660\begin{description}
5661\item[fill]
5662after allocation the storage is filled with a specified character.
5663\item[resize]
5664an existing allocation is decreased or increased in size.
5665In 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.
5666For an increase in storage size, new storage after the copied data may be filled.
5667\item[alignment]
5668an allocation starts on a specified memory boundary, \eg, an address multiple of 64 or 128 for cache-line purposes.
5669\item[array]
5670the allocation size is scaled to the specified number of array elements.
5671An array may be filled, resized, or aligned.
5672\end{description}
5673The table shows allocation routines supporting different combinations of storage-management capabilities:
5674\begin{center}
5675\begin{tabular}{@{}r|r|l|l|l|l@{}}
5676\multicolumn{1}{c}{}&           & \multicolumn{1}{c|}{fill}     & resize        & alignment     & array \\
5677\hline
5678C               & ©malloc©                      & no                    & no            & no            & no    \\
5679                & ©calloc©                      & yes (0 only)  & no            & no            & yes   \\
5680                & ©realloc©                     & no/copy               & yes           & no            & no    \\
5681                & ©memalign©            & no                    & no            & yes           & no    \\
5682                & ©posix_memalign©      & no                    & no            & yes           & no    \\
5683\hline
5684C11             & ©aligned_alloc©       & no                    & no            & yes           & no    \\
5685\hline
5686\CFA    & ©alloc©                       & no/copy/yes   & no/yes        & no            & yes   \\
5687                & ©align_alloc©         & no/yes                & no            & yes           & yes   \\
5688\end{tabular}
5689\end{center}
5690It is impossible to resize with alignment because the underlying ©realloc© allocates storage if more space is needed, and it does not honour alignment from the original allocation.
5691
5692\leavevmode
5693\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5694// C unsafe allocation
5695extern "C" {
5696void * malloc( size_t size );§\indexc{memset}§
5697void * calloc( size_t dim, size_t size );§\indexc{calloc}§
5698void * realloc( void * ptr, size_t size );§\indexc{realloc}§
5699void * memalign( size_t align, size_t size );§\indexc{memalign}§
5700int posix_memalign( void ** ptr, size_t align, size_t size );§\indexc{posix_memalign}§
5701}
5702
5703// §\CFA§ safe equivalents, i.e., implicit size specification
5704forall( dtype T | sized(T) ) T * malloc( void );
5705forall( dtype T | sized(T) ) T * calloc( size_t dim );
5706forall( dtype T | sized(T) ) T * realloc( T * ptr, size_t size );
5707forall( dtype T | sized(T) ) T * memalign( size_t align );
5708forall( dtype T | sized(T) ) T * aligned_alloc( size_t align );
5709forall( dtype T | sized(T) ) int posix_memalign( T ** ptr, size_t align );
5710
5711// §\CFA§ safe general allocation, fill, resize, array
5712forall( dtype T | sized(T) ) T * alloc( void );§\indexc{alloc}§
5713forall( dtype T | sized(T) ) T * alloc( char fill );
5714forall( dtype T | sized(T) ) T * alloc( size_t dim );
5715forall( dtype T | sized(T) ) T * alloc( size_t dim, char fill );
5716forall( dtype T | sized(T) ) T * alloc( T ptr[], size_t dim );
5717forall( dtype T | sized(T) ) T * alloc( T ptr[], size_t dim, char fill );
5718
5719// §\CFA§ safe general allocation, align, fill, array
5720forall( dtype T | sized(T) ) T * align_alloc( size_t align );
5721forall( dtype T | sized(T) ) T * align_alloc( size_t align, char fill );
5722forall( dtype T | sized(T) ) T * align_alloc( size_t align, size_t dim );
5723forall( dtype T | sized(T) ) T * align_alloc( size_t align, size_t dim, char fill );
5724
5725// C unsafe initialization/copy
5726extern "C" {
5727void * memset( void * dest, int c, size_t size );
5728void * memcpy( void * dest, const void * src, size_t size );
5729}
5730
5731// §\CFA§ safe initialization/copy, i.e., implicit size specification
5732forall( dtype T | sized(T) ) T * memset( T * dest, char c );§\indexc{memset}§
5733forall( dtype T | sized(T) ) T * memcpy( T * dest, const T * src );§\indexc{memcpy}§
5734
5735// §\CFA§ safe initialization/copy array
5736forall( dtype T | sized(T) ) T * memset( T dest[], size_t dim, char c );
5737forall( dtype T | sized(T) ) T * memcpy( T dest[], const T src[], size_t dim );
5738
5739// §\CFA§ allocation/deallocation and constructor/destructor
5740forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * new( Params p );§\indexc{new}§
5741forall( dtype T | { void ^?{}( T * ); } ) void delete( T * ptr );§\indexc{delete}§
5742forall( dtype T, ttype Params | { void ^?{}( T * ); void delete( Params ); } )
5743  void delete( T * ptr, Params rest );
5744
5745// §\CFA§ allocation/deallocation and constructor/destructor, array
5746forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * anew( size_t dim, Params p );§\indexc{anew}§
5747forall( dtype T | sized(T) | { void ^?{}( T * ); } ) void adelete( size_t dim, T arr[] );§\indexc{adelete}§
5748forall( dtype T | sized(T) | { void ^?{}( T * ); }, ttype Params | { void adelete( Params ); } )
5749  void adelete( size_t dim, T arr[], Params rest );
5750\end{cfa}
5751
5752
5753\subsection{Conversion}
5754
5755\leavevmode
5756\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5757int ato( const char * ptr );§\indexc{ato}§
5758unsigned int ato( const char * ptr );
5759long int ato( const char * ptr );
5760unsigned long int ato( const char * ptr );
5761long long int ato( const char * ptr );
5762unsigned long long int ato( const char * ptr );
5763float ato( const char * ptr );
5764double ato( const char * ptr );
5765long double ato( const char * ptr );
5766float _Complex ato( const char * ptr );
5767double _Complex ato( const char * ptr );
5768long double _Complex ato( const char * ptr );
5769
5770int strto( const char * sptr, char ** eptr, int base );
5771unsigned int strto( const char * sptr, char ** eptr, int base );
5772long int strto( const char * sptr, char ** eptr, int base );
5773unsigned long int strto( const char * sptr, char ** eptr, int base );
5774long long int strto( const char * sptr, char ** eptr, int base );
5775unsigned long long int strto( const char * sptr, char ** eptr, int base );
5776float strto( const char * sptr, char ** eptr );
5777double strto( const char * sptr, char ** eptr );
5778long double strto( const char * sptr, char ** eptr );
5779float _Complex strto( const char * sptr, char ** eptr );
5780double _Complex strto( const char * sptr, char ** eptr );
5781long double _Complex strto( const char * sptr, char ** eptr );
5782\end{cfa}
5783
5784
5785\subsection{Search / Sort}
5786
5787\leavevmode
5788\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5789forall( otype T | { int ?<?( T, T ); } )        §\C{// location}§
5790T * bsearch( T key, const T * arr, size_t dim );§\indexc{bsearch}§
5791
5792forall( otype T | { int ?<?( T, T ); } )        §\C{// position}§
5793unsigned int bsearch( T key, const T * arr, size_t dim );
5794
5795forall( otype T | { int ?<?( T, T ); } )
5796void qsort( const T * arr, size_t dim );§\indexc{qsort}§
5797\end{cfa}
5798
5799
5800\subsection{Absolute Value}
5801
5802\leavevmode
5803\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5804unsigned char abs( signed char );§\indexc{abs}§
5805int abs( int );
5806unsigned long int abs( long int );
5807unsigned long long int abs( long long int );
5808float abs( float );
5809double abs( double );
5810long double abs( long double );
5811float abs( float _Complex );
5812double abs( double _Complex );
5813long double abs( long double _Complex );
5814forall( otype T | { void ?{}( T *, zero_t ); int ?<?( T, T ); T -?( T ); } )
5815T abs( T );
5816\end{cfa}
5817
5818
5819\subsection{Random Numbers}
5820
5821\leavevmode
5822\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5823void rand48seed( long int s );§\indexc{rand48seed}§
5824char rand48();§\indexc{rand48}§
5825int rand48();
5826unsigned int rand48();
5827long int rand48();
5828unsigned long int rand48();
5829float rand48();
5830double rand48();
5831float _Complex rand48();
5832double _Complex rand48();
5833long double _Complex rand48();
5834\end{cfa}
5835
5836
5837\subsection{Algorithms}
5838
5839\leavevmode
5840\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5841forall( otype T | { int ?<?( T, T ); } ) T min( T t1, T t2 );§\indexc{min}§
5842forall( otype T | { int ?>?( T, T ); } ) T max( T t1, T t2 );§\indexc{max}§
5843forall( otype T | { T min( T, T ); T max( T, T ); } ) T clamp( T value, T min_val, T max_val );§\indexc{clamp}§
5844forall( otype T ) void swap( T * t1, T * t2 );§\indexc{swap}§
5845\end{cfa}
5846
5847
5848\section{Math Library}
5849\label{s:Math Library}
5850
5851The \CFA math-library wraps explicitly-polymorphic C math-routines into implicitly-polymorphic versions.
5852
5853
5854\subsection{General}
5855
5856\leavevmode
5857\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5858float ?%?( float, float );§\indexc{fmod}§
5859float fmod( float, float );
5860double ?%?( double, double );
5861double fmod( double, double );
5862long double ?%?( long double, long double );
5863long double fmod( long double, long double );
5864
5865float remainder( float, float );§\indexc{remainder}§
5866double remainder( double, double );
5867long double remainder( long double, long double );
5868
5869[ int, float ] remquo( float, float );§\indexc{remquo}§
5870float remquo( float, float, int * );
5871[ int, double ] remquo( double, double );
5872double remquo( double, double, int * );
5873[ int, long double ] remquo( long double, long double );
5874long double remquo( long double, long double, int * );
5875
5876[ int, float ] div( float, float );                                             // alternative name for remquo
5877float div( float, float, int * );§\indexc{div}§
5878[ int, double ] div( double, double );
5879double div( double, double, int * );
5880[ int, long double ] div( long double, long double );
5881long double div( long double, long double, int * );
5882
5883float fma( float, float, float );§\indexc{fma}§
5884double fma( double, double, double );
5885long double fma( long double, long double, long double );
5886
5887float fdim( float, float );§\indexc{fdim}§
5888double fdim( double, double );
5889long double fdim( long double, long double );
5890
5891float nan( const char * );§\indexc{nan}§
5892double nan( const char * );
5893long double nan( const char * );
5894\end{cfa}
5895
5896
5897\subsection{Exponential}
5898
5899\leavevmode
5900\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5901float exp( float );§\indexc{exp}§
5902double exp( double );
5903long double exp( long double );
5904float _Complex exp( float _Complex );
5905double _Complex exp( double _Complex );
5906long double _Complex exp( long double _Complex );
5907
5908float exp2( float );§\indexc{exp2}§
5909double exp2( double );
5910long double exp2( long double );
5911float _Complex exp2( float _Complex );
5912double _Complex exp2( double _Complex );
5913long double _Complex exp2( long double _Complex );
5914
5915float expm1( float );§\indexc{expm1}§
5916double expm1( double );
5917long double expm1( long double );
5918
5919float log( float );§\indexc{log}§
5920double log( double );
5921long double log( long double );
5922float _Complex log( float _Complex );
5923double _Complex log( double _Complex );
5924long double _Complex log( long double _Complex );
5925
5926float log2( float );§\indexc{log2}§
5927double log2( double );
5928long double log2( long double );
5929float _Complex log2( float _Complex );
5930double _Complex log2( double _Complex );
5931long double _Complex log2( long double _Complex );
5932
5933float log10( float );§\indexc{log10}§
5934double log10( double );
5935long double log10( long double );
5936float _Complex log10( float _Complex );
5937double _Complex log10( double _Complex );
5938long double _Complex log10( long double _Complex );
5939
5940float log1p( float );§\indexc{log1p}§
5941double log1p( double );
5942long double log1p( long double );
5943
5944int ilogb( float );§\indexc{ilogb}§
5945int ilogb( double );
5946int ilogb( long double );
5947
5948float logb( float );§\indexc{logb}§
5949double logb( double );
5950long double logb( long double );
5951\end{cfa}
5952
5953
5954\subsection{Power}
5955
5956\leavevmode
5957\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5958float sqrt( float );§\indexc{sqrt}§
5959double sqrt( double );
5960long double sqrt( long double );
5961float _Complex sqrt( float _Complex );
5962double _Complex sqrt( double _Complex );
5963long double _Complex sqrt( long double _Complex );
5964
5965float cbrt( float );§\indexc{cbrt}§
5966double cbrt( double );
5967long double cbrt( long double );
5968
5969float hypot( float, float );§\indexc{hypot}§
5970double hypot( double, double );
5971long double hypot( long double, long double );
5972
5973float pow( float, float );§\indexc{pow}§
5974double pow( double, double );
5975long double pow( long double, long double );
5976float _Complex pow( float _Complex, float _Complex );
5977double _Complex pow( double _Complex, double _Complex );
5978long double _Complex pow( long double _Complex, long double _Complex );
5979\end{cfa}
5980
5981
5982\subsection{Trigonometric}
5983
5984\leavevmode
5985\begin{cfa}[aboveskip=0pt,belowskip=0pt]
5986float sin( float );§\indexc{sin}§
5987double sin( double );
5988long double sin( long double );
5989float _Complex sin( float _Complex );
5990double _Complex sin( double _Complex );
5991long double _Complex sin( long double _Complex );
5992
5993float cos( float );§\indexc{cos}§
5994double cos( double );
5995long double cos( long double );
5996float _Complex cos( float _Complex );
5997double _Complex cos( double _Complex );
5998long double _Complex cos( long double _Complex );
5999
6000float tan( float );§\indexc{tan}§
6001double tan( double );
6002long double tan( long double );
6003float _Complex tan( float _Complex );
6004double _Complex tan( double _Complex );
6005long double _Complex tan( long double _Complex );
6006
6007float asin( float );§\indexc{asin}§
6008double asin( double );
6009long double asin( long double );
6010float _Complex asin( float _Complex );
6011double _Complex asin( double _Complex );
6012long double _Complex asin( long double _Complex );
6013
6014float acos( float );§\indexc{acos}§
6015double acos( double );
6016long double acos( long double );
6017float _Complex acos( float _Complex );
6018double _Complex acos( double _Complex );
6019long double _Complex acos( long double _Complex );
6020
6021float atan( float );§\indexc{atan}§
6022double atan( double );
6023long double atan( long double );
6024float _Complex atan( float _Complex );
6025double _Complex atan( double _Complex );
6026long double _Complex atan( long double _Complex );
6027
6028float atan2( float, float );§\indexc{atan2}§
6029double atan2( double, double );
6030long double atan2( long double, long double );
6031
6032float atan( float, float );                                                             // alternative name for atan2
6033double atan( double, double );§\indexc{atan}§
6034long double atan( long double, long double );
6035\end{cfa}
6036
6037
6038\subsection{Hyperbolic}
6039
6040\leavevmode
6041\begin{cfa}[aboveskip=0pt,belowskip=0pt]
6042float sinh( float );§\indexc{sinh}§
6043double sinh( double );
6044long double sinh( long double );
6045float _Complex sinh( float _Complex );
6046double _Complex sinh( double _Complex );
6047long double _Complex sinh( long double _Complex );
6048
6049float cosh( float );§\indexc{cosh}§
6050double cosh( double );
6051long double cosh( long double );
6052float _Complex cosh( float _Complex );
6053double _Complex cosh( double _Complex );
6054long double _Complex cosh( long double _Complex );
6055
6056float tanh( float );§\indexc{tanh}§
6057double tanh( double );
6058long double tanh( long double );
6059float _Complex tanh( float _Complex );
6060double _Complex tanh( double _Complex );
6061long double _Complex tanh( long double _Complex );
6062
6063float asinh( float );§\indexc{asinh}§
6064double asinh( double );
6065long double asinh( long double );
6066float _Complex asinh( float _Complex );
6067double _Complex asinh( double _Complex );
6068long double _Complex asinh( long double _Complex );
6069
6070float acosh( float );§\indexc{acosh}§
6071double acosh( double );
6072long double acosh( long double );
6073float _Complex acosh( float _Complex );
6074double _Complex acosh( double _Complex );
6075long double _Complex acosh( long double _Complex );
6076
6077float atanh( float );§\indexc{atanh}§
6078double atanh( double );
6079long double atanh( long double );
6080float _Complex atanh( float _Complex );
6081double _Complex atanh( double _Complex );
6082long double _Complex atanh( long double _Complex );
6083\end{cfa}
6084
6085
6086\subsection{Error / Gamma}
6087
6088\leavevmode
6089\begin{cfa}[aboveskip=0pt,belowskip=0pt]
6090float erf( float );§\indexc{erf}§
6091double erf( double );
6092long double erf( long double );
6093float _Complex erf( float _Complex );
6094double _Complex erf( double _Complex );
6095long double _Complex erf( long double _Complex );
6096
6097float erfc( float );§\indexc{erfc}§
6098double erfc( double );
6099long double erfc( long double );
6100float _Complex erfc( float _Complex );
6101double _Complex erfc( double _Complex );
6102long double _Complex erfc( long double _Complex );
6103
6104float lgamma( float );§\indexc{lgamma}§
6105double lgamma( double );
6106long double lgamma( long double );
6107float lgamma( float, int * );
6108double lgamma( double, int * );
6109long double lgamma( long double, int * );
6110
6111float tgamma( float );§\indexc{tgamma}§
6112double tgamma( double );
6113long double tgamma( long double );
6114\end{cfa}
6115
6116
6117\subsection{Nearest Integer}
6118
6119\leavevmode
6120\begin{cfa}[aboveskip=0pt,belowskip=0pt]
6121float floor( float );§\indexc{floor}§
6122double floor( double );
6123long double floor( long double );
6124
6125float ceil( float );§\indexc{ceil}§
6126double ceil( double );
6127long double ceil( long double );
6128
6129float trunc( float );§\indexc{trunc}§
6130double trunc( double );
6131long double trunc( long double );
6132
6133float rint( float );§\indexc{rint}§
6134long double rint( long double );
6135long int rint( float );
6136long int rint( double );
6137long int rint( long double );
6138long long int rint( float );
6139long long int rint( double );
6140long long int rint( long double );
6141
6142long int lrint( float );§\indexc{lrint}§
6143long int lrint( double );
6144long int lrint( long double );
6145long long int llrint( float );
6146long long int llrint( double );
6147long long int llrint( long double );
6148
6149float nearbyint( float );§\indexc{nearbyint}§
6150double nearbyint( double );
6151long double nearbyint( long double );
6152
6153float round( float );§\indexc{round}§
6154long double round( long double );
6155long int round( float );
6156long int round( double );
6157long int round( long double );
6158long long int round( float );
6159long long int round( double );
6160long long int round( long double );
6161
6162long int lround( float );§\indexc{lround}§
6163long int lround( double );
6164long int lround( long double );
6165long long int llround( float );
6166long long int llround( double );
6167long long int llround( long double );
6168\end{cfa}
6169
6170
6171\subsection{Manipulation}
6172
6173\leavevmode
6174\begin{cfa}[aboveskip=0pt,belowskip=0pt]
6175float copysign( float, float );§\indexc{copysign}§
6176double copysign( double, double );
6177long double copysign( long double, long double );
6178
6179float frexp( float, int * );§\indexc{frexp}§
6180double frexp( double, int * );
6181long double frexp( long double, int * );
6182
6183float ldexp( float, int );§\indexc{ldexp}§
6184double ldexp( double, int );
6185long double ldexp( long double, int );
6186
6187[ float, float ] modf( float );§\indexc{modf}§
6188float modf( float, float * );
6189[ double, double ] modf( double );
6190double modf( double, double * );
6191[ long double, long double ] modf( long double );
6192long double modf( long double, long double * );
6193
6194float nextafter( float, float );§\indexc{nextafter}§
6195double nextafter( double, double );
6196long double nextafter( long double, long double );
6197
6198float nexttoward( float, long double );§\indexc{nexttoward}§
6199double nexttoward( double, long double );
6200long double nexttoward( long double, long double );
6201
6202float scalbn( float, int );§\indexc{scalbn}§
6203double scalbn( double, int );
6204long double scalbn( long double, int );
6205
6206float scalbln( float, long int );§\indexc{scalbln}§
6207double scalbln( double, long int );
6208long double scalbln( long double, long int );
6209\end{cfa}
6210
6211
6212\section{Multi-precision Integers}
6213\label{s:MultiPrecisionIntegers}
6214
6215\CFA has an interface to the GMP \Index{multi-precision} signed-integers~\cite{GMP}, similar to the \CC interface provided by GMP.
6216The \CFA interface wraps GMP routines into operator routines to make programming with multi-precision integers identical to using fixed-sized integers.
6217The \CFA type name for multi-precision signed-integers is \Indexc{Int} and the header file is \Indexc{gmp}.
6218
6219\begin{cfa}
6220void ?{}( Int * this );                                 §\C{// constructor}§
6221void ?{}( Int * this, Int init );
6222void ?{}( Int * this, zero_t );
6223void ?{}( Int * this, one_t );
6224void ?{}( Int * this, signed long int init );
6225void ?{}( Int * this, unsigned long int init );
6226void ?{}( Int * this, const char * val );
6227void ^?{}( Int * this );
6228
6229Int ?=?( Int * lhs, Int rhs );                  §\C{// assignment}§
6230Int ?=?( Int * lhs, long int rhs );
6231Int ?=?( Int * lhs, unsigned long int rhs );
6232Int ?=?( Int * lhs, const char * rhs );
6233
6234char ?=?( char * lhs, Int rhs );
6235short int ?=?( short int * lhs, Int rhs );
6236int ?=?( int * lhs, Int rhs );
6237long int ?=?( long int * lhs, Int rhs );
6238unsigned char ?=?( unsigned char * lhs, Int rhs );
6239unsigned short int ?=?( unsigned short int * lhs, Int rhs );
6240unsigned int ?=?( unsigned int * lhs, Int rhs );
6241unsigned long int ?=?( unsigned long int * lhs, Int rhs );
6242
6243long int narrow( Int val );
6244unsigned long int narrow( Int val );
6245
6246int ?==?( Int oper1, Int oper2 );               §\C{// comparison}§
6247int ?==?( Int oper1, long int oper2 );
6248int ?==?( long int oper2, Int oper1 );
6249int ?==?( Int oper1, unsigned long int oper2 );
6250int ?==?( unsigned long int oper2, Int oper1 );
6251
6252int ?!=?( Int oper1, Int oper2 );
6253int ?!=?( Int oper1, long int oper2 );
6254int ?!=?( long int oper1, Int oper2 );
6255int ?!=?( Int oper1, unsigned long int oper2 );
6256int ?!=?( unsigned long int oper1, Int oper2 );
6257
6258int ?<?( Int oper1, Int oper2 );
6259int ?<?( Int oper1, long int oper2 );
6260int ?<?( long int oper2, Int oper1 );
6261int ?<?( Int oper1, unsigned long int oper2 );
6262int ?<?( unsigned long int oper2, Int oper1 );
6263
6264int ?<=?( Int oper1, Int oper2 );
6265int ?<=?( Int oper1, long int oper2 );
6266int ?<=?( long int oper2, Int oper1 );
6267int ?<=?( Int oper1, unsigned long int oper2 );
6268int ?<=?( unsigned long int oper2, Int oper1 );
6269
6270int ?>?( Int oper1, Int oper2 );
6271int ?>?( Int oper1, long int oper2 );
6272int ?>?( long int oper1, Int oper2 );
6273int ?>?( Int oper1, unsigned long int oper2 );
6274int ?>?( unsigned long int oper1, Int oper2 );
6275
6276int ?>=?( Int oper1, Int oper2 );
6277int ?>=?( Int oper1, long int oper2 );
6278int ?>=?( long int oper1, Int oper2 );
6279int ?>=?( Int oper1, unsigned long int oper2 );
6280int ?>=?( unsigned long int oper1, Int oper2 );
6281
6282Int +?( Int oper );                                             §\C{// arithmetic}§
6283Int -?( Int oper );
6284Int ~?( Int oper );
6285
6286Int ?&?( Int oper1, Int oper2 );
6287Int ?&?( Int oper1, long int oper2 );
6288Int ?&?( long int oper1, Int oper2 );
6289Int ?&?( Int oper1, unsigned long int oper2 );
6290Int ?&?( unsigned long int oper1, Int oper2 );
6291Int ?&=?( Int * lhs, Int rhs );
6292
6293Int ?|?( Int oper1, Int oper2 );
6294Int ?|?( Int oper1, long int oper2 );
6295Int ?|?( long int oper1, Int oper2 );
6296Int ?|?( Int oper1, unsigned long int oper2 );
6297Int ?|?( unsigned long int oper1, Int oper2 );
6298Int ?|=?( Int * lhs, Int rhs );
6299
6300Int ?^?( Int oper1, Int oper2 );
6301Int ?^?( Int oper1, long int oper2 );
6302Int ?^?( long int oper1, Int oper2 );
6303Int ?^?( Int oper1, unsigned long int oper2 );
6304Int ?^?( unsigned long int oper1, Int oper2 );
6305Int ?^=?( Int * lhs, Int rhs );
6306
6307Int ?+?( Int addend1, Int addend2 );
6308Int ?+?( Int addend1, long int addend2 );
6309Int ?+?( long int addend2, Int addend1 );
6310Int ?+?( Int addend1, unsigned long int addend2 );
6311Int ?+?( unsigned long int addend2, Int addend1 );
6312Int ?+=?( Int * lhs, Int rhs );
6313Int ?+=?( Int * lhs, long int rhs );
6314Int ?+=?( Int * lhs, unsigned long int rhs );
6315Int ++?( Int * lhs );
6316Int ?++( Int * lhs );
6317
6318Int ?-?( Int minuend, Int subtrahend );
6319Int ?-?( Int minuend, long int subtrahend );
6320Int ?-?( long int minuend, Int subtrahend );
6321Int ?-?( Int minuend, unsigned long int subtrahend );
6322Int ?-?( unsigned long int minuend, Int subtrahend );
6323Int ?-=?( Int * lhs, Int rhs );
6324Int ?-=?( Int * lhs, long int rhs );
6325Int ?-=?( Int * lhs, unsigned long int rhs );
6326Int --?( Int * lhs );
6327Int ?--( Int * lhs );
6328
6329Int ?*?( Int multiplicator, Int multiplicand );
6330Int ?*?( Int multiplicator, long int multiplicand );
6331Int ?*?( long int multiplicand, Int multiplicator );
6332Int ?*?( Int multiplicator, unsigned long int multiplicand );
6333Int ?*?( unsigned long int multiplicand, Int multiplicator );
6334Int ?*=?( Int * lhs, Int rhs );
6335Int ?*=?( Int * lhs, long int rhs );
6336Int ?*=?( Int * lhs, unsigned long int rhs );
6337
6338Int ?/?( Int dividend, Int divisor );
6339Int ?/?( Int dividend, unsigned long int divisor );
6340Int ?/?( unsigned long int dividend, Int divisor );
6341Int ?/?( Int dividend, long int divisor );
6342Int ?/?( long int dividend, Int divisor );
6343Int ?/=?( Int * lhs, Int rhs );
6344Int ?/=?( Int * lhs, long int rhs );
6345Int ?/=?( Int * lhs, unsigned long int rhs );
6346
6347[ Int, Int ] div( Int dividend, Int divisor );
6348[ Int, Int ] div( Int dividend, unsigned long int divisor );
6349
6350Int ?%?( Int dividend, Int divisor );
6351Int ?%?( Int dividend, unsigned long int divisor );
6352Int ?%?( unsigned long int dividend, Int divisor );
6353Int ?%?( Int dividend, long int divisor );
6354Int ?%?( long int dividend, Int divisor );
6355Int ?%=?( Int * lhs, Int rhs );
6356Int ?%=?( Int * lhs, long int rhs );
6357Int ?%=?( Int * lhs, unsigned long int rhs );
6358
6359Int ?<<?( Int shiften, mp_bitcnt_t shift );
6360Int ?<<=?( Int * lhs, mp_bitcnt_t shift );
6361Int ?>>?( Int shiften, mp_bitcnt_t shift );
6362Int ?>>=?( Int * lhs, mp_bitcnt_t shift );
6363
6364Int abs( Int oper );                                    §\C{// number functions}§
6365Int fact( unsigned long int N );
6366Int gcd( Int oper1, Int oper2 );
6367Int pow( Int base, unsigned long int exponent );
6368Int pow( unsigned long int base, unsigned long int exponent );
6369void srandom( gmp_randstate_t state );
6370Int random( gmp_randstate_t state, mp_bitcnt_t n );
6371Int random( gmp_randstate_t state, Int n );
6372Int random( gmp_randstate_t state, mp_size_t max_size );
6373int sgn( Int oper );
6374Int sqrt( Int oper );
6375
6376forall( dtype istype | istream( istype ) ) istype * ?|?( istype * is, Int * mp );  §\C{// I/O}§
6377forall( dtype ostype | ostream( ostype ) ) ostype * ?|?( ostype * os, Int mp );
6378\end{cfa}
6379
6380The following factorial programs contrast using GMP with the \CFA and C interfaces, where the output from these programs appears in \VRef[Figure]{f:MultiPrecisionFactorials}.
6381(Compile with flag \Indexc{-lgmp} to link with the GMP library.)
6382\begin{quote2}
6383\begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
6384\multicolumn{1}{c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}}    & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}}      \\
6385\hline
6386\begin{cfa}
6387#include <gmp>§\indexc{gmp}§
6388int main( void ) {
6389        sout | "Factorial Numbers" | endl;
6390        Int fact = 1;
6391
6392        sout | 0 | fact | endl;
6393        for ( unsigned int i = 1; i <= 40; i += 1 ) {
6394                fact *= i;
6395                sout | i | fact | endl;
6396        }
6397}
6398\end{cfa}
6399&
6400\begin{cfa}
6401#include <gmp.h>§\indexc{gmp.h}§
6402int main( void ) {
6403        ®gmp_printf®( "Factorial Numbers\n" );
6404        ®mpz_t® fact;
6405        ®mpz_init_set_ui®( fact, 1 );
6406        ®gmp_printf®( "%d %Zd\n", 0, fact );
6407        for ( unsigned int i = 1; i <= 40; i += 1 ) {
6408                ®mpz_mul_ui®( fact, fact, i );
6409                ®gmp_printf®( "%d %Zd\n", i, fact );
6410        }
6411}
6412\end{cfa}
6413\end{tabular}
6414\end{quote2}
6415
6416\begin{figure}
6417\begin{cfa}
6418Factorial Numbers
64190 1
64201 1
64212 2
64223 6
64234 24
64245 120
64256 720
64267 5040
64278 40320
64289 362880
642910 3628800
643011 39916800
643112 479001600
643213 6227020800
643314 87178291200
643415 1307674368000
643516 20922789888000
643617 355687428096000
643718 6402373705728000
643819 121645100408832000
643920 2432902008176640000
644021 51090942171709440000
644122 1124000727777607680000
644223 25852016738884976640000
644324 620448401733239439360000
644425 15511210043330985984000000
644526 403291461126605635584000000
644627 10888869450418352160768000000
644728 304888344611713860501504000000
644829 8841761993739701954543616000000
644930 265252859812191058636308480000000
645031 8222838654177922817725562880000000
645132 263130836933693530167218012160000000
645233 8683317618811886495518194401280000000
645334 295232799039604140847618609643520000000
645435 10333147966386144929666651337523200000000
645536 371993326789901217467999448150835200000000
645637 13763753091226345046315979581580902400000000
645738 523022617466601111760007224100074291200000000
645839 20397882081197443358640281739902897356800000000
645940 815915283247897734345611269596115894272000000000
6460\end{cfa}
6461\caption{Multi-precision Factorials}
6462\label{f:MultiPrecisionFactorials}
6463\end{figure}
6464
6465
6466\section{Rational Numbers}
6467\label{s:RationalNumbers}
6468
6469Rational numbers are numbers written as a ratio, \ie as a fraction, where the numerator (top number) and the denominator (bottom number) are whole numbers.
6470When creating and computing with rational numbers, results are constantly reduced to keep the numerator and denominator as small as possible.
6471
6472\begin{cfa}[belowskip=0pt]
6473// implementation
6474struct Rational {§\indexc{Rational}§
6475        long int numerator, denominator;                                        // invariant: denominator > 0
6476}; // Rational
6477
6478Rational rational();                                    §\C{// constructors}§
6479Rational rational( long int n );
6480Rational rational( long int n, long int d );
6481void ?{}( Rational * r, zero_t );
6482void ?{}( Rational * r, one_t );
6483
6484long int numerator( Rational r );               §\C{// numerator/denominator getter/setter}§
6485long int numerator( Rational r, long int n );
6486long int denominator( Rational r );
6487long int denominator( Rational r, long int d );
6488
6489int ?==?( Rational l, Rational r );             §\C{// comparison}§
6490int ?!=?( Rational l, Rational r );
6491int ?<?( Rational l, Rational r );
6492int ?<=?( Rational l, Rational r );
6493int ?>?( Rational l, Rational r );
6494int ?>=?( Rational l, Rational r );
6495
6496Rational -?( Rational r );                              §\C{// arithmetic}§
6497Rational ?+?( Rational l, Rational r );
6498Rational ?-?( Rational l, Rational r );
6499Rational ?*?( Rational l, Rational r );
6500Rational ?/?( Rational l, Rational r );
6501
6502double widen( Rational r );                             §\C{// conversion}§
6503Rational narrow( double f, long int md );
6504
6505forall( dtype istype | istream( istype ) ) istype * ?|?( istype *, Rational * ); // I/O
6506forall( dtype ostype | ostream( ostype ) ) ostype * ?|?( ostype *, Rational );
6507\end{cfa}
6508
6509
6510\bibliographystyle{plain}
6511\bibliography{cfa}
6512
6513
6514\addcontentsline{toc}{section}{\indexname} % add index name to table of contents
6515\begin{theindex}
6516Italic page numbers give the location of the main entry for the referenced term.
6517Plain page numbers denote uses of the indexed term.
6518Entries for grammar non-terminals are italicized.
6519A typewriter font is used for grammar terminals and program identifiers.
6520\indexspace
6521\input{user.ind}
6522\end{theindex}
6523
6524
6525\end{document}
6526
6527% Local Variables: %
6528% tab-width: 4 %
6529% fill-column: 100 %
6530% compile-command: "make" %
6531% End: %
Note: See TracBrowser for help on using the repository browser.