Changeset 32490deb for doc/user/user.tex


Ignore:
Timestamp:
Jan 31, 2024, 6:40:25 PM (5 months ago)
Author:
JiadaL <j82liang@…>
Branches:
master
Children:
496ffc17
Parents:
c75b30a (diff), e71b09a (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'master' of plg.uwaterloo.ca:software/cfa/cfa-cc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/user/user.tex

    rc75b30a r32490deb  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Sun Jan 14 17:27:41 2024
    14 %% Update Count     : 5764
     13%% Last Modified On : Tue Jan 30 09:02:41 2024
     14%% Update Count     : 6046
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
    … …  
    4646%\input{common}                                                                                 % common CFA document macros
    4747\usepackage[dvips,plainpages=false,pdfpagelabels,pdfpagemode=UseNone,colorlinks=true,pagebackref=true,linkcolor=blue,citecolor=blue,urlcolor=blue,pagebackref=true,breaklinks=true]{hyperref}
     48\urlstyle{sf}
    4849\usepackage{breakurl}
    4950
    … …  
    163164
    164165\Index*[C++]{\CC{}}~\cite{c++:v1} had a similar goal 30 years ago, allowing object-oriented programming to be incrementally added to C.
    165 However, \CC currently has the disadvantages of a strong object-oriented bias, multiple legacy design-choices that are difficult to update, and active divergence of the language model from C, requiring significant effort and training to incrementally add \CC to a C-based project.
     166However, \CC currently has the disadvantages of a strong object-oriented bias, multiple legacy design-choices that are difficult to update, and active divergence of the language model from C, requiring significant effort and training to incrementally add \CC to a C code-base.
    166167In contrast, \CFA has 30 years of hindsight and a clean starting point.
    167168
    … …  
    200201\end{center}
    201202While \CFA I/O \see{\VRef{s:StreamIOLibrary}} looks similar to \Index*[C++]{\CC{}}, there are important differences, such as automatic spacing between variables and an implicit newline at the end of the expression list, similar to \Index*{Python}~\cite{Python}.
     203In general, \CFA programs are 10\% to 30\% shorter than their equivalent C/\CC counterparts.
    202204
    203205
    … …  
    218220Even with all its problems, C continues to be popular because it allows writing software at virtually any level in a computer system without restriction.
    219221For system programming, where direct access to hardware, storage management, and real-time issues are a requirement, C is the only language of choice.
    220 The TIOBE index~\cite{TIOBE} for February 2021 ranks the top six most \emph{popular} programming languages as C 17.4\%, \Index*{Java} 12\%, Python 12\%, \Index*[C++]{\CC{}} 7.6\%, \Csharp 4\%, Visual Basic 3.8\% = 56.8\%, where the next 50 languages are less than 2\% each, with a long tail.
     222The TIOBE index~\cite{TIOBE} for February 2023 ranks the top six most \emph{popular} programming languages as C 17.4\%, \Index*{Java} 12\%, Python 12\%, \Index*[C++]{\CC{}} 7.6\%, \Csharp 4\%, Visual Basic 3.8\% = 56.8\%, where the next 50 languages are less than 2\% each, with a long tail.
    221223The top 4 rankings over the past 35 years are:
    222224\begin{center}
    … …  
    238240however, it largely extended the C language, and did not address many of C's existing problems.\footnote{%
    239241Two 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.}
    240 \Index*{Fortran}~\cite{Fortran08}, \Index*{Cobol}~\cite{Cobol14}, and \Index*{Ada}~\cite{Ada12} 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.
     242\Index*{Fortran}~\cite{Fortran08}, \Index*{Cobol}~\cite{Cobol14}, and \Index*{Ada}~\cite{Ada16} 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.
    241243\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.
    242244These 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.
    … …  
    263265% extending the C type system with parametric polymorphism and overloading, as opposed to the \Index*[C++]{\CC{}} approach of object-oriented extensions.
    264266\CFA{}\hspace{1pt}'s polymorphism was originally formalized by \Index*{Glen Ditchfield}\index{Ditchfield, Glen}~\cite{Ditchfield92}, and first implemented by \Index*{Richard Bilson}\index{Bilson, Richard}~\cite{Bilson03}.
    265 However, at that time, there was little interesting in extending C, so work did not continue.
     267However, at that time, there was little interest in extending C, so work did not continue.
    266268As the saying goes, ``\Index*{What goes around, comes around.}'', and there is now renewed interest in the C programming language because of the legacy code-base, so the \CFA project was restarted in 2015.
    267269
    … …  
    272274\CFA is designed to integrate directly with existing C programs and libraries.
    273275The 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.
    274 This feature allows \CFA programmers to take advantage of the existing panoply of C libraries to access thousands of external software features.
     276This feature allows \CFA programmers to take advantage of the existing panoply of C libraries to access thousands of software features.
    275277Language developers often state that adequate \Index{library support} takes more work than designing and implementing the language itself.
    276278Fortunately, \CFA, like \Index*[C++]{\CC{}}, starts with immediate access to all exiting C libraries, and in many cases, can easily wrap library routines with simpler and safer interfaces, at zero or very low cost.
    … …  
    320322However, it is necessary to differentiate between C and \CFA code because of name \Index{overload}ing, as for \CC.
    321323For 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©.
    322 Whereas, \CFA wraps each of these routines into one overloaded name ©abs©:
    323 \begin{cfa}
    324 char ®abs®( char );
    325 extern "C" { int ®abs®( int ); } §\C{// use default C routine for int}§
    326 long int ®abs®( long int );
    327 long long int ®abs®( long long int );
    328 float ®abs®( float );
    329 double ®abs®( double );
    330 long double ®abs®( long double );
    331 float _Complex ®abs®( float _Complex );
    332 double _Complex ®abs®( double _Complex );
    333 long double _Complex ®abs®( long double _Complex );
     324Whereas, \CFA wraps these routines into one overloaded name ©abs©:
     325\begin{cfa}
     326unsigned char ®abs®( signed char );                             §\C[3.5in]{// no C equivalent}§
     327extern "C" { int ®abs®( int ); }                                §\C{// C abs}§
     328unsigned long int ®abs®( long int );                    §\C{// C labs}§
     329unsigned long long int ®abs®( long long int );  §\C{// C llabs}§
     330float ®abs®( float );                                                   §\C{// C fabsf}§
     331double ®abs®( double );                                                 §\C{// C fabs}§
     332long double ®abs®( long double );                               §\C{// C fabsl}§
     333float _Complex ®abs®( float _Complex );                 §\C{// C cabsf}§
     334double _Complex ®abs®( double _Complex );               §\C{// C cabs}§
     335long double _Complex ®abs®( long double _Complex ); §\C{// C cabsl}\CRT§
    334336\end{cfa}
    335337The problem is a \Index{name clash} between the C name ©abs© and the \CFA names ©abs©, resulting in two name linkages\index{C linkage}: ©extern "C"© and ©extern "Cforall"© (default).
    … …  
    339341
    340342This example illustrates a core idea in \CFA: \emph{the \Index{power of a name}}.
    341 The name ``©abs©'' evokes the notion of absolute value, and many mathematical types provide the notion of absolute value.
    342 Hence, knowing the name ©abs© is sufficient to apply it to any type where it is applicable.
     343The name ``©abs©'' evokes the notion of absolute value and many mathematical types provide the notion of absolute value.
     344Hence, knowing the name ©abs© is sufficient to apply it to any applicable type.
    343345The time savings and safety of using one name uniformly versus $N$ unique names cannot be underestimated.
    344346
    345347
    346348\section{\CFA Compilation}
     349
     350\CFA is a \newterm{transpiler}, meaning it reads in a programming language (\CFA) as input and generates another programming language (C) as output, whereas a \newterm{compiler} reads in a programming language and generates assembler/machine code.
     351Hence, \CFA is like the C preprocessor modifying a program and sending it on to another step for further transformation.
     352The order of transformation is C preprocessor, \CFA, and finally GNU C compiler, which also has a number of transformation steps, such as assembler and linker.
    347353
    348354The command ©cfa© is used to compile a \CFA program and is based on the \Index{GNU} \Indexc{gcc} command, \eg:
    … …  
    444450which conditionally includes the correct header file, if the program is compiled using \Indexc{gcc} or \Indexc{cfa}.
    445451
    446 The \CFA translator has multiple steps.
    447 The following flags control how the translator works, the stages run, and printing within a stage.
     452The \CFA \Index{transpiler} has multiple internal steps.
     453The following flags control how the \CFA transpiler works, the stages run, and printing within a stage.
    448454The majority of these flags are used by \CFA developers, but some are occasionally useful to programmers.
    449 Each option must be escaped with \Indexc{-XCFA}\index{translator option!-XCFA@{©-XCFA©}} to direct it to the compiler step, similar to the ©-Xlinker© flag for the linker, \eg:
     455Each option must be escaped with \Indexc{-XCFA}\index{transpiler option!-XCFA@{©-XCFA©}} to direct it to the \CFA compilation step, similar to the ©-Xlinker© flag for the linker, \eg:
    450456\begin{lstlisting}[language=sh]
    451457cfa §test§.cfa -CFA -XCFA -p # print translated code without printing the standard prelude
    … …  
    458464\begin{description}[topsep=5pt,itemsep=0pt,parsep=0pt]
    459465\item
    460 \Indexc{-c}\index{translator option!-c@{©-c©}}, \Indexc{--colors}\index{translator option!--colors@{©--colors©}} \, diagnostic color: ©never©, ©always©, \lstinline[deletekeywords=auto]{auto}
    461 \item
    462 \Indexc{-g}\index{translator option!-g@{©-g©}}, \Indexc{--gdb}\index{translator option!--gdb@{©--gdb©}} \, wait for gdb to attach
    463 \item
    464 \Indexc{-h}\index{translator option!-h@{©-h©}}, \Indexc{--help}\index{translator option!--help@{©--help©}} \, print translator help message
    465 \item
    466 \Indexc{-i}\index{translator option!-i@{©-i©}}, \Indexc{--invariant}\index{translator option!--invariant@{©--invariant©}} \, invariant checking during AST passes
    467 \item
    468 \Indexc{-l}\index{translator option!-l@{©-l©}}, \Indexc{--libcfa}\index{translator option!--libcfa@{©--libcfa©}} \, generate ©libcfa.c©
    469 \item
    470 \Indexc{-L}\index{translator option!-L@{©-L©}}, \Indexc{--linemarks}\index{translator option!--linemarks@{©--linemarks©}} \, generate line marks
    471 \item
    472 \Indexc{-m}\index{translator option!-m@{©-m©}}, \Indexc{--no-main}\index{translator option!--no-main@{©--no-main©}} \, do not replace main
    473 \item
    474 \Indexc{-N}\index{translator option!-N@{©-N©}}, \Indexc{--no-linemarks}\index{translator option!--no-linemarks@{©--no-linemarks©}} \, do not generate line marks
    475 \item
    476 \Indexc{-n}\index{translator option!-n@{©-n©}}, \Indexc{--no-prelude}\index{translator option!--no-prelude@{©--no-prelude©}} \, do not read prelude
    477 \item
    478 \Indexc{-p}\index{translator option!-p@{©-p©}}, \Indexc{--prototypes}\index{translator option!--prototypes@{©--prototypes©}} \, do not generate prelude prototypes $\Rightarrow$ prelude not printed
    479 \item
    480 \Indexc{-d}\index{translator option!-d@{©-d©}}, \Indexc{--deterministic-out}\index{translator option!--deterministic-out@{©--deterministic-out©}} \, only print deterministic output
    481 \item
    482 \Indexc{-P}\index{translator option!-P@{©-P©}}, \Indexc{--print}\index{translator option!--print@{©--print©}} \, one of:
     466\Indexc{-c}\index{transpiler option!-c@{©-c©}}, \Indexc{--colors}\index{transpiler option!--colors@{©--colors©}} \, diagnostic color: ©never©, ©always©, \lstinline[deletekeywords=auto]{auto}
     467\item
     468\Indexc{-g}\index{transpiler option!-g@{©-g©}}, \Indexc{--gdb}\index{transpiler option!--gdb@{©--gdb©}} \, wait for gdb to attach
     469\item
     470\Indexc{-h}\index{transpiler option!-h@{©-h©}}, \Indexc{--help}\index{transpiler option!--help@{©--help©}} \, print transpiler help message
     471\item
     472\Indexc{-i}\index{transpiler option!-i@{©-i©}}, \Indexc{--invariant}\index{transpiler option!--invariant@{©--invariant©}} \, invariant checking during AST passes
     473\item
     474\Indexc{-l}\index{transpiler option!-l@{©-l©}}, \Indexc{--libcfa}\index{transpiler option!--libcfa@{©--libcfa©}} \, generate ©libcfa.c©
     475\item
     476\Indexc{-L}\index{transpiler option!-L@{©-L©}}, \Indexc{--linemarks}\index{transpiler option!--linemarks@{©--linemarks©}} \, generate line marks
     477\item
     478\Indexc{-m}\index{transpiler option!-m@{©-m©}}, \Indexc{--no-main}\index{transpiler option!--no-main@{©--no-main©}} \, do not replace main
     479\item
     480\Indexc{-N}\index{transpiler option!-N@{©-N©}}, \Indexc{--no-linemarks}\index{transpiler option!--no-linemarks@{©--no-linemarks©}} \, do not generate line marks
     481\item
     482\Indexc{-n}\index{transpiler option!-n@{©-n©}}, \Indexc{--no-prelude}\index{transpiler option!--no-prelude@{©--no-prelude©}} \, do not read prelude
     483\item
     484\Indexc{-p}\index{transpiler option!-p@{©-p©}}, \Indexc{--prototypes}\index{transpiler option!--prototypes@{©--prototypes©}} \, do not generate prelude prototypes $\Rightarrow$ prelude not printed
     485\item
     486\Indexc{-d}\index{transpiler option!-d@{©-d©}}, \Indexc{--deterministic-out}\index{transpiler option!--deterministic-out@{©--deterministic-out©}} \, only print deterministic output
     487\item
     488\Indexc{-P}\index{transpiler option!-P@{©-P©}}, \Indexc{--print}\index{transpiler option!--print@{©--print©}} \, one of:
    483489\begin{description}[topsep=0pt,itemsep=0pt,parsep=0pt]
    484490\item
    485 \Indexc{ascodegen}\index{translator option!-P@{©-P©}!©ascodegen©}\index{translator option!--print@{©-print©}!©ascodegen©} \, print AST as codegen rather than AST
    486 \item
    487 \Indexc{asterr}\index{translator option!-P@{©-P©}!©asterr©}\index{translator option!--print@{©-print©}!©asterr©} \, print AST on error
    488 \item
    489 \Indexc{declstats}\index{translator option!-P@{©-P©}!©declstats©}\index{translator option!--print@{©-print©}!©declstats©} \, print code property statistics
    490 \item
    491 \Indexc{parse}\index{translator option!-P@{©-P©}!©parse©}\index{translator option!--print@{©-print©}!©parse©} \, print yacc (parsing) debug information
    492 \item
    493 \Indexc{pretty}\index{translator option!-P@{©-P©}!©pretty©}\index{translator option!--print@{©-print©}!©pretty©} \, prettyprint for ©ascodegen© flag
    494 \item
    495 \Indexc{rproto}\index{translator option!-P@{©-P©}!©rproto©}\index{translator option!--print@{©-print©}!©rproto©} \, resolver-proto instance
    496 \item
    497 \Indexc{rsteps}\index{translator option!-P@{©-P©}!©rsteps©}\index{translator option!--print@{©-print©}!©rsteps©} \, print resolver steps
    498 \item
    499 \Indexc{ast}\index{translator option!-P@{©-P©}!©ast©}\index{translator option!--print@{©-print©}!©ast©} \, print AST after parsing
    500 \item
    501 \Indexc{excpdecl}\index{translator option!-P@{©-P©}!©excpdecl©}\index{translator option!--print@{©-print©}!©excpdecl©} \, print AST after translating exception decls
    502 \item
    503 \Indexc{symevt}\index{translator option!-P@{©-P©}!©symevt©}\index{translator option!--print@{©-print©}!©symevt©} \, print AST after symbol table events
    504 \item
    505 \Indexc{expralt}\index{translator option!-P@{©-P©}!©expralt©}\index{translator option!--print@{©-print©}!©expralt©} \, print AST after expressions alternatives
    506 \item
    507 \Indexc{valdecl}\index{translator option!-P@{©-P©}!©valdecl©}\index{translator option!--print@{©-print©}!©valdecl©} \, print AST after declaration validation pass
    508 \item
    509 \Indexc{bresolver}\index{translator option!-P@{©-P©}!©bresolver©}\index{translator option!--print@{©-print©}!©bresolver©} \, print AST before resolver step
    510 \item
    511 \Indexc{expranly}\index{translator option!-P@{©-P©}!©expranly©}\index{translator option!--print@{©-print©}!©expranly©} \, print AST after expression analysis
    512 \item
    513 \Indexc{ctordtor}\index{translator option!-P@{©-P©}!©ctordtor©}\index{translator option!--print@{©-print©}!©ctordtor©} \, print AST after ctor/dtor are replaced
    514 \item
    515 \Indexc{tuple}\index{translator option!-P@{©-P©}!©tuple©}\index{translator option!--print@{©-print©}!©tuple©} \, print AST after tuple expansion
    516 \item
    517 \Indexc{instgen}\index{translator option!-P@{©-P©}!©instgen©}\index{translator option!--print@{©-print©}!©instgen©} \, print AST after instantiate generics
    518 \item
    519 \Indexc{bbox}\index{translator option!-P@{©-P©}!©bbox©}\index{translator option!--print@{©-print©}!©bbox©} \, print AST before box pass
    520 \item
    521 \Indexc{bcodegen}\index{translator option!-P@{©-P©}!©bcodegen©}\index{translator option!--print@{©-print©}!©bcodegen©} \, print AST before code generation
     491\Indexc{ascodegen}\index{transpiler option!-P@{©-P©}!©ascodegen©}\index{transpiler option!--print@{©-print©}!©ascodegen©} \, print AST as codegen rather than AST
     492\item
     493\Indexc{asterr}\index{transpiler option!-P@{©-P©}!©asterr©}\index{transpiler option!--print@{©-print©}!©asterr©} \, print AST on error
     494\item
     495\Indexc{declstats}\index{transpiler option!-P@{©-P©}!©declstats©}\index{transpiler option!--print@{©-print©}!©declstats©} \, print code property statistics
     496\item
     497\Indexc{parse}\index{transpiler option!-P@{©-P©}!©parse©}\index{transpiler option!--print@{©-print©}!©parse©} \, print yacc (parsing) debug information
     498\item
     499\Indexc{pretty}\index{transpiler option!-P@{©-P©}!©pretty©}\index{transpiler option!--print@{©-print©}!©pretty©} \, prettyprint for ©ascodegen© flag
     500\item
     501\Indexc{rproto}\index{transpiler option!-P@{©-P©}!©rproto©}\index{transpiler option!--print@{©-print©}!©rproto©} \, resolver-proto instance
     502\item
     503\Indexc{rsteps}\index{transpiler option!-P@{©-P©}!©rsteps©}\index{transpiler option!--print@{©-print©}!©rsteps©} \, print resolver steps
     504\item
     505\Indexc{ast}\index{transpiler option!-P@{©-P©}!©ast©}\index{transpiler option!--print@{©-print©}!©ast©} \, print AST after parsing
     506\item
     507\Indexc{excpdecl}\index{transpiler option!-P@{©-P©}!©excpdecl©}\index{transpiler option!--print@{©-print©}!©excpdecl©} \, print AST after translating exception decls
     508\item
     509\Indexc{symevt}\index{transpiler option!-P@{©-P©}!©symevt©}\index{transpiler option!--print@{©-print©}!©symevt©} \, print AST after symbol table events
     510\item
     511\Indexc{expralt}\index{transpiler option!-P@{©-P©}!©expralt©}\index{transpiler option!--print@{©-print©}!©expralt©} \, print AST after expressions alternatives
     512\item
     513\Indexc{valdecl}\index{transpiler option!-P@{©-P©}!©valdecl©}\index{transpiler option!--print@{©-print©}!©valdecl©} \, print AST after declaration validation pass
     514\item
     515\Indexc{bresolver}\index{transpiler option!-P@{©-P©}!©bresolver©}\index{transpiler option!--print@{©-print©}!©bresolver©} \, print AST before resolver step
     516\item
     517\Indexc{expranly}\index{transpiler option!-P@{©-P©}!©expranly©}\index{transpiler option!--print@{©-print©}!©expranly©} \, print AST after expression analysis
     518\item
     519\Indexc{ctordtor}\index{transpiler option!-P@{©-P©}!©ctordtor©}\index{transpiler option!--print@{©-print©}!©ctordtor©} \, print AST after ctor/dtor are replaced
     520\item
     521\Indexc{tuple}\index{transpiler option!-P@{©-P©}!©tuple©}\index{transpiler option!--print@{©-print©}!©tuple©} \, print AST after tuple expansion
     522\item
     523\Indexc{instgen}\index{transpiler option!-P@{©-P©}!©instgen©}\index{transpiler option!--print@{©-print©}!©instgen©} \, print AST after instantiate generics
     524\item
     525\Indexc{bbox}\index{transpiler option!-P@{©-P©}!©bbox©}\index{transpiler option!--print@{©-print©}!©bbox©} \, print AST before box pass
     526\item
     527\Indexc{bcodegen}\index{transpiler option!-P@{©-P©}!©bcodegen©}\index{transpiler option!--print@{©-print©}!©bcodegen©} \, print AST before code generation
    522528\end{description}
    523529\item
    524530\Indexc{--prelude-dir} <directory> \, prelude directory for debug/nodebug
    525531\item
    526 \Indexc{-S}\index{translator option!-S@{©-S©}!©counters,heap,time,all,none©}, \Indexc{--statistics}\index{translator option!--statistics@{©--statistics©}!©counters,heap,time,all,none©} <option-list> \, enable profiling information: ©counters©, ©heap©, ©time©, ©all©, ©none©
    527 \item
    528 \Indexc{-t}\index{translator option!-t@{©-t©}}, \Indexc{--tree}\index{translator option!--tree@{©--tree©}} build in tree
     532\Indexc{-S}\index{transpiler option!-S@{©-S©}!©counters,heap,time,all,none©}, \Indexc{--statistics}\index{transpiler option!--statistics@{©--statistics©}!©counters,heap,time,all,none©} <option-list> \, enable profiling information: ©counters©, ©heap©, ©time©, ©all©, ©none©
     533\item
     534\Indexc{-t}\index{transpiler option!-t@{©-t©}}, \Indexc{--tree}\index{transpiler option!--tree@{©--tree©}} build in tree
    529535\end{description}
    530536
    … …  
    540546\end{cfa}
    541547Existing C programs with keyword clashes can be converted by prefixing the keyword identifiers with double backquotes, and eventually the identifier name can be changed to a non-keyword name.
    542 \VRef[Figure]{f:HeaderFileInterposition} shows how clashes in existing C header-files \see{\VRef{s:StandardHeaders}} can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©.
    543 Several common C header-files with keyword clashes are fixed in the standard \CFA header-library, so there is a seamless programming-experience.
     548\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in existing C header-files \see{\VRef{s:StandardHeaders}} can be handled using preprocessor \newterm{interposition}: ©#include_next© and command-line ©-I filename©.
     549Several common C header-files with keyword clashes are fixed in the standard \CFA header-library, so there is largely a seamless programming-experience.
    544550
    545551\begin{figure}
    … …  
    591597the type suffixes ©U©, ©L©, \etc may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
    592598\end{enumerate}
    593 It is significantly easier to read and enter long constants when they are broken up into smaller groupings (many cultures use comma and/or period among digits for the same purpose).
     599It is significantly easier to read and enter long constants when they are broken up into smaller groupings (most cultures use comma and/or period among digits for the same purpose).
    594600This extension is backwards compatible, matches with the use of underscore in variable names, and appears in \Index*{Ada} and \Index*{Java} 8.
    595601\CC uses the single quote (©'©) as a separator, restricted within a sequence of digits, \eg ©0xaa©©'©©ff©, ©3.141©©'©©592E1©©'©©1©.
     602However, the drawback of the \CC approach is difficults parsing for IDEs between character and numeric constants, as quotes are no longer balanced (©'x'© and ©3.14©©'©©159©).
    596603
    597604
    598605\section{Exponentiation Operator}
    599606
    600 C, \CC, and Java (and other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow(x,y)}, to perform the exponentiation operation.
     607C, \CC, and Java (and other programming languages) have \emph{no} exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow(x,y)}, to perform the exponentiation operation.
    601608\CFA extends the basic operators with the exponentiation operator ©?©\R{©\\©}©?©\index{?\\?@©?@\@?©} and ©?©\R{©\\©}©=?©\index{?\\=?@©@\@=?©}, as in, ©x ©\R{©\\©}© y© and ©x ©\R{©\\©}©= y©, which means $x^y$ and $x \leftarrow x^y$.
    602609The 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©.
    603610
    604611There are exponentiation operators for integral and floating types, including the builtin \Index{complex} types.
    605 Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication ($O(\log y)$ multiplies or shifting if the exponent is 2).
     612Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication ($O(\log y)$ or shifting if the exponent is 2).
    606613Overflow for a large exponent or negative exponent returns zero.
    607614Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the exponent cannot be negative.
    … …  
    620627T ?®\®?( T ep, unsigned long int y );
    621628\end{cfa}
    622 A user type ©T© must define multiplication, one (©1©), and ©*©.
     629A user type ©T© must define one (©1©), and multiplication (©*©) \see{\VRef{s:Operator}}.
    623630
    624631
    … …  
    631638\subsection{\texorpdfstring{\LstKeywordStyle{if} / \LstKeywordStyle{while} Statement}{if / while Statement}}
    632639
    633 The \Indexc{if}/\Indexc{while} expression allows declarations, similar to \Indexc{for} declaration expression.\footnote{
     640The \Indexc{if} and \Indexc{while} expressions are extended with declarations, similar to the \Indexc{for} declaration expression.\footnote{
    634641Declarations in the \Indexc{do}-©while© condition are not useful because they appear after the loop body.}
    635642\begin{cfa}
    … …  
    653660\label{s:caseClause}
    654661
    655 C restricts a \Indexc{case} clause in \Indexc{switch} statement to a single value.
     662C restricts the \Indexc{case} clause in a \Indexc{switch} statement to a single value.
    656663For multiple ©case© clauses prefixing a statement within the ©switch© statement, it is necessary to have multiple ©case© clauses rather than multiple values.
    657664Requiring a ©case© clause for each value is not in the spirit of brevity normally associated with C.
    … …  
    688695\end{tabular}
    689696\end{cquote}
    690 In addition, subranges are allowed to specify case values.
     697In addition, subranges are allowed to specify a contiguous set of case values.
    691698\begin{cquote}
    692699\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{\hspace{2em}}l@{}}
    … …  
    801808\end{cfa}
    802809This situation is better handled by a list of case values \see{\VRef{s:caseClause}}.
    803 While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive to many programmers and is different from most programming languages with a ©switch© statement.
    804 Hence, default fall-through semantics results in a many programming errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
     810
     811While fall-through itself is not a problem, the problem occurs when fall-through is the default, as this semantics is unintuitive for many programmers and is different from most programming languages with a ©switch© statement.
     812Hence, default fall-through semantics results in programming errors as programmers often \emph{forget} the ©break© statement at the end of a ©case© clause, resulting in inadvertent fall-through.
    805813
    806814\item
    … …  
    819827The technical problem results from the inability to ensure declaration and initialization of variables when blocks are not entered at the beginning.
    820828There are few arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
    821 
    822829This C idiom is known as ``\Index*{Duff's device}''~\cite{Duff83}, from this example:
    823830\begin{cfa}
    … …  
    9961003with the current \Indexc{switch}/\Indexc{choose} statement.
    9971004
     1005
     1006\subsection{Loop Control}
     1007
     1008Looping a fixed number of times, possibly with a loop index, occurs frequently.
     1009\CFA condenses simply looping to facilitate coding speed and safety~\see{examples in \VRef[Figure]{f:LoopControlExamples}}.
     1010
     1011The \Indexc{for}, \Indexc{while}, and \Indexc{do} loop-control are extended to allow an empty conditional, which implies a comparison value of ©1© (true).
     1012\begin{cfa}
     1013while ( ®/* empty */®  )                                §\C{// while ( true )}§
     1014for ( ®/* empty */®  )                                  §\C{// for ( ; true; )}§
     1015do ... while ( ®/* empty */®  )                 §\C{// do ... while ( true )}§
     1016\end{cfa}
     1017
    9981018\begin{figure}
    9991019\begin{tabular}{@{}l@{\hspace{50pt}}|l@{}}
    … …  
    10031023while () { sout | "empty"; break; }
    10041024do { sout | "empty"; break; } while ();
    1005 for () { sout | "empty"; break; }                                                       §\C[3in]{sout | nl | nlOff;}§
     1025for () { sout | "empty"; break; }                                                       §\C{sout | nl | nlOff;}§
    10061026
    10071027for ( 0 ) { sout | "A"; } sout | "zero";                                        §\C{sout | nl;}§
    … …  
    10451065for ( i; 5 : j; @ -~ -5 ~ 2 : k; 1.5 ~ @ ) { sout | i | j | k; } §\C{sout | nl;}§
    10461066for ( i; 5 : j; @ -~ -5 ~ 2 : k; 1.5 ~ @ ) { sout | i | j | k; } §\C{sout | nl;}§
    1047 for ( i; 5 : k; 1.5 ~ @ : j; @ -~ -5 ~ 2 ) { sout | i | j | k; } §\C{sout | nl;}\CRT§
     1067for ( i; 5 : k; 1.5 ~ @ : j; @ -~ -5 ~ 2 ) { sout | i | j | k; } §\C{sout | nl;}§
    10481068\end{cfa}
    10491069&
    … …  
    11081128% for ( T i ; 3~9 ) => for ( T i = 3 ; i < 9; i += 1 ) // using 1
    11091129
    1110 
    1111 \subsection{Loop Control}
    1112 
    1113 Looping a fixed number of times, possibly with a loop index, occurs frequently.
    1114 \CFA condenses simply looping to facilitate coding speed and safety~\see{examples in \VRef[Figure]{f:LoopControlExamples}}.
    1115 
    1116 The \Indexc{for}, \Indexc{while}, and \Indexc{do} loop-control allow an empty conditional, which implies a comparison value of ©1© (true).
    1117 \begin{cfa}
    1118 while ( ®/* empty */®  )                                §\C{// while ( true )}§
    1119 for ( ®/* empty */®  )                                  §\C{// for ( ; true; )}§
    1120 do ... while ( ®/* empty */®  )                 §\C{// do ... while ( true )}§
    1121 \end{cfa}
    1122 
    1123 The ©for© control has 4 new loop-control operators that are not overloadable:
     1130The ©for© control is extended with 4 new loop-control operators, which are not overloadable:
    11241131\begin{description}[itemsep=0pt,parsep=0pt]
    11251132\item
    … …  
    11951202Similarly, the high value cannot be elided is an anonymous loop index (©1 ~ @©), as there is no index to stop the loop.
    11961203\item
    1197 ©:© means low another index.
     1204©:© means add another index.
    11981205\begin{cfa}
    11991206for ( i; 5 ®:® j; 2 ~ 12 ~ 3 )                  §\C{// for ( typeof(i) i = 1, j = 2; i < 5 \&\& j < 12; i += 1, j += 3 )}§
    … …  
    12121219\subsection{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break} Statement}{Labelled continue / break Statement}}
    12131220
    1214 C \Indexc{continue} and \Indexc{break} statements, for altering control flow, are restricted to one level of nesting for a particular control structure.
     1221C \Indexc{continue} and \Indexc{break} statements are restricted to one level of nesting for a particular control structure.
    12151222This restriction forces programmers to use \Indexc{goto} to achieve the equivalent control-flow for more than one level of nesting.
    12161223To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@©continue©!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@©break©!labelled}\index{labelled!break@©break©} with a target label to support static multi-level exit\index{multi-level exit}\index{static multi-level exit}~\cite{Buhr85}, as in Java.
    … …  
    13021309Furthermore, the location of the label at the \emph{beginning} of the target control structure informs the reader (\Index{eye candy}) that complex control-flow is occurring in the body of the control structure.
    13031310With ©goto©, the label is at the end of the control structure, which fails to convey this important clue early enough to the reader.
    1304 Finally, using an explicit target for the transfer instead of an implicit target allows new constructs to be added or removed without affecting existing constructs.
     1311Finally, using an explicit target for the transfer, instead of an implicit target, allows new constructs to be added or removed without affecting existing constructs.
    13051312Otherwise, the implicit targets of the current ©continue© and ©break©, \ie the closest enclosing loop or ©switch©, change as certain constructs are added or removed.
    13061313
    … …  
    13731380\begin{cfa}
    13741381Person p
    1375 ®p.®name; ®p.®address; ®p.®sex;                 §\C{// access containing fields}§
     1382®p.®name ...;  ®p.®address ...;  ®p.®sex ...; §\C{// access containing fields}§
    13761383\end{cfa}
    13771384which extends to multiple levels of qualification for nested aggregates and multiple aggregates.
    13781385\begin{cfa}
    13791386struct Ticket { ... } t;
    1380 ®p.name®.first; ®p.address®.street;             §\C{// access nested fields}§
    1381 ®t.®departure; ®t.®cost;                                §\C{// access multiple aggregate}§
     1387®p.name®.first ...;  ®p.address®.street ...; §\C{// access nested fields}§
     1388®t.®departure ...;  ®t.®cost ...;               §\C{// access multiple aggregate}§
    13821389\end{cfa}
    13831390Repeated aggregate qualification is tedious and makes code difficult to read.
    … …  
    15581565
    15591566
    1560 \section{Non-local Exception}
     1567\subsection{Non-local Exception}
    15611568
    15621569\begin{cfa}
    … …  
    23472354\subsection{Implicit String Conversions}
    23482355
    2349 The types ©char©, ©char *©, ©int©, ©double©, ©_Complex©, including signness and different sizes, implicitly convert to type ©string©.
    2350 \VRef[Figure]{f:ImplicitStringConversions} shows examples of implicit conversion between C strings, integral, floating-point and complex types to ©string©
    2351 The implicit conversions can be specified explicitly, as in:
    2352 \begin{cfa}
    2353 s = string( "abc" );            // converts char * to string
    2354 s = string( 5 );                        // converts int to string
    2355 s = string( 5.5 );                      // converts double to string
    2356 \end{cfa}
    2357 Conversions from ©string© to ©char *© are supported but with restrictions.
    2358 Explicit As well, when a string is converted to a ©char *©, the storage for the ©char *© is created by the conversion operation, which must be subsequently deleted:
    2359 \begin{cfa}
    2360 string x = "abc";
    2361 char *p = x;                            // convert from string to char *
    2362 ...
    2363 delete p;                                       // free storage created for p
    2364 \end{cfa}
     2356The types ©char©, ©char *©, ©int©, ©double©, ©_Complex©, including different signness and sizes, implicitly convert to type ©string©.
     2357\VRef[Figure]{f:ImplicitConversionsString} shows examples of implicit conversions between C strings, integral, floating-point and complex types to ©string©.
     2358A conversions can be explicitly specified:
     2359\begin{cfa}
     2360s = string( "abc" );                            §\C{// converts char * to string}§
     2361s = string( 5 );                                        §\C{// converts int to string}§
     2362s = string( 5.5 );                                      §\C{// converts double to string}§
     2363\end{cfa}
     2364All conversions from ©string© to ©char *©, attempt to be safe:
     2365either by requiring the maximum length of the ©char *© storage (©strncpy©) or allocating the ©char *© storage for the string characters (ownership), meaning the programmer must free the storage.
     2366As well, a string is always null terminates, implying a minimum size of 1 character.
     2367\begin{cquote}
     2368\begin{tabular}{@{}l@{\hspace{1.75in}}|@{\hspace{15pt}}l@{}}
     2369\begin{cfa}
     2370string s = "abcde";
     2371char cs[3];
     2372strncpy( cs, s, sizeof(cs) );           §\C{sout | cs;}§
     2373char * cp = s;                                          §\C{sout | cp;}§
     2374delete( cp );
     2375cp = s + ' ' + s;                                       §\C{sout | cp;}§
     2376delete( cp );
     2377\end{cfa}
     2378&
     2379\begin{cfa}
     2380
     2381
     2382ab
     2383abcde
     2384
     2385abcde abcde
     2386
     2387\end{cfa}
     2388\end{tabular}
     2389\end{cquote}
    23652390
    23662391\begin{figure}
    … …  
    23702395        string s;
    23712396        // conversion of char and char * to string
    2372         s = 'x';                                                §\CD{sout | s;}§
    2373         s = "abc";                                              §\CD{sout | s;}§
     2397        s = 'x';                                                §\C{sout | s;}§
     2398        s = "abc";                                              §\C{sout | s;}§
    23742399        char cs[5] = "abc";
    2375         s = cs;                                                 §\CD{sout | s;}§
     2400        s = cs;                                                 §\C{sout | s;}§
    23762401        // conversion of integral, floating-point, and complex to string
    2377         s = 45hh;                                               §\CD{sout | s;}§
    2378         s = 45h;                                                §\CD{sout | s;}§
    2379         s = -(ssize_t)MAX - 1;                  §\CD{sout | s;}§
    2380         s = (size_t)MAX;                                §\CD{sout | s;}§
    2381         s = 5.5;                                                §\CD{sout | s;}§
    2382         s = 5.5L;                                               §\CD{sout | s;}§
    2383         s = 5.5+3.4i;                                   §\CD{sout | s;}§
    2384         s = 5.5L+3.4Li;                                 §\CD{sout | s;}§
    2385         // safe conversion from string to char *
    2386         strncpy( cs, s, sizeof(cs) );   §\CD{sout | cs;}§
    2387         char * cp = s;                                  §\CD{sout | cp; // ownership}§
    2388         delete( cp );
    2389         cp = s + ' ' + s;                               §\CD{sout | cp; // ownership}§
    2390         delete( cp );
     2402        s = 45hh;                                               §\C{sout | s;}§
     2403        s = 45h;                                                §\C{sout | s;}§
     2404        s = -(ssize_t)MAX - 1;                  §\C{sout | s;}§
     2405        s = (size_t)MAX;                                §\C{sout | s;}§
     2406        s = 5.5;                                                §\C{sout | s;}§
     2407        s = 5.5L;                                               §\C{sout | s;}§
     2408        s = 5.5+3.4i;                                   §\C{sout | s;}§
     2409        s = 5.5L+3.4Li;                                 §\C{sout | s;}§
    23912410\end{cfa}
    23922411&
    … …  
    240824275.5+3.4i
    240924285.5+3.4i
    2410 
    2411 5.5+
    2412 5.5+3.4i
    2413 
    2414 5.5+3.4i 5.5+3.4i
    2415 
    24162429\end{cfa}
    24172430\end{tabular}
    2418 \caption{Implicit String Conversions}
    2419 \label{f:ImplicitStringConversions}
     2431\caption{Implicit Conversions to String}
     2432\label{f:ImplicitConversionsString}
    24202433\end{figure}
    24212434
    24222435
     2436\subsection{Size (length)}
     2437
     2438The ©size© operation returns the length of a string.
     2439\begin{cfa}
     2440i = size( "" );                                         §\C{// i is assigned 0}§
     2441i = size( "abc" );                                      §\C{// i is assigned 3}§
     2442i = size( peter );                                      §\C{// i is assigned 5}§
     2443\end{cfa}
     2444
     2445
    24232446\subsection{Comparison Operators}
    24242447
    2425 The binary relational and equality operators ©<©, ©<=©, ©>©, ©>=©, ©==©, ©!=© compare ©string© using lexicographical ordering, where longer strings are greater than shorter strings.
     2448The binary \Index{relational operator}s, ©<©, ©<=©, ©>©, ©>=©, and \Index{equality operator}s, ©==©, ©!=©, compare strings using lexicographical ordering, where longer strings are greater than shorter strings.
    24262449
    24272450
    24282451\subsection{Concatenation}
    24292452
    2430 The binary operator ©+© concatenates two strings.
    2431 \begin{cfa}
    2432 s = peter + digit;                                      §\C{// s is assigned "PETER0123456789"}§
    2433 s += peter;                                                     §\C{// s is assigned "PETER0123456789PETER"}§
    2434 \end{cfa}
    2435 There is also an assignment form ©+=©.
     2453The binary operators \Indexc{+} and \Indexc{+=} concatenate two strings, creating the sum of the strings.
     2454\begin{cfa}
     2455s = peter + ' ' + digit;                        §\C{// s is assigned "PETER 0123456789"}§
     2456s += peter;                                                     §\C{// s is assigned "PETER 0123456789PETER"}§
     2457\end{cfa}
    24362458
    24372459
    24382460\subsection{Repetition}
    24392461
    2440 The binary operator \Indexc{*} returns a string that is the string repeated ©n© times.
    2441 If ©n = 0©, a zero length string, ©""© is returned.
    2442 \begin{cfa}
    2443 s = (peter + ' ') * 3;                          §\C{// s is assigned "PETER PETER PETER"}§
    2444 \end{cfa}
    2445 There is also an assignment form ©*=©.
    2446 
    2447 
    2448 \subsection{Length}
    2449 
    2450 The ©length© operation
    2451 \begin{cfa}
    2452 int length()
    2453 \end{cfa}
    2454 returns the length of a string variable.
    2455 \begin{cfa}
    2456 i = peter.length();                     §\C{// i is assigned the value 5}§
     2462The binary operators \Indexc{*} and \Indexc{*=} repeat a string $N$ times.
     2463If $N = 0$, a zero length string, ©""© is returned.
     2464\begin{cfa}
     2465s = 'x' * 3;                            §\C{// s is assigned "PETER PETER PETER "}§
     2466s = (peter + ' ') * 3;                          §\C{// s is assigned "PETER PETER PETER "}§
    24572467\end{cfa}
    24582468
    24592469
    24602470\subsection{Substring}
    2461 The substring operation:
    2462 \begin{cfa}
    2463 string operator () (int start, int lnth);
    2464 \end{cfa}
    2465 performs a substring operation that returns the string starting at a specified position (©start©) in the current string, and having the specified length (©lnth©).
     2471The substring operation returns a subset of the string starting at a position in the string and traversing a length.
     2472\begin{cfa}
     2473s = peter( 2, 3 );                                      §\C{// s is assigned "ETE"}§
     2474s = peter( 4, -3 );                                     §\C{// s is assigned "ETE", length is opposite direction}§
     2475s = peter( 2, 8 );                                      §\C{// s is assigned "ETER", length is clipped to 4}§
     2476s = peter( 0, -1 );                                     §\C{// s is assigned "", beyond string so clipped to null}§
     2477s = peter(-1, -1 );                                     §\C{// s is assigned "R", start and length are negative}§
     2478\end{cfa}
    24662479A negative starting position is a specification from the right end of the string.
    24672480A negative length means that characters are selected in the opposite (right to left) direction from the starting position.
    24682481If the substring request extends beyond the beginning or end of the string, it is clipped (shortened) to the bounds of the string.
    24692482If the substring request is completely outside of the original string, a null string located at the end of the original string is returned.
    2470 \begin{cfa}
    2471 s = peter( 2, 3 );                      §\C{// s is assigned "ETE"}§
    2472 s = peter( 4, -3 );                     §\C{// s is assigned "ETE", length is opposite direction}§
    2473 s = peter( 2, 8 );                      §\C{// s is assigned "ETER", length is clipped to 4}§
    2474 s = peter( 0, -1 );                     §\C{// s is assigned "", beyond string so clipped to null}§
    2475 s = peter(-1, -1 );                     §\C{// s is assigned "R", start and length are negative}§
    2476 \end{cfa}
    24772483The substring operation can also appear on the left hand side of the assignment operator.
    24782484The substring is replaced by the value on the right hand side of the assignment.
    24792485The length of the right-hand-side value may be shorter, the same length, or longer than the length of the substring that is selected on the left hand side of the assignment.
    2480 \begin{cfa}[mathescape=false]
    2481 digit( 3, 3 ) = "";             §\C{// digit is assigned "0156789"}§
    2482 digit( 4, 3 ) = "xyz";          §\C{// digit is assigned "015xyz9"}§
    2483 digit( 7, 0 ) = "***";          §\C{// digit is assigned "015xyz***9"}§
    2484 digit(-4, 3 ) = "$$$";          §\C{// digit is assigned "015xyz\$\$\$9"}§
     2486\begin{cfa}
     2487digit( 3, 3 ) = "";                             §\C{// digit is assigned "0156789"}§
     2488digit( 4, 3 ) = "xyz";                          §\C{// digit is assigned "015xyz9"}§
     2489digit( 7, 0 ) = "***";                          §\C{// digit is assigned "015xyz***9"}§
     2490digit(-4, 3 ) = "$$$";                          §\C{// digit is assigned "015xyz\$\$\$9"}§
    24852491\end{cfa}
    24862492A substring is treated as a pointer into the base (substringed) string rather than creating a copy of the subtext.
    … …  
    25012507// e is a substring result passed by value
    25022508void test(string &x, string &a, string &b, string &c, string &d, string e) {
    2503                                                         §\C{//   x                                a               b               c               d               e}§
    2504         a( 1, 2 ) = "aaa";              §\C{// aaaxxxxxxxxxxx   aaax    axx             xxxxx   xxxxx   xxxxx}§
    2505         b( 2, 12 ) = "bbb";             §\C{// aaabbbxxxxxxxxx  aaab    abbb    bbxxx   xxxxx   xxxxx}§
    2506         c( 4, 5 ) = "ccc";              §\C{// aaabbbxcccxxxxxx aaab    abbb    bbxccc  ccxxx   xxxxx}§
    2507         c = "yyy";                              §\C{// aaabyyyxxxxxx    aaab    abyy    yyy             xxxxx   xxxxx}§
    2508         d( 1, 3 ) = "ddd";              §\C{// aaabyyyxdddxx    aaab    abyy    yyy             dddxx   xxxxx}§
    2509         e( 1, 3 ) = "eee";              §\C{// aaabyyyxdddxx    aaab    abyy    yyy             dddxx   eeexx}§
    2510         x = e;                                  §\C{// eeexx                    eeex    exx             x                               eeexx}§
     2509                                                                        §\C{//   x                                a               b               c               d               e}§
     2510        a( 1, 2 ) = "aaa";                              §\C{// aaaxxxxxxxxxxx   aaax    axx             xxxxx   xxxxx   xxxxx}§
     2511        b( 2, 12 ) = "bbb";                             §\C{// aaabbbxxxxxxxxx  aaab    abbb    bbxxx   xxxxx   xxxxx}§
     2512        c( 4, 5 ) = "ccc";                              §\C{// aaabbbxcccxxxxxx aaab    abbb    bbxccc  ccxxx   xxxxx}§
     2513        c = "yyy";                                              §\C{// aaabyyyxxxxxx    aaab    abyy    yyy             xxxxx   xxxxx}§
     2514        d( 1, 3 ) = "ddd";                              §\C{// aaabyyyxdddxx    aaab    abyy    yyy             dddxx   xxxxx}§
     2515        e( 1, 3 ) = "eee";                              §\C{// aaabyyyxdddxx    aaab    abyy    yyy             dddxx   eeexx}§
     2516        x = e;                                                  §\C{// eeexx                    eeex    exx             x                               eeexx}§
    25112517}
    25122518\end{cfa}
    … …  
    25182524For example:
    25192525\begin{cfa}
    2520 s = peter( 2 );                         §\C{// s is assigned "ETER"}§
    2521 peter( 2 ) = "IPER";            §\C{// peter is assigned "PIPER"}§
     2526s = peter( 2 );                                         §\C{// s is assigned "ETER"}§
     2527peter( 2 ) = "IPER";                            §\C{// peter is assigned "PIPER"}§
    25222528\end{cfa}
    25232529It is also possible to substring using a string as the index for selecting the substring portion of the string.
    … …  
    25272533For example:
    25282534\begin{cfa}[mathescape=false]
    2529 digit( "xyz$$$" ) = "678";      §\C{// digit is assigned "0156789"}§
    2530 digit( "234") = "***";          §\C{// digit is assigned "0156789***"}§
    2531 \end{cfa}
    2532 %$
     2535digit( "xyz$$$" ) = "678";                      §\C{// digit is assigned "0156789"}§
     2536digit( "234") = "***";                          §\C{// digit is assigned "0156789***"}§
     2537\end{cfa}
    25332538
    25342539
    … …  
    25702575A negative starting position is a specification from the right end of the string.
    25712576\begin{cfa}
    2572 i = peter.include( digitmask ); §\C{// i is assigned 1}§
    2573 i = peter.include( alphamask ); §\C{// i is assigned 6}§
     2577i = peter.include( digitmask );         §\C{// i is assigned 1}§
     2578i = peter.include( alphamask );         §\C{// i is assigned 6}§
    25742579\end{cfa}
    25752580
    … …  
    26222627\begin{cfa}
    26232628// remove leading blanks
    2624 s = string( "   ABC" ).trim( " " );                     §\C{// s is assigned "ABC",}§
     2629s = string( "   ABC" ).trim( " " );     §\C{// s is assigned "ABC",}§
    26252630// remove trailing blanks
    2626 s = string( "ABC   " ).trim( " ", last );       §\C{// s is assigned "ABC",}§
     2631s = string( "ABC   " ).trim( " ", last ); §\C{// s is assigned "ABC",}§
    26272632\end{cfa}
    26282633
    … …  
    26512656returns a string in which all occurrences of the ©from© string in the current string have been replaced by the ©to© string.
    26522657\begin{cfa}
    2653 s = peter.replace( "E", "XX" ); §\C{// s is assigned "PXXTXXR"}§
     2658s = peter.replace( "E", "XX" );         §\C{// s is assigned "PXXTXXR"}§
    26542659\end{cfa}
    26552660The replacement is done left-to-right.
    26562661When an instance of the ©from© string is found and changed to the ©to© string, it is NOT examined again for further replacement.
    26572662
    2658 
    2659 \section{Returning N+1 on Failure}
     2663\subsection{Returning N+1 on Failure}
    26602664
    26612665Any of the string search routines can fail at some point during the search.
    … …  
    26872691
    26882692
     2693\subsection{C Compatibility}
     2694
     2695To ease conversion from C to \CFA, there are companion ©string© routines for C strings.
     2696\VRef[Table]{t:CompanionStringRoutines} shows the C routines on the left that also work with ©string© and the rough equivalent ©string© opeation of the right.
     2697Hence, it is possible to directly convert a block of C string operations into @string@ just by changing the
     2698
     2699\begin{table}
     2700\begin{cquote}
     2701\begin{tabular}{@{}l|l@{}}
     2702\multicolumn{1}{c|}{©char []©}  & \multicolumn{1}{c}{©string©}  \\
     2703\hline
     2704©strcpy©, ©strncpy©             & ©=©                                                                   \\
     2705©strcat©, ©strncat©             & ©+©                                                                   \\
     2706©strcmp©, ©strncmp©             & ©==©, ©!=©, ©<©, ©<=©, ©>©, ©>=©              \\
     2707©strlen©                                & ©size©                                                                \\
     2708©[]©                                    & ©[]©                                                                  \\
     2709©strstr©                                & ©find©                                                                \\
     2710©strcspn©                               & ©find_first_of©, ©find_last_of©               \\
     2711©strspc©                                & ©find_fist_not_of©, ©find_last_not_of©
     2712\end{tabular}
     2713\end{cquote}
     2714\caption{Companion Routines for \CFA \lstinline{string} to C Strings}
     2715\label{t:CompanionStringRoutines}
     2716\end{table}
     2717
     2718For example, this block of C code can be converted to \CFA by simply changing the type of variable ©s© from ©char []© to ©string©.
     2719\begin{cfa}
     2720        char s[32];
     2721        //string s;
     2722        strcpy( s, "abc" );                             PRINT( %s, s );
     2723        strncpy( s, "abcdef", 3 );              PRINT( %s, s );
     2724        strcat( s, "xyz" );                             PRINT( %s, s );
     2725        strncat( s, "uvwxyz", 3 );              PRINT( %s, s );
     2726        PRINT( %zd, strlen( s ) );
     2727        PRINT( %c, s[3] );
     2728        PRINT( %s, strstr( s, "yzu" ) ) ;
     2729        PRINT( %s, strstr( s, 'y' ) ) ;
     2730\end{cfa}
     2731However, the conversion fails with I/O because ©printf© cannot print a ©string© using format code ©%s© because \CFA strings are not null terminated.
     2732
     2733
    26892734\subsection{Input/Output Operators}
    26902735
    … …  
    27072752Hence, enums may be overloaded with variable, enum, and function names.
    27082753\begin{cfa}
    2709 int Foo;                        §\C{// type/variable separate namespaces}§
     2754int Foo;                                                        §\C{// type/variable separate namespaces}§
    27102755enum Foo { Bar };
    2711 enum Goo { Bar };       §\C[1.75in]{// overload Foo.Bar}§
    2712 double Bar;                     §\C{// overload Foo.Bar, Goo.Bar}\CRT§
     2756enum Goo { Bar };                                       §\C{// overload Foo.Bar}§
     2757double Bar;                                                     §\C{// overload Foo.Bar, Goo.Bar}§
    27132758\end{cfa}
    27142759An anonymous enumeration injects enums with specific values into a scope.
    … …  
    27832828The following examples illustrate the difference between the enumeration type and the type of its enums.
    27842829\begin{cfa}
    2785 Math m = PI;    §\C[1.5in]{// allowed}§
    2786 double d = PI;  §\C{// allowed, conversion to base type}§
    2787 m = E;                  §\C{// allowed}§
    2788 m = Alph;               §\C{// {\color{red}disallowed}}§
    2789 m = 3.141597;   §\C{// {\color{red}disallowed}}§
    2790 d = m;                  §\C{// allowed}§
    2791 d = Alph;               §\C{// {\color{red}disallowed}}§
    2792 Letter l = A;   §\C{// allowed}§
    2793 Greek g = Alph; §\C{// allowed}§
    2794 l = Alph;               §\C{// allowed, conversion to base type}§
    2795 g = A;                  §\C{// {\color{red}disallowed}}\CRT§
     2830Math m = PI;                                            §\C{// allowed}§
     2831double d = PI;                                          §\C{// allowed, conversion to base type}§
     2832m = E;                                                          §\C{// allowed}§
     2833m = Alph;                                                       §\C{// {\color{red}disallowed}}§
     2834m = 3.141597;                                           §\C{// {\color{red}disallowed}}§
     2835d = m;                                                          §\C{// allowed}§
     2836d = Alph;                                                       §\C{// {\color{red}disallowed}}§
     2837Letter l = A;                                           §\C{// allowed}§
     2838Greek g = Alph;                                         §\C{// allowed}§
     2839l = Alph;                                                       §\C{// allowed, conversion to base type}§
     2840g = A;                                                          §\C{// {\color{red}disallowed}}§
    27962841\end{cfa}
    27972842
    … …  
    33623407For example, consider C's \Indexc{div} function, which returns the quotient and remainder for a division of an integer value.
    33633408\begin{cfa}
    3364 typedef struct { int quot, rem; } div_t;        §\C[7cm]{// from include stdlib.h}§
     3409typedef struct { int quot, rem; } div_t; §\C{// from include stdlib.h}§
    33653410div_t div( int num, int den );
    3366 div_t qr = div( 13, 5 ); §\C{// return quotient/remainder aggregate}§
     3411div_t qr = div( 13, 5 );                                §\C{// return quotient/remainder aggregate}§
    33673412printf( "%d %d\n", qr.quot, qr.rem ); §\C{// print quotient/remainder}§
    33683413\end{cfa}
    … …  
    33753420For example, consider C's \Indexc{modf} function, which returns the integral and fractional part of a floating value.
    33763421\begin{cfa}
    3377 double modf( double x, double * i ); §\C{// from include math.h}§
     3422double modf( double x, double * i );    §\C{// from include math.h}§
    33783423double intp, frac = modf( 13.5, &intp ); §\C{// return integral and fractional components}§
    33793424printf( "%g %g\n", intp, frac ); §\C{// print integral/fractional components}§
    … …  
    34043449When a function call is passed as an argument to another call, the best match of actual arguments to formal parameters is evaluated given all possible expression interpretations in the current scope.
    34053450\begin{cfa}
    3406 void g( int, int ); §\C{// 1}§
    3407 void g( double, double ); §\C{// 2}§
    3408 g( div( 13, 5 ) ); §\C{// select 1}§
    3409 g( modf( 13.5 ) ); §\C{// select 2}§
     3451void g( int, int );                                             §\C{// 1}§
     3452void g( double, double );                               §\C{// 2}§
     3453g( div( 13, 5 ) );                                              §\C{// select 1}§
     3454g( modf( 13.5 ) );                                              §\C{// select 2}§
    34103455\end{cfa}
    34113456In this case, there are two overloaded ©g© routines.
    … …  
    34163461The previous examples can be rewritten passing the multiple returned-values directly to the ©printf© function call.
    34173462\begin{cfa}
    3418 [ int, int ] div( int x, int y ); §\C{// from include stdlib}§
     3463[ int, int ] div( int x, int y );               §\C{// from include stdlib}§
    34193464printf( "%d %d\n", div( 13, 5 ) ); §\C{// print quotient/remainder}§
    34203465
    3421 [ double, double ] modf( double x ); §\C{// from include math}§
     3466[ double, double ] modf( double x );    §\C{// from include math}§
    34223467printf( "%g %g\n", modf( 13.5 ) ); §\C{// print integral/fractional components}§
    34233468\end{cfa}
    … …  
    34303475\begin{cfa}
    34313476int quot, rem;
    3432 [ quot, rem ] = div( 13, 5 ); §\C{// assign multiple variables}§
    3433 printf( "%d %d\n", quot, rem ); §\C{// print quotient/remainder}\CRT§
     3477[ quot, rem ] = div( 13, 5 );                   §\C{// assign multiple variables}§
     3478printf( "%d %d\n", quot, rem );                 §\C{// print quotient/remainder}§
    34343479\end{cfa}
    34353480Here, the multiple return-values are matched in much the same way as passing multiple return-values to multiple parameters in a call.
    … …  
    38483893The general syntax of a lexical list is:
    38493894\begin{cfa}
    3850 [ $\emph{exprlist}$ ]
    3851 \end{cfa}
    3852 where ©$\emph{exprlist}$© is a list of one or more expressions separated by commas.
     3895[ §\emph{exprlist}§ ]
     3896\end{cfa}
     3897where \LstBasicStyle{\emph{exprlist}} is a list of one or more expressions separated by commas.
    38533898The brackets, ©[]©, allow differentiating between lexical lists and expressions containing the C comma operator.
    38543899The following are examples of lexical lists:
    … …  
    38563901[ x, y, z ]
    38573902[ 2 ]
    3858 [ v+w, x*y, 3.14159, f() ]
     3903[ v + w, x * y, 3.14159, f() ]
    38593904\end{cfa}
    38603905Tuples 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.
    … …  
    38683913The general syntax of a tuple type is:
    38693914\begin{cfa}
    3870 [ $\emph{typelist}$ ]
    3871 \end{cfa}
    3872 where ©$\emph{typelist}$© is a list of one or more legal \CFA or C type specifications separated by commas, which may include other tuple type specifications.
     3915[ §\emph{typelist}§ ]
     3916\end{cfa}
     3917where \LstBasicStyle{\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.
    38733918Examples of tuple types include:
    38743919\begin{cfa}
    38753920[ unsigned int, char ]
    38763921[ double, double, double ]
    3877 [ * int, int * ] §\C{// mix of CFA and ANSI}§
     3922[ * int, int * ]                                                §\C{// mix of CFA and ANSI}§
    38783923[ * [ 5 ] int, * * char, * [ [ int, int ] ] (int, int) ]
    38793924\end{cfa}
    … …  
    38823927Examples of declarations using tuple types are:
    38833928\begin{cfa}
    3884 [ int, int ] x; §\C{// 2 element tuple, each element of type int}§
    3885 * [ char, char ] y; §\C{// pointer to a 2 element tuple}§
     3929[ int, int ] x;                                                 §\C{// 2 element tuple, each element of type int}§
     3930* [ char, char ] y;                                             §\C{// pointer to a 2 element tuple}§
    38863931[ [ int, int ] ] z ([ int, int ]);
    38873932\end{cfa}
    … …  
    39003945[ int, int ] w1;
    39013946[ int, int, int ] w2;
    3902 [ void ] f (int, int, int); §\C{// three input parameters of type int}§
    3903 [ void ] g ([ int, int, int ]); §\C{3 element tuple as input}§
     3947[ void ] f (int, int, int);                             §\C{// three input parameters of type int}§
     3948[ void ] g ([ int, int, int ]);                 §\C{// 3 element tuple as input}§
    39043949f( [ 1, 2, 3 ] );
    39053950f( w1, 3 );
    … …  
    39824027[ int, int, int, int ] w = [ 1, 2, 3, 4 ];
    39834028int x = 5;
    3984 [ x, w ] = [ w, x ]; §\C{// all four tuple coercions}§
     4029[ x, w ] = [ w, x ];                                    §\C{// all four tuple coercions}§
    39854030\end{cfa}
    39864031Starting on the right-hand tuple in the last assignment statement, w is opened, producing a tuple of four values;
    … …  
    40004045Mass assignment has the following form:
    40014046\begin{cfa}
    4002 [ $\emph{lvalue}$, ... , $\emph{lvalue}$ ] = $\emph{expr}$;
     4047[ §\emph{lvalue}§, ... , §\emph{lvalue}§ ] = §\emph{expr}§;
    40034048\end{cfa}
    40044049\index{lvalue}
    4005 The left-hand side is a tuple of \emph{lvalues}, which is a list of expressions each yielding an address, \ie any data object that can appear on the left-hand side of a conventional assignment statement.
    4006 ©$\emph{expr}$© is any standard arithmetic expression.
     4050The left-hand side is a tuple of \LstBasicStyle{\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.
     4051\LstBasicStyle{\emph{expr}} is any standard arithmetic expression.
    40074052Clearly, the types of the entities being assigned must be type compatible with the value of the expression.
    40084053
    … …  
    40414086Multiple assignment has the following form:
    40424087\begin{cfa}
    4043 [ $\emph{lvalue}$, ... , $\emph{lvalue}$ ] = [ $\emph{expr}$, ... , $\emph{expr}$ ];
     4088[ §\emph{lvalue}§, ... , §\emph{lvalue}§ ] = [ §\emph{expr}§, ... , §\emph{expr}§ ];
    40444089\end{cfa}
    40454090\index{lvalue}
    … …  
    40724117both these examples produce indeterminate results:
    40734118\begin{cfa}
    4074 f( x++, x++ ); §\C{// C routine call with side effects in arguments}§
    4075 [ v1, v2 ] = [ x++, x++ ]; §\C{// side effects in right-hand side of multiple assignment}§
     4119f( x++, x++ );                                                  §\C{// C routine call with side effects in arguments}§
     4120[ v1, v2 ] = [ x++, x++ ];                              §\C{// side effects in right-hand side of multiple assignment}§
    40764121\end{cfa}
    40774122
    … …  
    40834128Cascade assignment has the following form:
    40844129\begin{cfa}
    4085 $\emph{tuple}$ = $\emph{tuple}$ = ... = $\emph{tuple}$;
     4130§\emph{tuple}§ = §\emph{tuple}§ = ... = §\emph{tuple}§;
    40864131\end{cfa}
    40874132and it has the same parallel semantics as for mass and multiple assignment.
    … …  
    41034148The goal of \CFA stream input/output (I/O) is to simplify the common cases\index{I/O!common case}, while fully supporting polymorphism and user defined types in a consistent way.
    41044149Stream I/O can be implicitly or explicitly formatted.
    4105 Implicit formatting means \CFA selects the output or input format for values that matches the variable's type.
    4106 Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
     4150Implicit formatting means \CFA selects an I/O format for values that matches a variable's type.
     4151Explicit formatting means additional I/O information is specified to control how a value is interpreted.
     4152
    41074153\CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
    41084154Specifically:
    … …  
    41124158\CFA/\CC format manipulators are named, making them easier to read and remember.
    41134159\item
    4114 ©printf©/Python separates format codes from associated variables, making it difficult to match codes with variables.
     4160©printf©/Python separate format codes from associated variables, making it difficult to match codes with variables.
    41154161\CFA/\CC co-locate codes with associated variables, where \CFA has the tighter binding.
    41164162\item
    4117 Format manipulators in \CFA have local effect, whereas \CC have global effect, except ©setw©.
    4118 Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
     4163Format manipulators in ©printf©/Python/\CFA have local effect, whereas \CC have global effect, except ©setw©.
     4164Hence, it is common \CC programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
    41194165Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
    41204166Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
     4167\CC programers never do any of this.
    41214168\item
    41224169\CFA has more sophisticated implicit value spacing than Python, plus implicit newline at the end of a print.
    41234170\end{itemize}
    41244171
    4125 The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
    4126 Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file.
    4127 Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
    4128 \begin{cfa}
    4129 ®exit®   | "x (" | x | ") negative value.";   // terminate and return EXIT_FAILURE to shell
    4130 ®abort® | "x (" | x | ") negative value.";   // terminate and generate stack trace and core file
    4131 \end{cfa}
    4132 Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
     4172
     4173\subsection{Basic I/O}
     4174
     4175The standard polymorphic I/O streams are ©stdin©/©sin© (input), ©stdout©/©sout©, and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
     4176The standard I/O operator is the bit-wise (or) operator, ©'|'©, which is used to cascade multiple I/O operations.
    41334177The \CFA header file for the I/O library is \Indexc{fstream.hfa}.
    4134 
    4135 
    4136 \subsection{Basic I/O}
    41374178
    41384179For implicit formatted output, the common case is printing a series of variables separated by whitespace.
    … …  
    417742181®, ®2®, ®3 4®, ®5®, ®6
    41784219\end{cfa}
    4179 Finally, \CFA uses the logical-or operator for I/O as it is the lowest-priority \emph{overloadable} operator, other than assignment.
     4220The bit-wise ©|© operator is used for I/O, rather \CC shift-operators, ©<<© and ©>>©, as it is the lowest-priority \emph{overloadable} operator, other than assignment.
     4221(Operators ©||© and ©&&© are not overloadable in \CFA.)
    41804222Therefore, fewer output expressions require parenthesis.
    41814223\begin{cquote}
    … …  
    42004242\end{cquote}
    42014243There is a weak similarity between the \CFA logical-or operator and the \Index{Shell pipe-operator} for moving data, where data flows in the correct direction for input but the opposite direction for output.
    4202 Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators, which prevents this common error in \CC:
     4244Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators to prevent this common error in \CC:
    42034245\begin{C++}
    42044246cin << i; // why is this generating a lot of error messages?
    42054247\end{C++}
     4248
     4249Streams ©exit© and ©abort© provide output with immediate program termination without and with generating a stack trace and core file.
     4250Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
     4251\begin{cfa}
     4252®exit®   | "x (" | x | ") negative value.";     §\C{// print, terminate, and return EXIT\_FAILURE to shell}§
     4253®abort® | "x (" | x | ") negative value.";      §\C{// print, terminate, and generate stack trace and core file}§
     4254\end{cfa}
     4255Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
    42064256
    42074257For implicit formatted input, the common case is reading a sequence of values separated by whitespace, where the type of an input constant must match with the type of the input variable.
    … …  
    42464296\end{tabular}
    42474297\end{cquote}
    4248 
    4249 \VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
     4298The format of numeric input values in the same as C constants without a trailing type suffix, as the input value-type is denoted by the input variable.
     4299For ©bool© type, the constants are ©true© and ©false©.
     4300For integral types, any number of digits, optionally preceded by a sign (©+© or ©-©), where a
     4301\begin{itemize}
     4302\item
     4303©1©-©9© prefix introduces a decimal value (©0©-©9©),
     4304\item
     4305©0© prefix introduces an octal value (©0©-©7©), and
     4306\item
     4307©0x© or ©0X© prefix introduces a hexadecimal value (©0©-©f©) with lower or upper case letters.
     4308\end{itemize}
     4309For floating-point types, any number of decimal digits, optionally preceded by a sign (©+© or ©-©), optionally containing a decimal point, and optionally followed by an exponent, ©e© or ©E©, with signed (optional) decimal digits.
     4310Floating-point values can also be written in hexadecimal format preceded by ©0x© or ©0X© with hexadecimal digits and exponent denoted by ©p© or ©P©.
     4311In all cases, all whitespace characters are skipped until an appropriate value is found.
     4312\Textbf{If an appropriate value is not found, the exception ©missing_data© is raised.}
     4313
     4314For the C-string type, there are two input forms: any number of \Textbf{non-whitespace} characters or a quoted sequence containing any characters except the closing quote, \ie there is no escape character supported in the string..
     4315In both cases, the string is null terminated ©'\0'©.
     4316For the quoted string, the start and end quote characters can be any character and do not have to match \see{\ref{XXX}}.
     4317
     4318\VRef[Figure]{f:IOStreamFunctions} shows the I/O stream operations for interacting with files other than ©cin©, ©cout©, and ©cerr©.
     4319\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     4320\item
     4321\Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
     4322\item
     4323\Indexc{clear} resets the stream error-indicator.
     4324\item
     4325\Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
     4326\item
     4327\Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
     4328Returns true if the end-of-file indicator is set, otherwise false.
     4329\item
     4330\Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
     4331\item
     4332\Indexc{close} flushes the stream and closes the file.
     4333\item
     4334\Indexc{write} (©ofstream© only) writes ©size© bytes to the stream.
     4335The bytes are written lazily when an internal buffer fills.
     4336Eager buffer writes are done with ©flush©
     4337\item
     4338\Indexc{read} (©ifstream© only) reads ©size© bytes from the stream.
     4339\item
     4340\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
     4341Pushed-back characters returned by subsequent reads in the reverse order of pushing.
     4342\end{itemize}
     4343The constructor functions:
     4344\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     4345\item
     4346create an unbound stream, which is subsequently bound to a file with ©open©.
     4347\item
     4348create a bound stream to the associated file with given ©mode©.
     4349\end{itemize}
     4350The destructor closes the stream.
     4351
     4352\begin{figure}
     4353\begin{cfa}
     4354// *********************************** ofstream ***********************************
     4355bool fail( ofstream & );§\indexc{fail}\index{ofstream@©ofstream©!©fail©}§
     4356void clear( ofstream & );§\indexc{clear}\index{ofstream@©ofstream©!©clear©}§
     4357int flush( ofstream & );§\indexc{flush}\index{ofstream@©ofstream©!©flush©}§
     4358void open( ofstream &, const char name[], const char mode[] = "w" );§\indexc{open}\index{ofstream@©ofstream©!©open©}§
     4359void close( ofstream & );§\indexc{close}\index{ofstream@©ofstream©!©close©}§
     4360ofstream & write( ofstream &, const char data[], size_t size );§\indexc{write}\index{ofstream@©ofstream©!©write©}§
     4361void ?{}( ofstream & );§\index{ofstream@©ofstream©!©?{}©}§
     4362void ?{}( ofstream &, const char name[], const char mode[] = "w" );
     4363void ^?{}( ofstream & );§\index{ofstream@©ofstream©!©^?{}©}§
     4364
     4365// *********************************** ifstream ***********************************
     4366bool fail( ifstream & is );§\indexc{fail}\index{ifstream@©ifstream©!©fail©}§
     4367void clear( ifstream & );§\indexc{clear}\index{ifstream@©ifstream©!©clear©}§
     4368bool eof( ifstream & is );§\indexc{eof}\index{ifstream@©ifstream©!©eof©}§
     4369void open( ifstream & is, const char name[], const char mode[] = "r" );§\indexc{open}\index{ifstream@©ifstream©!©open©}§
     4370void close( ifstream & is );§\indexc{close}\index{ifstream@©ifstream©!©close©}§
     4371ifstream & read( ifstream & is, char data[], size_t size );§\indexc{read}\index{ifstream@©ifstream©!©read©}§
     4372ifstream & ungetc( ifstream & is, char c );§\indexc{unget}\index{ifstream@©ifstream©!©unget©}§
     4373void ?{}( ifstream & is );§\index{ifstream@©ifstream©!©?{}©}§
     4374void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
     4375void ^?{}( ifstream & is );§\index{ifstream@©ifstream©!©^?{}©}§
     4376\end{cfa}
     4377\caption{I/O Stream Functions}
     4378\label{f:IOStreamFunctions}
     4379\end{figure}
     4380
     4381\VRef[Figure]{f:CFACommand-LineProcessing} demonstrates the file operations by showing the idiomatic \CFA command-line processing and copying an input file to an output file.
    42504382Note, a stream variable may be copied because it is a reference to an underlying stream data-structures.
    4251 All I/O errors are handles as exceptions, but end-of-file is not an exception as C programmers are use to explicitly checking for it.
     4383\Textbf{All I/O errors are handled as exceptions}, but end-of-file is not an exception as C programmers are use to explicitly checking for it.
    42524384
    42534385\begin{figure}
    … …  
    42614393        try {
    42624394                choose ( argc ) {
    4263                   case 2, 3:
     4395                  case 3, 2:
    42644396                        ®open®( in, argv[1] );                  §\C{// open input file first as output creates file}§
    42654397                        if ( argc == 3 ) ®open®( out, argv[2] ); §\C{// do not create output unless input opens}§
    … …  
    42904422\end{figure}
    42914423
    4292 \VRef[Figure]{f:StreamFunctions} shows the stream operations.
    4293 \begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
    4294 \item
    4295 \Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
    4296 \item
    4297 \Indexc{clear} resets the stream error-indicator.
    4298 \item
    4299 \Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
    4300 \item
    4301 \Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
    4302 Returns true if the end-of-file indicator is set, otherwise false.
    4303 \item
    4304 \Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
    4305 \item
    4306 \Indexc{close} flushes the stream and closes the file.
    4307 \item
    4308 \Indexc{write} (©ofstream© only) writes ©size© bytes to the stream.
    4309 The bytes are written lazily when an internal buffer fills.
    4310 Eager buffer writes are done with ©flush©
    4311 \item
    4312 \Indexc{read} (©ifstream© only) reads ©size© bytes from the stream.
    4313 \item
    4314 \Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
    4315 Pushed-back characters returned by subsequent reads in the reverse order of pushing.
    4316 \end{itemize}
    4317 The constructor functions:
    4318 \begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
    4319 \item
    4320 create an unbound stream, which is subsequently bound to a file with ©open©.
    4321 \item
    4322 create a bound stream to the associated file with given ©mode©.
    4323 \end{itemize}
    4324 The destructor closes the stream.
    4325 
    4326 \begin{figure}
    4327 \begin{cfa}
    4328 // *********************************** ofstream ***********************************
    4329 
    4330 bool fail( ofstream & );§\indexc{fail}\index{ofstream@©ofstream©!©fail©}§
    4331 void clear( ofstream & );§\indexc{clear}\index{ofstream@©ofstream©!©clear©}§
    4332 int flush( ofstream & );§\indexc{flush}\index{ofstream@©ofstream©!©flush©}§
    4333 void open( ofstream &, const char name[], const char mode[] = "w" );§\indexc{open}\index{ofstream@©ofstream©!©open©}§
    4334 void close( ofstream & );§\indexc{close}\index{ofstream@©ofstream©!©close©}§
    4335 ofstream & write( ofstream &, const char data[], size_t size );§\indexc{write}\index{ofstream@©ofstream©!©write©}§
    4336 
    4337 void ?{}( ofstream & );§\index{ofstream@©ofstream©!©?{}©}§
    4338 void ?{}( ofstream &, const char name[], const char mode[] = "w" );
    4339 void ^?{}( ofstream & );§\index{ofstream@©ofstream©!©^?{}©}§
    4340 
    4341 // *********************************** ifstream ***********************************
    4342 
    4343 bool fail( ifstream & is );§\indexc{fail}\index{ifstream@©ifstream©!©fail©}§
    4344 void clear( ifstream & );§\indexc{clear}\index{ifstream@©ifstream©!©clear©}§
    4345 bool eof( ifstream & is );§\indexc{eof}\index{ifstream@©ifstream©!©eof©}§
    4346 void open( ifstream & is, const char name[], const char mode[] = "r" );§\indexc{open}\index{ifstream@©ifstream©!©open©}§
    4347 void close( ifstream & is );§\indexc{close}\index{ifstream@©ifstream©!©close©}§
    4348 ifstream & read( ifstream & is, char data[], size_t size );§\indexc{read}\index{ifstream@©ifstream©!©read©}§
    4349 ifstream & ungetc( ifstream & is, char c );§\indexc{unget}\index{ifstream@©ifstream©!©unget©}§
    4350 
    4351 void ?{}( ifstream & is );§\index{ifstream@©ifstream©!©?{}©}§
    4352 void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
    4353 void ^?{}( ifstream & is );§\index{ifstream@©ifstream©!©^?{}©}§
    4354 \end{cfa}
    4355 \caption{Stream Functions}
    4356 \label{f:StreamFunctions}
    4357 \end{figure}
    4358 
    43594424
    43604425\subsection{Implicit Separator}
    43614426
    43624427The \Index{implicit separator}\index{I/O!separator} character (space/blank) is a separator not a terminator for output.
    4363 The rules for implicitly adding the separator are:
     4428The rules for implicitly adding a separator are:
    43644429\begin{enumerate}
    43654430\item
    … …  
    43904455\begin{cfa}
    43914456sout | 1 | ", x" | 2 | ". x" | 3 | "; x" | 4 | "! x" | 5 | "? x" | 6 | "% x"
    4392            | 7 | "$\LstStringStyle{\textcent}$ x" | 8 | "$\LstStringStyle{\guillemotright}$ x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
     4457           | 7 | "§\LstStringStyle{\textcent}§ x" | 8 | "§\LstStringStyle{\guillemotright}§ x" | 9 | ") x" | 10 | "] x" | 11 | "} x";
    43934458\end{cfa}
    43944459\begin{cfa}[showspaces=true]
    4395 1®,® x 2®.® x 3®;® x 4®!® x 5®?® x 6®%® x 7$\R{\LstStringStyle{\textcent}}$ x 8$\R{\LstStringStyle{\guillemotright}}$ x 9®)® x 10®]® x 11®}® x
     4460Input1®,® x 2®.® x 3®;® x 4®!® x 5®?® x 6®%® x 7§\R{\LstStringStyle{\textcent}}§ x 8§\R{\LstStringStyle{\guillemotright}}§ x 9®)® x 10®]® x 11®}® x
    43964461\end{cfa}
    43974462
    43984463\item
    43994464A separator does not appear after a C string ending with the (extended) \Index*{ASCII}\index{ASCII!extended} characters: \LstStringStyle{([\{=\$\textsterling\textyen\textexclamdown\textquestiondown\guillemotleft}, where \LstStringStyle{\textexclamdown\textquestiondown} are inverted opening exclamation and question marks, and \LstStringStyle{\guillemotleft} is an opening citation mark.
    4400 %$
    4401 \begin{cfa}
    4402 sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x $\LstStringStyle{\textdollar}$" | 5 | "x $\LstStringStyle{\textsterling}$" | 6 | "x $\LstStringStyle{\textyen}$"
    4403            | 7 | "x $\LstStringStyle{\textexclamdown}$" | 8 | "x $\LstStringStyle{\textquestiondown}$" | 9 | "x $\LstStringStyle{\guillemotleft}$" | 10;
    4404 \end{cfa}
    4405 %$
     4465\begin{cfa}
     4466sout | "x (" | 1 | "x [" | 2 | "x {" | 3 | "x =" | 4 | "x §\LstStringStyle{\textdollar}§" | 5 | "x §\LstStringStyle{\textsterling}§" | 6 | "x §\LstStringStyle{\textyen}§"
     4467           | 7 | "x §\LstStringStyle{\textexclamdown}§" | 8 | "x §\LstStringStyle{\textquestiondown}§" | 9 | "x §\LstStringStyle{\guillemotleft}§" | 10;
     4468\end{cfa}
    44064469\begin{cfa}[showspaces=true]
    4407 x ®(®1 x ®[®2 x ®{®3 x ®=®4 x $\LstStringStyle{\textdollar}$5 x $\R{\LstStringStyle{\textsterling}}$6 x $\R{\LstStringStyle{\textyen}}$7 x $\R{\LstStringStyle{\textexclamdown}}$8 x $\R{\LstStringStyle{\textquestiondown}}$9 x $\R{\LstStringStyle{\guillemotleft}}$10
    4408 \end{cfa}
    4409 %$
     4470x ®(®1 x ®[®2 x ®{®3 x ®=®4 x §\LstStringStyle{\textdollar}§5 x §\R{\LstStringStyle{\textsterling}}§6 x §\R{\LstStringStyle{\textyen}}§7 x §\R{\LstStringStyle{\textexclamdown}}§8 x §\R{\LstStringStyle{\textquestiondown}}§9 x §\R{\LstStringStyle{\guillemotleft}}§10
     4471\end{cfa}
    44104472
    44114473\item
    … …  
    44154477\end{cfa}
    44164478\begin{cfa}[showspaces=true,showtabs=true]
    4417 x®`®1®`®x$\R{\texttt{'}}$2$\R{\texttt{'}}$x$\R{\texttt{"}}$3$\R{\texttt{"}}$x®:®4®:®x® ®5® ®x®  ®6®     ®x
     4479x®`®1®`®x§\R{\texttt{'}}§2§\R{\texttt{'}}§x§\R{\texttt{"}}§3§\R{\texttt{"}}§x®:®4®:®x® ®5® ®x®  ®6®     ®x
    44184480\end{cfa}
    44194481
    … …  
    44214483If a space is desired before or after one of the special string start/end characters, explicitly insert a space.
    44224484\begin{cfa}
    4423 sout | "x ($\R{\texttt{\textvisiblespace}}$" | 1 | "$\R{\texttt{\textvisiblespace}}$) x" | 2 | "$\R{\texttt{\textvisiblespace}}$, x" | 3 | "$\R{\texttt{\textvisiblespace}}$:x:$\R{\texttt{\textvisiblespace}}$" | 4;
     4485sout | "x (§\R{\texttt{\textvisiblespace}}§" | 1 | "§\R{\texttt{\textvisiblespace}}§) x" | 2 | "§\R{\texttt{\textvisiblespace}}§, x" | 3 | "§\R{\texttt{\textvisiblespace}}§:x:§\R{\texttt{\textvisiblespace}}§" | 4;
    44244486\end{cfa}
    44254487\begin{cfa}[showspaces=true,showtabs=true]
    … …  
    44384500The separator string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
    44394501\begin{cfa}[belowskip=0pt]
    4440 sepSet( sout, ", $\LstStringStyle{\textdollar}$" ); §\C{// set separator from " " to ", \$"}§
     4502sepSet( sout, ", §\LstStringStyle{\textdollar}§" ); §\C{// set separator from " " to ", \$"}§
    44414503sout | 1 | 2 | 3 | " \"" | ®sepVal® | "\"";
    44424504\end{cfa}
    44434505\begin{cfa}[showspaces=true,aboveskip=0pt]
    4444 1®, $\color{red}\LstStringStyle{\textdollar}$®2®, $\color{red}\LstStringStyle{\textdollar}$®3 ®", $\color{red}\LstStringStyle{\textdollar}$"®
     45061®, §\color{red}\LstStringStyle{\textdollar}§®2®, §\color{red}\LstStringStyle{\textdollar}§®3 ®", §\color{red}\LstStringStyle{\textdollar}§"®
    44454507\end{cfa}
    44464508\begin{cfa}[belowskip=0pt]
    … …  
    45574619For example, in:
    45584620\begin{cfa}
     4621int i, j;
    45594622sin | i | ®nl® | j;
    456046231 ®2®
    … …  
    45624625\end{cfa}
    45634626variable ©i© is assigned 1, the 2 is skipped, and variable ©j© is assigned 3.
     4627For example, in:
     4628\begin{cquote}
     4629\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
     4630\begin{cfa}
     4631char ch
     4632
     4633sin | ch; // read X
     4634
     4635X
     4636\end{cfa}
     4637&
     4638\begin{cfa}
     4639
     4640sin | ®nlOn®; // enable reading newlines
     4641sin | ch; // read newline
     4642
     4643
     4644\end{cfa}
     4645\end{tabular}
     4646\end{cquote}
     4647the left example skips the newline and reads ©'X'© into ©ch©, while the right example reads the newline into ©ch©.
    45644648
    45654649For output:
    … …  
    45894673
    45904674
    4591 \subsection{Output Value Manipulators}
     4675\subsection{Output Manipulators}
    45924676
    45934677The following \Index{manipulator}s control formatting (printing) of the argument output values.
    … …  
    46434727\item
    46444728\Indexc{unit}( engineering-notation )\index{manipulator!unit@©unit©} print engineering exponent as a letter between the range $10^{-24}$ and $10^{24}$:
     4729\begin{cquote}
    46454730©y© $\Rightarrow 10^{-24}$, ©z© $\Rightarrow 10^{-21}$, ©a© $\Rightarrow 10^{-18}$, ©f© $\Rightarrow 10^{-15}$, ©p© $\Rightarrow 10^{-12}$, ©n© $\Rightarrow 10^{-9}$, ©u© $\Rightarrow 10^{-6}$, ©m© $\Rightarrow 10^{-3}$, ©K© $\Rightarrow 10^{3}$, ©M© $\Rightarrow 10^{6}$, ©G© $\Rightarrow 10^{9}$, ©T© $\Rightarrow 10^{12}$, ©P© $\Rightarrow 10^{15}$, ©E© $\Rightarrow 10^{18}$, ©Z© $\Rightarrow 10^{21}$, ©Y© $\Rightarrow 10^{24}$.
     4731\end{cquote}
    46464732For exponent $10^{0}$, no decimal point or letter is printed.
    46474733\begin{cfa}[belowskip=0pt]
    … …  
    48434929// End: //
    48444930\end{comment}
    4845 %$
    4846 
    4847 
    4848 \subsection{Input Value Manipulators}
    4849 
    4850 The format of numeric input values in the same as C constants without a trailing type suffix, as the input value-type is denoted by the input variable.
    4851 For ©bool© type, the constants are ©true© and ©false©.
    4852 For integral types, any number of digits, optionally preceded by a sign (©+© or ©-©), where a
    4853 \begin{itemize}
    4854 \item
    4855 ©1©-©9© prefix introduces a decimal value (©0©-©9©),
    4856 \item
    4857 ©0© prefix introduces an octal value (©0©-©7©), and
    4858 \item
    4859 ©0x© or ©0X© prefix introduces a hexadecimal value (©0©-©f©) with lower or upper case letters.
    4860 \end{itemize}
    4861 For floating-point types, any number of decimal digits, optionally preceded by a sign (©+© or ©-©), optionally containing a decimal point, and optionally followed by an exponent, ©e© or ©E©, with signed (optional) decimal digits.
    4862 Floating-point values can also be written in hexadecimal format preceded by ©0x© or ©0X© with hexadecimal digits and exponent denoted by ©p© or ©P©.
    4863 
    4864 For the C-string type, the input values are \emph{not} the same as C-string constants, \ie double quotes bracketing arbitrary text with escape sequences.
    4865 Instead, the next sequence of non-whitespace characters are read, and the input sequence is terminated with delimiter ©'\0'©.
    4866 The string variable \emph{must} be large enough to contain the input sequence.
     4931
     4932
     4933\subsection{Input Manipulators}
     4934
     4935The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
     4936
     4937Certain manipulators support a \newterm{scanset}, which is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
     4938For example, the scanset \lstinline{"a-zA-Z -/?§"} matches any number of characters between ©'a'© and ©'z'©, between ©'A'© and ©'Z'©, between space and ©'/'©, and characters ©'?'© and (Latin-1) ©'§'©.
     4939The following string is matched by this scanset:
     4940\begin{cfa}
     4941!&%$  abAA () ZZZ  ??  xx§\S\S\S§
     4942\end{cfa}
     4943To match a minus, put it as the first character, ©"-0-9"©.
     4944Other complex forms of regular-expression matching are not supported.
     4945
     4946A string variable \emph{must} be large enough to contain the input sequence.
    48674947To force programmers to consider buffer overruns for C-string input, C-strings can only be read with a width field, which should specify a size less than or equal to the C-string size, \eg:
    48684948\begin{cfa}
    … …  
    48714951\end{cfa}
    48724952
    4873 A scanset is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
    4874 For example, the scanset \lstinline{"a-zA-Z -/?§"} matches characters between ©'a'© and ©'z'©, between ©'A'© and ©'Z'©, between space and ©'/'©, and characters ©'?'© and (Latin-1) ©'§'©.
    4875 The following string is matched by this scanset:
    4876 \begin{cfa}
    4877 !&%$  abAA () ZZZ  ??  xx§§§§
    4878 \end{cfa}
    4879 To match a minus, put it as the first character, ©"-0-9"©.
    4880 Other complex forms of regular-expression matching are not supported.
    4881 
    4882 The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
     4953Currently, there is no mechanism to detect if a value read exceeds the capwhen Most types are finite sized, \eg integral types only store value that fit into their corresponding storage, 8, 16, 32, 64, 128 bits.
     4954Hence, an input value may be too large, and the result of the read is often considered undefined, which leads to difficlt to locate runtime errors.
     4955All reads in \CFA check if values do not fit into the argument variable's type and raise the exception
     4956All types are
     4957
    48834958\begin{enumerate}
    48844959\item
    4885 \Indexc{skip}( pattern )\index{manipulator!skip@©skip©}, ©skip©( length )
    4886 The pattern is composed of white-space and non-white-space characters, where \emph{any} white-space character matches 0 or more input white-space characters (hence, consecutive white-space characters in the pattern are combined), and each non-white-space character matches exactly with an input character.
    4887 The length is composed of the next $N$ characters, including the newline character.
     4960\Indexc{skip}( scanset )\index{manipulator!skip@©skip©}, ©skip©( $N$ )
     4961The first form uses a scanset to skip matching characters.
     4962The second form skips the next $N$ characters, including newline.
    48884963If the match successes, the input characters are discarded, and input continues with the next character.
    48894964If the match fails, the input characters are left unread.
    48904965\begin{cfa}[belowskip=0pt]
    4891 char sk[$\,$] = "abc";
     4966char sk[§\,§] = "abc";
    48924967sin | "abc " | skip( sk ) | skip( 5 ); // match input sequence
    48934968\end{cfa}
    … …  
    48994974
    49004975\item
    4901 \Indexc{wdi}( maximum, reference-value )\index{manipulator!wdi@©wdi©}
    4902 For all types except ©char©, maximum is the maximum number of characters read for the current operation.
     4976\Indexc{wdi}( maximum, variable )\index{manipulator!wdi@©wdi©}
     4977For all types except ©char *©, whitespace is skipped until an appropriate value is found for the specified variable type.
     4978maximum is the maximum number of characters read for the current operation.
    49034979\begin{cfa}[belowskip=0pt]
    4904 char s[10];   int i;   double d;   
    4905 sin | wdi( 4, s ) | wdi( 3, i ) | wdi( 8, d );  // c == "abcd", i == 123, d == 3.456E+2
     4980char ch;   char ca[3];   int i;   double d;   
     4981sin | wdi( sizeof(ch), ch ) | wdi( sizeof(ca), ca[0] ) | wdi( 3, i ) | wdi( 8, d );  // c == 'a', ca == "bcd", i == 123, d == 345.6
    49064982\end{cfa}
    49074983\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    49084984®abcd1233.456E+2®
    49094985\end{cfa}
     4986Here, ©ca[0]© is type ©char©, so the width reads 3 characters \Textbf{without} a null terminator.
     4987
    49104988Note, input ©wdi© cannot be overloaded with output ©wd© because both have the same parameters but return different types.
    49114989Currently, \CFA cannot distinguish between these two manipulators in the middle of an ©sout©/©sin© expression based on return type.
     4990
     4991\item
     4992\Indexc{wdi}( maximum size, ©char s[]© )\index{manipulator!wdi@©wdi©}
     4993For type ©char *©, maximum is the maximum number of characters read for the current operation.
     4994Any number of non-whitespace characters, stopping at the first whitespace character found. A terminating null character is automatically added at the end of the stored sequence
     4995\begin{cfa}[belowskip=0pt]
     4996char cstr[10];
     4997sin | wdi( sizeof(cstr), cstr );
     4998\end{cfa}
     4999\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
     5000®abcd1233.456E+2®
     5001\end{cfa}
     5002
     5003\item
     5004\Indexc{wdi}( maximum size, maximum read, ©char s[]© )\index{manipulator!wdi@©wdi©}
     5005For type ©char *©, maximum is the maximum number of characters read for the current operation.
     5006\begin{cfa}[belowskip=0pt]
     5007char ch;   char ca[3];   int i;   double d;   
     5008sin | wdi( sizeof(ch), ch ) | wdi( sizeof(ca), ca[0] ) | wdi( 3, i ) | wdi( 8, d );  // c == 'a', ca == "bcd", i == 123, d == 345.6
     5009\end{cfa}
     5010\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
     5011®abcd1233.456E+2®
     5012\end{cfa}
    49125013
    49135014\item
    … …  
    49465047\end{cfa}
    49475048
     5049\Indexc{quoted}( char delimit, wdi-input-string )\index{manipulator!quoted@©quoted©}
     5050Is an ©excl© with scanset ©"delimit"©, which consumes all characters up to the delimit character.
     5051If the delimit character is omitted, it defaults to ©'\n'© (newline).
     5052
    49485053\item
    49495054\Indexc{getline}( char delimit, wdi-input-string )\index{manipulator!getline@©getline©}
    4950 Is an @excl@ with scanset ©"delimit"©, which consumes all characters up to the delimit character.
     5055Is an ©excl© with scanset ©"delimit"©, which consumes all characters up to the delimit character.
    49515056If the delimit character is omitted, it defaults to ©'\n'© (newline).
    49525057\end{enumerate}
    … …  
    49585063For example, if two threads execute the following:
    49595064\begin{cfa}
    4960 $\emph{thread\(_1\)}$ : sout | "abc " | "def ";
    4961 $\emph{thread\(_2\)}$ : sout | "uvw " | "xyz ";
     5065§\emph{thread\(_1\)}§ : sout | "abc " | "def ";
     5066§\emph{thread\(_2\)}§ : sout | "uvw " | "xyz ";
    49625067\end{cfa}
    49635068possible outputs are:
    … …  
    49995104The common usage is the short form of the mutex statement\index{ostream@©ostream©!mutex@©mutex©} to lock a stream during a single cascaded I/O expression, \eg:
    50005105\begin{cfa}
    5001 $\emph{thread\(_1\)}$ : ®mutex( sout )® sout | "abc " | "def ";
    5002 $\emph{thread\(_2\)}$ : ®mutex( sout )® sout | "uvw " | "xyz ";
     5106§\emph{thread\(_1\)}§ : ®mutex( sout )® sout | "abc " | "def ";
     5107§\emph{thread\(_2\)}§ : ®mutex( sout )® sout | "uvw " | "xyz ";
    50035108\end{cfa}
    50045109Now, the order of the thread execution is still non-deterministic, but the output is constrained to two possible lines in either order.
    … …  
    50615166Cultures use different syntax, called a \newterm{locale}, for printing numbers so they are easier to read, \eg:
    50625167\begin{cfa}
    5063 12®,®345®.®123          $\C[1.25in]{// comma separator, period decimal-point}$
     516812®,®345®.®123          §\C[1.25in]{// comma separator, period decimal-point}§
    5064516912®.®345®,®123          §\C{// period separator, comma decimal-point}§
    5065 12$\Sp$345®,®123®.®     §\C{// space separator, comma decimal-point, period terminator}\CRT§
     517012§\Sp§345®,®123®.®     §\C{// space separator, comma decimal-point, period terminator}\CRT§
    50665171\end{cfa}
    50675172A locale is selected with function ©setlocale©, and the corresponding locale package \emph{must} be installed on the underlying system;
    … …  
    51095214Ukraine uk_UA.utf8
    5110521512 123 1 234 12 345 123 456 1 234 567
    5111 12®.® 123®,®1®.® 1$\Sp$234®,®12®.® 12$\Sp$ 345®,®123®.® 123$\Sp$ 456®,®1234®.® 1$\Sp$ 234$\Sp$567®,®12345®.®
     521612®.® 123®,®1®.® 1§\Sp§234®,®12®.® 12§\Sp§ 345®,®123®.® 123§\Sp§ 456®,®1234®.® 1§\Sp§ 234§\Sp§567®,®12345®.®
    51125217
    51135218Default locale off C
    … …  
    54615566
    54625567\subsection{Operator}
     5568\label{s:Operator}
    54635569
    54645570\CFA also allows operators to be overloaded, to simplify the use of user-defined types.
    … …  
    73327438
    73337439\Index*[C++]{\CC{}} is a general-purpose programming language.
    7334 It has imperative, object-oriented and generic programming features, while also providing facilities for low-level memory manipulation. (Wikipedia)
    7335 
    7336 The primary focus of \CC seems to be adding object-oriented programming to C, and this is the primary difference between \CC and Do.
     7440It is an imperative, object-oriented and generic programming language, while also providing facilities for low-level memory manipulation.
     7441The primary focus of \CC was adding object-oriented programming to C, and this is the primary difference between \CC and \CFA.
    73377442\CC uses classes to encapsulate data and the functions that operate on that data, and to hide the internal representation of the data.
    73387443\CFA uses modules instead to perform these same tasks.
    … …  
    73527457\subsection{Go}
    73537458
    7354 \Index*{Go}, also commonly referred to as golang, is a programming language developed at Google in 2007 [.].
     7459\Index*{Go}, also commonly referred to as golang, is a programming language developed at Google in 2007~\cite{Go}.
    73557460It is a statically typed language with syntax loosely derived from that of C, adding garbage collection, type
    73567461safety, some structural typing capabilities, additional built-in types such as variable-length arrays and key-value maps, and a large standard library. (Wikipedia)
    … …  
    74067511In \CFA, there are ambiguous cases with dereference and operator identifiers, \eg ©int *?*?()©, where the string ©*?*?© can be interpreted as:
    74077512\begin{cfa}
    7408 *?$\Sp$*? §\C{// dereference operator, dereference operator}§
    7409 *$\Sp$?*? §\C{// dereference, multiplication operator}§
     7513*?§\Sp§*?                                                               §\C{// dereference operator, dereference operator}§
     7514*§\Sp§?*?                                                               §\C{// dereference, multiplication operator}§
    74107515\end{cfa}
    74117516By default, the first interpretation is selected, which does not yield a meaningful parse.
    … …  
    74167521The ambiguity occurs when the deference operator has no parameters:
    74177522\begin{cfa}
    7418 *?()$\R{\textvisiblespace...}$ ;
    7419 *?()$\R{\textvisiblespace...}$(...) ;
     7523*?()§\R{\textvisiblespace...}§ ;
     7524*?()§\R{\textvisiblespace...}§(...) ;
    74207525\end{cfa}
    74217526requiring arbitrary whitespace look-ahead for the routine-call parameter-list to disambiguate.
    … …  
    74257530The remaining cases are with the increment/decrement operators and conditional expression, \eg:
    74267531\begin{cfa}
    7427 i++?$\R{\textvisiblespace...}$(...);
    7428 i?++$\R{\textvisiblespace...}$(...);
     7532i++?§\R{\textvisiblespace...}§(...);
     7533i?++§\R{\textvisiblespace...}§(...);
    74297534\end{cfa}
    74307535requiring arbitrary whitespace look-ahead for the operator parameter-list, even though that interpretation is an incorrect expression (juxtaposed identifiers).
    74317536Therefore, it is necessary to disambiguate these cases with a space:
    74327537\begin{cfa}
    7433 i++$\Sp$? i : 0;
    7434 i?$\Sp$++i : 0;
     7538i++§\Sp§? i : 0;
     7539i?§\Sp§++i : 0;
    74357540\end{cfa}
    74367541
    … …  
    74597564\eg:
    74607565\begin{cfa}
    7461 x; §\C{// int x}§
    7462 *y; §\C{// int *y}§
    7463 f( p1, p2 ); §\C{// int f( int p1, int p2 );}§
    7464 g( p1, p2 ) int p1, p2; §\C{// int g( int p1, int p2 );}§
     7566x;                                                              §\C{// int x}§
     7567*y;                                                             §\C{// int * y}§
     7568f( p1, p2 );                                    §\C{// int f( int p1, int p2 );}§
     7569g( p1, p2 ) int p1, p2;                 §\C{// int g( int p1, int p2 );}§
    74657570\end{cfa}
    74667571\CFA continues to support K\&R routine definitions:
    74677572\begin{cfa}
    7468 f( a, b, c ) §\C{// default int return}§
    7469         int a, b; char c §\C{// K\&R parameter declarations}§
     7573f( a, b, c )                                    §\C{// default int return}§
     7574        int a, b; char c;                       §\C{// K\&R parameter declarations}§
    74707575{
    74717576        ...
    … …  
    74867591int rtn( int i );
    74877592int rtn( char c );
    7488 rtn( 'x' ); §\C{// programmer expects 2nd rtn to be called}§
     7593rtn( 'x' );                                             §\C{// programmer expects 2nd rtn to be called}§
    74897594\end{cfa}
    74907595\item[Rationale:] it is more intuitive for the call to ©rtn© to match the second version of definition of ©rtn© rather than the first.
    … …  
    75087613\item[Change:] make string literals ©const©:
    75097614\begin{cfa}
    7510 char * p = "abc"; §\C{// valid in C, deprecated in \CFA}§
    7511 char * q = expr ? "abc" : "de"; §\C{// valid in C, invalid in \CFA}§
     7615char * p = "abc";                               §\C{// valid in C, deprecated in \CFA}§
     7616char * q = expr ? "abc" : "de"; §\C{// valid in C, invalid in \CFA}§
    75127617\end{cfa}
    75137618The type of a string literal is changed from ©[] char© to ©const [] char©.
    … …  
    75167621\begin{cfa}
    75177622char * p = "abc";
    7518 p[0] = 'w'; §\C{// segment fault or change constant literal}§
     7623p[0] = 'w';                                             §\C{// segment fault or change constant literal}§
    75197624\end{cfa}
    75207625The same problem occurs when passing a string literal to a routine that changes its argument.
    … …  
    75287633\item[Change:] remove \newterm{tentative definitions}, which only occurs at file scope:
    75297634\begin{cfa}
    7530 int i; §\C{// forward definition}§
    7531 int *j = ®&i®; §\C{// forward reference, valid in C, invalid in \CFA}§
    7532 int i = 0; §\C{// definition}§
     7635int i;                                                  §\C{// forward definition}§
     7636int *j = ®&i®;                                  §\C{// forward reference, valid in C, invalid in \CFA}§
     7637int i = 0;                                              §\C{// definition}§
    75337638\end{cfa}
    75347639is valid in C, and invalid in \CFA because duplicate overloaded object definitions at the same scope level are disallowed.
    … …  
    75367641\begin{cfa}
    75377642struct X { int i; struct X *next; };
    7538 static struct X a; §\C{// forward definition}§
    7539 static struct X b = { 0, ®&a® };§\C{// forward reference, valid in C, invalid in \CFA}§
    7540 static struct X a = { 1, &b }; §\C{// definition}§
     7643static struct X a;                              §\C{// forward definition}§
     7644static struct X b = { 0, ®&a® }; §\C{// forward reference, valid in C, invalid in \CFA}§
     7645static struct X a = { 1, &b };  §\C{// definition}§
    75417646\end{cfa}
    75427647\item[Rationale:] avoids having different initialization rules for builtin types and user-defined types.
    … …  
    75527657enum ®Colour® { R, G, B, Y, C, M };
    75537658struct Person {
    7554         enum ®Colour® { R, G, B };      $\C[7cm]{// nested type}$
    7555         struct Face { §\C{// nested type}§
    7556                 ®Colour® Eyes, Hair; §\C{// type defined outside (1 level)}§
     7659        enum ®Colour® { R, G, B };      §\C{// nested type}§
     7660        struct Face {                           §\C{// nested type}§
     7661                ®Colour® Eyes, Hair;    §\C{// type defined outside (1 level)}§
    75577662        };
    7558         ®.Colour® shirt; §\C{// type defined outside (top level)}§
    7559         ®Colour® pants; §\C{// type defined same level}§
    7560         Face looks[10]; §\C{// type defined same level}§
     7663        ®.Colour® shirt;                        §\C{// type defined outside (top level)}§
     7664        ®Colour® pants;                         §\C{// type defined same level}§
     7665        Face looks[10];                         §\C{// type defined same level}§
    75617666};
    7562 ®Colour® c = R; §\C{// type/enum defined same level}§
    7563 Person®.Colour® pc = Person®.®R;§\C{// type/enum defined inside}§
    7564 Person®.®Face pretty; §\C{// type defined inside}\CRT§
     7667®Colour® c = R;                                 §\C{// type/enum defined same level}§
     7668Person®.Colour® pc = Person®.®R;        §\C{// type/enum defined inside}§
     7669Person®.®Face pretty;                   §\C{// type defined inside}§
    75657670\end{cfa}
    75667671In 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.
    … …  
    76397744\CFA introduces the following new \Index{keyword}s, which cannot be used as identifiers.
    76407745
     7746\begin{cquote}
     7747\Indexc{basetypeof}, \Indexc{choose}, \Indexc{coroutine}, \Indexc{disable},
     7748\Indexc{enable}, \Indexc{exception}, \Indexc{fallthrough}, \Indexc{fallthru},
     7749\Indexc{finally}, \Indexc{fixup}, \Indexc{forall},\Indexc{generator},
     7750\Indexc{int128}, \Indexc{monitor}, \Indexc{mutex}, \Indexc{one_t},
     7751\Indexc{report}, \Indexc{suspend}, \Indexc{throw}, \Indexc{throwResume},
     7752\Indexc{trait}, \Indexc{try}, \Indexc{virtual}, \Indexc{waitfor},
     7753\Indexc{when}, \Indexc{with}, \Indexc{zero_t}
     7754\end{cquote}
     7755\CFA introduces the following new \Index{quasi-keyword}s, which can be used as identifiers.
     7756\begin{cquote}
     7757\Indexc{catch}, \Indexc{catchResume}, \Indexc{finally}, \Indexc{fixup}, \Indexc{or}, \Indexc{timeout}
     7758\end{cquote}
     7759
     7760\begin{comment}
    76417761\begin{cquote}
    76427762\begin{tabular}{@{}lllllll@{}}
    … …  
    77077827\end{tabular}
    77087828\end{cquote}
     7829\end{comment}
     7830
    77097831
    77107832\section{Standard Headers}
    77117833\label{s:StandardHeaders}
    77127834
    7713 \Celeven prescribes the following standard header-files~\cite[\S~7.1.2]{C11} and \CFA adds to this list:
     7835\Celeven prescribes the following standard header-files~\cite[\S~7.1.2]{C11}:
     7836\begin{cquote}
     7837\Indexc{assert.h}, \Indexc{complex.h}, \Indexc{ctype.h}, \Indexc{errno.h}, \Indexc{fenv.h},
     7838\Indexc[deletekeywords=float]{float.h}, \Indexc{inttypes.h}, \Indexc{iso646.h}, \Indexc{limits.h},
     7839\Indexc{locale.h}, \Indexc{math.h}, \Indexc{setjmp.h}, \Indexc{signal.h}, \Indexc{stdalign.h},
     7840\Indexc{stdarg.h}, \Indexc{stdatomic.h}, \Indexc{stdbool.h}, \Indexc{stddef.h}, \Indexc{stdint.h},
     7841\Indexc{stdio.h}, \Indexc{stdlib.h}, \Indexc{stdnoreturn.h}, \Indexc{string.h}, \Indexc{tgmath.h},
     7842\Indexc{threads.h}, \Indexc{time.h}, \Indexc{uchar.h}, \Indexc{wchar.h}, \Indexc{wctype.h}
     7843\end{cquote}
     7844and \CFA adds to this list:
     7845\begin{cquote}
     7846\Indexc{gmp.h}, \Indexc{malloc.h}, \Indexc{unistd.h}
     7847\end{cquote}
     7848\begin{comment}
    77147849\begin{cquote}
    77157850\begin{tabular}{@{}llllll|l@{}}
    … …  
    77737908\end{tabular}
    77747909\end{cquote}
     7910\end{comment}
    77757911For the prescribed head-files, \CFA uses header interposition to wraps these includes in an ©extern "C"©;
    77767912hence, names in these include files are not mangled\index{mangling!name} \see{\VRef{s:Interoperability}}.
    … …  
    78377973Type-safe allocation is provided for all C allocation routines and new \CFA allocation routines, \eg in
    78387974\begin{cfa}
    7839 int * ip = (int *)malloc( sizeof(int) );                §\C{// C}§
    7840 int * ip = malloc();                                                    §\C{// \CFA type-safe version of C malloc}§
    7841 int * ip = alloc();                                                             §\C{// \CFA type-safe uniform alloc}§
     7975int * ip = (int *)malloc( sizeof(int) ); §\C{// C}§
     7976int * ip = malloc();                                    §\C{// \CFA type-safe version of C malloc}§
     7977int * ip = alloc();                                             §\C{// \CFA type-safe uniform alloc}§
    78427978\end{cfa}
    78437979the latter two allocations determine the allocation size from the type of ©p© (©int©) and cast the pointer to the allocated storage to ©int *©.
    … …  
    78467982\begin{cfa}
    78477983struct S { int i; } __attribute__(( aligned( 128 ) )); // cache-line alignment
    7848 S * sp = malloc();                                                              §\C{// honour type alignment}§
     7984S * sp = malloc();                                              §\C{// honour type alignment}§
    78497985\end{cfa}
    78507986the storage allocation is implicitly aligned to 128 rather than the default 16.
    … …  
    78617997\CFA memory management extends allocation to support constructors for initialization of allocated storage, \eg in
    78627998\begin{cfa}
    7863 struct S { int i; };                                                    §\C{// cache-line alignment}§
     7999struct S { int i; };                                    §\C{// cache-line alignment}§
    78648000void ?{}( S & s, int i ) { s.i = i; }
    78658001// assume ?|? operator for printing an S
    78668002
    7867 S & sp = *®new®( 3 );                                                   §\C{// call constructor after allocation}§
     8003S & sp = *®new®( 3 );                                   §\C{// call constructor after allocation}§
    78688004sout | sp.i;
    78698005®delete®( &sp );
    78708006
    7871 S * spa = ®anew®( 10, 5 );                                              §\C{// allocate array and initialize each array element}§
     8007S * spa = ®anew®( 10, 5 );                              §\C{// allocate array and initialize each array element}§
    78728008for ( i; 10 ) sout | spa[i] | nonl;
    78738009sout | nl;
    … …  
    78818017extern "C" {
    78828018        // C unsafe allocation
    7883         void * malloc( size_t size );$\indexc{malloc}$
    7884         void * calloc( size_t dim, size_t size );$\indexc{calloc}$
    7885         void * realloc( void * ptr, size_t size );$\indexc{realloc}$
    7886         void * memalign( size_t align, size_t size );$\indexc{memalign}$
    7887         void * aligned_alloc( size_t align, size_t size );$\indexc{aligned_alloc}$
    7888         int posix_memalign( void ** ptr, size_t align, size_t size );$\indexc{posix_memalign}$
    7889         void * cmemalign( size_t alignment, size_t noOfElems, size_t elemSize );$\indexc{cmemalign}$ // CFA
     8019        void * malloc( size_t size );§\indexc{malloc}§
     8020        void * calloc( size_t dim, size_t size );§\indexc{calloc}§
     8021        void * realloc( void * ptr, size_t size );§\indexc{realloc}§
     8022        void * memalign( size_t align, size_t size );§\indexc{memalign}§
     8023        void * aligned_alloc( size_t align, size_t size );§\indexc{aligned_alloc}§
     8024        int posix_memalign( void ** ptr, size_t align, size_t size );§\indexc{posix_memalign}§
     8025        void * cmemalign( size_t alignment, size_t noOfElems, size_t elemSize );§\indexc{cmemalign}§ // CFA
    78908026
    78918027        // C unsafe initialization/copy
    7892         void * memset( void * dest, int c, size_t size );$\indexc{memset}$
    7893         void * memcpy( void * dest, const void * src, size_t size );$\indexc{memcpy}$
     8028        void * memset( void * dest, int c, size_t size );§\indexc{memset}§
     8029        void * memcpy( void * dest, const void * src, size_t size );§\indexc{memcpy}§
    78948030}
    78958031
    … …  
    78978033
    78988034forall( dtype T | sized(T) ) {
    7899         // $\CFA$ safe equivalents, i.e., implicit size specification
     8035        // §\CFA§ safe equivalents, i.e., implicit size specification
    79008036        T * malloc( void );
    79018037        T * calloc( size_t dim );
    … …  
    79068042        int posix_memalign( T ** ptr, size_t align );
    79078043
    7908         // $\CFA$ safe general allocation, fill, resize, alignment, array
    7909         T * alloc( void );$\indexc{alloc}$                                      $\C[3.5in]{// variable, T size}$
     8044        // §\CFA§ safe general allocation, fill, resize, alignment, array
     8045        T * alloc( void );§\indexc{alloc}§                                      §\C[3.5in]{// variable, T size}§
    79108046        T * alloc( size_t dim );                                                        §\C{// array[dim], T size elements}§
    79118047        T * alloc( T ptr[], size_t dim );                                       §\C{// realloc array[dim], T size elements}§
    79128048
    7913         T * alloc_set( char fill );$\indexc{alloc_set}$         §\C{// variable, T size, fill bytes with value}§
     8049        T * alloc_set( char fill );§\indexc{alloc_set}§         §\C{// variable, T size, fill bytes with value}§
    79148050        T * alloc_set( T fill );                                                        §\C{// variable, T size, fill with value}§
    79158051        T * alloc_set( size_t dim, char fill );                         §\C{// array[dim], T size elements, fill bytes with value}§
    … …  
    79308066        T * alloc_align_set( T ptr[], size_t align, size_t dim, char fill ); §\C{// realloc new aligned array[dim], fill new bytes with value}§
    79318067
    7932         // $\CFA$ safe initialization/copy, i.e., implicit size specification
    7933         T * memset( T * dest, char fill );$\indexc{memset}$
    7934         T * memcpy( T * dest, const T * src );$\indexc{memcpy}$
    7935 
    7936         // $\CFA$ safe initialization/copy, i.e., implicit size specification, array types
     8068        // §\CFA§ safe initialization/copy, i.e., implicit size specification
     8069        T * memset( T * dest, char fill );§\indexc{memset}§
     8070        T * memcpy( T * dest, const T * src );§\indexc{memcpy}§
     8071
     8072        // §\CFA§ safe initialization/copy, i.e., implicit size specification, array types
    79378073        T * amemset( T dest[], char fill, size_t dim );
    79388074        T * amemcpy( T dest[], const T src[], size_t dim );
    79398075}
    79408076
    7941 // $\CFA$ allocation/deallocation and constructor/destructor, non-array types
    7942 forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * new( Params p );$\indexc{new}$
    7943 forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void delete( T * ptr );$\indexc{delete}$
     8077// §\CFA§ allocation/deallocation and constructor/destructor, non-array types
     8078forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * new( Params p );§\indexc{new}§
     8079forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void delete( T * ptr );§\indexc{delete}§
    79448080forall( dtype T, ttype Params | sized(T) | { void ^?{}( T & ); void delete( Params ); } )
    79458081  void delete( T * ptr, Params rest );
    79468082
    7947 // $\CFA$ allocation/deallocation and constructor/destructor, array types
    7948 forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * anew( size_t dim, Params p );$\indexc{anew}$
    7949 forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void adelete( size_t dim, T arr[] );$\indexc{adelete}$
     8083// §\CFA§ allocation/deallocation and constructor/destructor, array types
     8084forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * anew( size_t dim, Params p );§\indexc{anew}§
     8085forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void adelete( size_t dim, T arr[] );§\indexc{adelete}§
    79508086forall( dtype T | sized(T) | { void ^?{}( T & ); }, ttype Params | { void adelete( Params ); } )
    79518087  void adelete( size_t dim, T arr[], Params rest );
    … …  
    79578093\leavevmode
    79588094\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    7959 int ato( const char * ptr );$\indexc{ato}$
     8095int ato( const char * ptr );§\indexc{ato}§
    79608096unsigned int ato( const char * ptr );
    79618097long int ato( const char * ptr );
    … …  
    79908126\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    79918127forall( T | { int ?<?( T, T ); } ) §\C{// location}§
    7992 T * bsearch( T key, const T * arr, size_t dim );$\indexc{bsearch}$
     8128T * bsearch( T key, const T * arr, size_t dim );§\indexc{bsearch}§
    79938129
    79948130forall( T | { int ?<?( T, T ); } ) §\C{// position}§
    … …  
    79968132
    79978133forall( T | { int ?<?( T, T ); } )
    7998 void qsort( const T * arr, size_t dim );$\indexc{qsort}$
     8134void qsort( const T * arr, size_t dim );§\indexc{qsort}§
    79998135
    80008136forall( E | { int ?<?( E, E ); } ) {
    8001         E * bsearch( E key, const E * vals, size_t dim );$\indexc{bsearch}$ §\C{// location}§
     8137        E * bsearch( E key, const E * vals, size_t dim );§\indexc{bsearch}§ §\C{// location}§
    80028138        size_t bsearch( E key, const E * vals, size_t dim );§\C{// position}§
    8003         E * bsearchl( E key, const E * vals, size_t dim );$\indexc{bsearchl}$
     8139        E * bsearchl( E key, const E * vals, size_t dim );§\indexc{bsearchl}§
    80048140        size_t bsearchl( E key, const E * vals, size_t dim );
    8005         E * bsearchu( E key, const E * vals, size_t dim );$\indexc{bsearchu}$
     8141        E * bsearchu( E key, const E * vals, size_t dim );§\indexc{bsearchu}§
    80068142        size_t bsearchu( E key, const E * vals, size_t dim );
    80078143}
    … …  
    80178153
    80188154forall( E | { int ?<?( E, E ); } ) {
    8019         void qsort( E * vals, size_t dim );$\indexc{qsort}$
     8155        void qsort( E * vals, size_t dim );§\indexc{qsort}§
    80208156}
    80218157\end{cfa}
    … …  
    80268162\leavevmode
    80278163\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8028 unsigned char abs( signed char );$\indexc{abs}$
     8164unsigned char abs( signed char );§\indexc{abs}§
    80298165int abs( int );
    80308166unsigned long int abs( long int );
    … …  
    80418177
    80428178
    8043 \subsection{Random Numbers}
     8179\subsection{C Random Numbers}
    80448180
    80458181\leavevmode
    80468182\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8047 void srandom( unsigned int seed );$\indexc{srandom}$
    8048 char random( void );$\indexc{random}$
     8183void srandom( unsigned int seed );§\indexc{srandom}§
     8184char random( void );§\indexc{random}§
    80498185char random( char u ); §\C{// [0,u)}§
    80508186char random( char l, char u ); §\C{// [l,u]}§
    … …  
    80738209\leavevmode
    80748210\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8075 forall( T | { int ?<?( T, T ); } ) T min( T t1, T t2 );$\indexc{min}$
    8076 forall( T | { int ?>?( T, T ); } ) T max( T t1, T t2 );$\indexc{max}$
    8077 forall( T | { T min( T, T ); T max( T, T ); } ) T clamp( T value, T min_val, T max_val );$\indexc{clamp}$
    8078 forall( T ) void swap( T * t1, T * t2 );$\indexc{swap}$
     8211forall( T | { int ?<?( T, T ); } ) T min( T t1, T t2 );§\indexc{min}§
     8212forall( T | { int ?>?( T, T ); } ) T max( T t1, T t2 );§\indexc{max}§
     8213forall( T | { T min( T, T ); T max( T, T ); } ) T clamp( T value, T min_val, T max_val );§\indexc{clamp}§
     8214forall( T ) void swap( T * t1, T * t2 );§\indexc{swap}§
    80798215\end{cfa}
    80808216
    … …  
    80908226\leavevmode
    80918227\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8092 float ?%?( float, float );$\indexc{fmod}$
     8228float ?%?( float, float );§\indexc{fmod}§
    80938229float fmod( float, float );
    80948230double ?%?( double, double );
    … …  
    80978233long double fmod( long double, long double );
    80988234
    8099 float remainder( float, float );$\indexc{remainder}$
     8235float remainder( float, float );§\indexc{remainder}§
    81008236double remainder( double, double );
    81018237long double remainder( long double, long double );
    81028238
    8103 float remquo( float, float, int * );$\indexc{remquo}$
     8239float remquo( float, float, int * );§\indexc{remquo}§
    81048240double remquo( double, double, int * );
    81058241long double remquo( long double, long double, int * );
    … …  
    81128248[ int, long double ] div( long double, long double );
    81138249
    8114 float fma( float, float, float );$\indexc{fma}$
     8250float fma( float, float, float );§\indexc{fma}§
    81158251double fma( double, double, double );
    81168252long double fma( long double, long double, long double );
    81178253
    8118 float fdim( float, float );$\indexc{fdim}$
     8254float fdim( float, float );§\indexc{fdim}§
    81198255double fdim( double, double );
    81208256long double fdim( long double, long double );
    81218257
    8122 float nan( const char * );$\indexc{nan}$
     8258float nan( const char * );§\indexc{nan}§
    81238259double nan( const char * );
    81248260long double nan( const char * );
    … …  
    81308266\leavevmode
    81318267\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8132 float exp( float );$\indexc{exp}$
     8268float exp( float );§\indexc{exp}§
    81338269double exp( double );
    81348270long double exp( long double );
    … …  
    81378273long double _Complex exp( long double _Complex );
    81388274
    8139 float exp2( float );$\indexc{exp2}$
     8275float exp2( float );§\indexc{exp2}§
    81408276double exp2( double );
    81418277long double exp2( long double );
    … …  
    81448280// long double _Complex exp2( long double _Complex );
    81458281
    8146 float expm1( float );$\indexc{expm1}$
     8282float expm1( float );§\indexc{expm1}§
    81478283double expm1( double );
    81488284long double expm1( long double );
    81498285
    8150 float pow( float, float );$\indexc{pow}$
     8286float pow( float, float );§\indexc{pow}§
    81518287double pow( double, double );
    81528288long double pow( long double, long double );
    … …  
    81618297\leavevmode
    81628298\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8163 float log( float );$\indexc{log}$
     8299float log( float );§\indexc{log}§
    81648300double log( double );
    81658301long double log( long double );
    … …  
    81688304long double _Complex log( long double _Complex );
    81698305
    8170 int log2( unsigned int );$\indexc{log2}$
     8306int log2( unsigned int );§\indexc{log2}§
    81718307long int log2( unsigned long int );
    81728308long long int log2( unsigned long long int )
    … …  
    81788314// long double _Complex log2( long double _Complex );
    81798315
    8180 float log10( float );$\indexc{log10}$
     8316float log10( float );§\indexc{log10}§
    81818317double log10( double );
    81828318long double log10( long double );
    … …  
    81858321// long double _Complex log10( long double _Complex );
    81868322
    8187 float log1p( float );$\indexc{log1p}$
     8323float log1p( float );§\indexc{log1p}§
    81888324double log1p( double );
    81898325long double log1p( long double );
    81908326
    8191 int ilogb( float );$\indexc{ilogb}$
     8327int ilogb( float );§\indexc{ilogb}§
    81928328int ilogb( double );
    81938329int ilogb( long double );
    81948330
    8195 float logb( float );$\indexc{logb}$
     8331float logb( float );§\indexc{logb}§
    81968332double logb( double );
    81978333long double logb( long double );
    81988334
    8199 float sqrt( float );$\indexc{sqrt}$
     8335float sqrt( float );§\indexc{sqrt}§
    82008336double sqrt( double );
    82018337long double sqrt( long double );
    … …  
    82048340long double _Complex sqrt( long double _Complex );
    82058341
    8206 float cbrt( float );$\indexc{cbrt}$
     8342float cbrt( float );§\indexc{cbrt}§
    82078343double cbrt( double );
    82088344long double cbrt( long double );
    82098345
    8210 float hypot( float, float );$\indexc{hypot}$
     8346float hypot( float, float );§\indexc{hypot}§
    82118347double hypot( double, double );
    82128348long double hypot( long double, long double );
    … …  
    82188354\leavevmode
    82198355\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8220 float sin( float );$\indexc{sin}$
     8356float sin( float );§\indexc{sin}§
    82218357double sin( double );
    82228358long double sin( long double );
    … …  
    82258361long double _Complex sin( long double _Complex );
    82268362
    8227 float cos( float );$\indexc{cos}$
     8363float cos( float );§\indexc{cos}§
    82288364double cos( double );
    82298365long double cos( long double );
    … …  
    82328368long double _Complex cos( long double _Complex );
    82338369
    8234 float tan( float );$\indexc{tan}$
     8370float tan( float );§\indexc{tan}§
    82358371double tan( double );
    82368372long double tan( long double );
    … …  
    82398375long double _Complex tan( long double _Complex );
    82408376
    8241 float asin( float );$\indexc{asin}$
     8377float asin( float );§\indexc{asin}§
    82428378double asin( double );
    82438379long double asin( long double );
    … …  
    82468382long double _Complex asin( long double _Complex );
    82478383
    8248 float acos( float );$\indexc{acos}$
     8384float acos( float );§\indexc{acos}§
    82498385double acos( double );
    82508386long double acos( long double );
    … …  
    82538389long double _Complex acos( long double _Complex );
    82548390
    8255 float atan( float );$\indexc{atan}$
     8391float atan( float );§\indexc{atan}§
    82568392double atan( double );
    82578393long double atan( long double );
    … …  
    82608396long double _Complex atan( long double _Complex );
    82618397
    8262 float atan2( float, float );$\indexc{atan2}$
     8398float atan2( float, float );§\indexc{atan2}§
    82638399double atan2( double, double );
    82648400long double atan2( long double, long double );
    82658401
    82668402float atan( float, float ); §\C{// alternative name for atan2}§
    8267 double atan( double, double );$\indexc{atan}$
     8403double atan( double, double );§\indexc{atan}§
    82688404long double atan( long double, long double );
    82698405\end{cfa}
    … …  
    82748410\leavevmode
    82758411\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8276 float sinh( float );$\indexc{sinh}$
     8412float sinh( float );§\indexc{sinh}§
    82778413double sinh( double );
    82788414long double sinh( long double );
    … …  
    82818417long double _Complex sinh( long double _Complex );
    82828418
    8283 float cosh( float );$\indexc{cosh}$
     8419float cosh( float );§\indexc{cosh}§
    82848420double cosh( double );
    82858421long double cosh( long double );
    … …  
    82888424long double _Complex cosh( long double _Complex );
    82898425
    8290 float tanh( float );$\indexc{tanh}$
     8426float tanh( float );§\indexc{tanh}§
    82918427double tanh( double );
    82928428long double tanh( long double );
    … …  
    82958431long double _Complex tanh( long double _Complex );
    82968432
    8297 float asinh( float );$\indexc{asinh}$
     8433float asinh( float );§\indexc{asinh}§
    82988434double asinh( double );
    82998435long double asinh( long double );
    … …  
    83028438long double _Complex asinh( long double _Complex );
    83038439
    8304 float acosh( float );$\indexc{acosh}$
     8440float acosh( float );§\indexc{acosh}§
    83058441double acosh( double );
    83068442long double acosh( long double );
    … …  
    83098445long double _Complex acosh( long double _Complex );
    83108446
    8311 float atanh( float );$\indexc{atanh}$
     8447float atanh( float );§\indexc{atanh}§
    83128448double atanh( double );
    83138449long double atanh( long double );
    … …  
    83228458\leavevmode
    83238459\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8324 float erf( float );$\indexc{erf}$
     8460float erf( float );§\indexc{erf}§
    83258461double erf( double );
    83268462long double erf( long double );
    … …  
    83298465long double _Complex erf( long double _Complex );
    83308466
    8331 float erfc( float );$\indexc{erfc}$
     8467float erfc( float );§\indexc{erfc}§
    83328468double erfc( double );
    83338469long double erfc( long double );
    … …  
    83368472long double _Complex erfc( long double _Complex );
    83378473
    8338 float lgamma( float );$\indexc{lgamma}$
     8474float lgamma( float );§\indexc{lgamma}§
    83398475double lgamma( double );
    83408476long double lgamma( long double );
    … …  
    83438479long double lgamma( long double, int * );
    83448480
    8345 float tgamma( float );$\indexc{tgamma}$
     8481float tgamma( float );§\indexc{tgamma}§
    83468482double tgamma( double );
    83478483long double tgamma( long double );
    … …  
    83898525unsigned long long int ceiling( unsigned long long int n, unsigned long long int align );
    83908526
    8391 float floor( float );$\indexc{floor}$
     8527float floor( float );§\indexc{floor}§
    83928528double floor( double );
    83938529long double floor( long double );
    83948530
    8395 float ceil( float );$\indexc{ceil}$
     8531float ceil( float );§\indexc{ceil}§
    83968532double ceil( double );
    83978533long double ceil( long double );
    83988534
    8399 float trunc( float );$\indexc{trunc}$
     8535float trunc( float );§\indexc{trunc}§
    84008536double trunc( double );
    84018537long double trunc( long double );
    84028538
    8403 float rint( float );$\indexc{rint}$
     8539float rint( float );§\indexc{rint}§
    84048540long double rint( long double );
    84058541long int rint( float );
    … …  
    84108546long long int rint( long double );
    84118547
    8412 long int lrint( float );$\indexc{lrint}$
     8548long int lrint( float );§\indexc{lrint}§
    84138549long int lrint( double );
    84148550long int lrint( long double );
    … …  
    84178553long long int llrint( long double );
    84188554
    8419 float nearbyint( float );$\indexc{nearbyint}$
     8555float nearbyint( float );§\indexc{nearbyint}§
    84208556double nearbyint( double );
    84218557long double nearbyint( long double );
    84228558
    8423 float round( float );$\indexc{round}$
     8559float round( float );§\indexc{round}§
    84248560long double round( long double );
    84258561long int round( float );
    … …  
    84308566long long int round( long double );
    84318567
    8432 long int lround( float );$\indexc{lround}$
     8568long int lround( float );§\indexc{lround}§
    84338569long int lround( double );
    84348570long int lround( long double );
    … …  
    84438579\leavevmode
    84448580\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    8445 float copysign( float, float );$\indexc{copysign}$
     8581float copysign( float, float );§\indexc{copysign}§
    84468582double copysign( double, double );
    84478583long double copysign( long double, long double );
    84488584
    8449 float frexp( float, int * );$\indexc{frexp}$
     8585float frexp( float, int * );§\indexc{frexp}§
    84508586double frexp( double, int * );
    84518587long double frexp( long double, int * );
    84528588
    8453 float ldexp( float, int );$\indexc{ldexp}$
     8589float ldexp( float, int );§\indexc{ldexp}§
    84548590double ldexp( double, int );
    84558591long double ldexp( long double, int );
    84568592
    8457 [ float, float ] modf( float );$\indexc{modf}$
     8593[ float, float ] modf( float );§\indexc{modf}§
    84588594float modf( float, float * );
    84598595[ double, double ] modf( double );
    … …  
    84628598long double modf( long double, long double * );
    84638599
    8464 float nextafter( float, float );$\indexc{nextafter}$
     8600float nextafter( float, float );§\indexc{nextafter}§
    84658601double nextafter( double, double );
    84668602long double nextafter( long double, long double );
    84678603
    8468 float nexttoward( float, long double );$\indexc{nexttoward}$
     8604float nexttoward( float, long double );§\indexc{nexttoward}§
    84698605double nexttoward( double, long double );
    84708606long double nexttoward( long double, long double );
    84718607
    8472 float scalbn( float, int );$\indexc{scalbn}$
     8608float scalbn( float, int );§\indexc{scalbn}§
    84738609double scalbn( double, int );
    84748610long double scalbn( long double, int );
    84758611
    8476 float scalbln( float, long int );$\indexc{scalbln}$
     8612float scalbln( float, long int );§\indexc{scalbln}§
    84778613double scalbln( double, long int );
    84788614long double scalbln( long double, long int );
    … …  
    87348870All \newterm{pseudo random-number generators} (\newterm{PRNG}) involve some technique to scramble bits of a value, \eg multiplicative recurrence:
    87358871\begin{cfa}
    8736 rand = 36973 * (rand & 65535) + (rand >> 16); // scramble bits
     8872rand = 33967 * (rand + 1063); // scramble bits
    87378873\end{cfa}
    87388874Multiplication of large values adds new least-significant bits and drops most-significant bits.
    … …  
    87418877bits 63--32 (most)      & bits 31--0 (least)    \\
    87428878\hline
    8743 0x0                                     & 0x3e8e36                              \\
    8744 0x5f                            & 0x718c25e1                    \\
    8745 0xad3e                          & 0x7b5f1dbe                    \\
    8746 0xbc3b                          & 0xac69ff19                    \\
    8747 0x1070f                         & 0x2d258dc6                    \\
     8879©0x0©                           & ©0x3e8e36©                    \\
     8880©0x5f©                          & ©0x718c25e1©                  \\
     8881©0xad3e©                        & ©0x7b5f1dbe©                  \\
     8882©0xbc3b©                        & ©0xac69ff19©                  \\
     8883©0x1070f©                       & ©0x2d258dc6©
    87488884\end{tabular}
    87498885\end{quote}
    … …  
    87518887The least-significant bits \emph{appear} random but the same bits are always generated given a fixed starting value, called the \newterm{seed} (value 0x3e8e36 above).
    87528888Hence, if a program uses the same seed, the same sequence of pseudo-random values is generated from the PRNG.
    8753 Often the seed is set to another random value like a program's process identifier (©getpid©\index{getpid@©getpid©}) or time when the program is run;
     8889Often the seed is set to another random value like a program's process identifier (\Indexc{getpid}) or time when the program is run;
    87548890hence, one random value bootstraps another.
    87558891Finally, a PRNG usually generates a range of large values, \eg ©[0, UINT_MAX]©, which are scaled using the modulus operator, \eg ©prng() % 5© produces random values in the range 0--4.
    87568892
    8757 \CFA provides a sequential PRNG type only accessible by a single thread (not thread-safe) and a set of global and companion thread PRNG functions accessible by multiple threads without contention.
     8893\CFA provides 32/64-bit sequential PRNG type only accessible by a single thread (not thread-safe) and a set of global routines and companion thread PRNG functions accessible by multiple threads without contention.
     8894To use the PRNG interface \Textbf{requires including \Indexc{stdlib.hfa}}.
    87588895\begin{itemize}
    87598896\item
    8760 The ©PRNG© type is for sequential programs, like coroutining:
    8761 \begin{cfa}
    8762 struct PRNG { ... }; $\C[3.75in]{// opaque type}$
    8763 void ?{}( PRNG & prng ); §\C{// random seed}§
    8764 void ?{}( PRNG & prng, uint32_t seed ); §\C{// fixed seed}§
    8765 void set_seed( PRNG & prng, uint32_t seed ); §\C{// set seed}§
    8766 uint32_t get_seed( PRNG & prng ); §\C{// get seed}§
    8767 uint32_t prng( PRNG & prng ); §\C{// [0,UINT\_MAX]}§
    8768 uint32_t prng( PRNG & prng, uint32_t u ); §\C{// [0,u)}§
    8769 uint32_t prng( PRNG & prng, uint32_t l, uint32_t u ); §\C{// [l,u]}§
    8770 uint32_t calls( PRNG & prng ); §\C{// number of calls}\CRT§
    8771 \end{cfa}
     8897The ©PRNG© types for sequential programs, including coroutining, are:
     8898\begin{cfa}
     8899struct PRNG32 {};                                               §\C{// opaque type, no copy or assignment}§
     8900void ?{}( PRNG32 & prng, uint32_t seed ); §\C{// fixed seed}§
     8901void ?{}( PRNG32 & prng );                              §\C{// random seed}§
     8902void set_seed( PRNG32 & prng, uint32_t seed ); §\C{// set seed}§
     8903uint32_t get_seed( PRNG32 & prng );             §\C{// get seed}§
     8904uint32_t prng( PRNG32 & prng );                 §\C{// [0,UINT\_MAX]}§
     8905uint32_t prng( PRNG32 & prng, uint32_t u ); §\C{// [0,u)}§
     8906uint32_t prng( PRNG32 & prng, uint32_t l, uint32_t u ); §\C{// [l,u]}§
     8907uint32_t calls( PRNG32 & prng );                §\C{// number of calls}§
     8908void copy( PRNG32 & dst, PRNG32 & src ); §\C{// checkpoint PRNG state}§
     8909\end{cfa}
     8910\begin{cfa}
     8911struct PRNG64 {};                                               §\C{// opaque type, no copy or assignment}§
     8912void ?{}( PRNG64 & prng, uint64_t seed ); §\C{// fixed seed}§
     8913void ?{}( PRNG64 & prng );                              §\C{// random seed}§
     8914void set_seed( PRNG64 & prng, uint64_t seed ); §\C{// set seed}§
     8915uint64_t get_seed( PRNG64 & prng );             §\C{// get seed}§
     8916uint64_t prng( PRNG64 & prng );                 §\C{// [0,UINT\_MAX]}§
     8917uint64_t prng( PRNG64 & prng, uint64_t u ); §\C{// [0,u)}§
     8918uint64_t prng( PRNG64 & prng, uint64_t l, uint64_t u ); §\C{// [l,u]}§
     8919uint64_t calls( PRNG64 & prng );                §\C{// number of calls}§
     8920void copy( PRNG64 & dst, PRNG64 & src ); §\C{// checkpoint PRNG state}§
     8921\end{cfa}
     8922The type ©PRNG© is aliased to ©PRNG64© on 64-bit architectures and ©PRNG32© on 32-bit architectures.
    87728923A ©PRNG© object is used to randomize behaviour or values during execution, \eg in games, a character makes a random move or an object takes on a random value.
    87738924In this scenario, it is useful to have multiple ©PRNG© objects, \eg one per player or object.
    8774 However, sequential execution is still repeatable given the same starting seeds for all ©PRNG©s. 
     8925However, sequential execution is still repeatable given the same starting seeds for all ©PRNG©s.
    87758926\VRef[Figure]{f:SequentialPRNG} shows an example that creates two sequential ©PRNG©s, sets both to the same seed (1009), and illustrates the three forms for generating random values, where both ©PRNG©s generate the same sequence of values.
     8927Note, to prevent accidental PRNG copying, the copy constructor and assignment are hidden.
     8928To copy a PRNG for checkpointing, use the explicit ©copy© member.
    87768929
    87778930\begin{figure}
    87788931\begin{cfa}
    8779 PRNG prng1, prng2;
    8780 ®set_seed( prng1, 1009 )®;   ®set_seed( prng2, 1009 )®;
     8932PRNG sprng1, sprng2;                                    §\C{// select appropriate 32/64-bit PRNG}§
     8933®set_seed( sprng1, 1009 )®;   ®set_seed( sprng2, 1009 )®;
    87818934for ( 10 ) {
    87828935        // Do not cascade prng calls because side-effect functions called in arbitrary order.
    8783         sout | nlOff | ®prng( prng1 )®;  sout | ®prng( prng1, 5 )®;  sout | ®prng( prng1, 0, 5 )® | '\t';
    8784         sout | ®prng( prng2 )®;  sout | ®prng( prng2, 5 )®;  sout | ®prng( prng2, 0, 5 )® | nlOn;
     8936        sout | nlOff | ®prng( sprng1 )®;  sout | ®prng( sprng1, 5 )®;  sout | ®prng( sprng1, 0, 5 )® | '\t';
     8937        sout | ®prng( sprng2 )®;  sout | ®prng( sprng2, 5 )®;  sout | ®prng( sprng2, 0, 5 )® | nlOn;
    87858938}
    87868939\end{cfa}
    … …  
    88218974The PRNG global and companion thread functions are for concurrent programming, such as randomizing execution in short-running programs, \eg ©yield( prng() % 5 )©.
    88228975\begin{cfa}
    8823 void set_seed( uint32_t seed ); $\C[3.75in]{// set global seed}$
    8824 uint32_t get_seed(); §\C{// get global seed}§
    8825 // SLOWER
    8826 uint32_t prng(); §\C{// [0,UINT\_MAX]}§
    8827 uint32_t prng( uint32_t u ); §\C{// [0,u)}§
    8828 uint32_t prng( uint32_t l, uint32_t u ); §\C{// [l,u]}§
    8829 // FASTER
    8830 uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th );     §\C{// [0,UINT\_MAX]}§
    8831 uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th, uint32_t u ); §\C{// [0,u)}§
    8832 uint32_t prng( $thread\LstStringStyle{\textdollar}$ & th, uint32_t l, uint32_t u );     §\C{// [l,u]}\CRT§
     8976void set_seed( size_t seed );                   §\C{// set global seed}§
     8977size_t get_seed();                                              §\C{// get global seed}§
     8978// SLOWER, global routines
     8979size_t prng( void );                                    §\C{// [0,UINT\_MAX]}§
     8980size_t prng( size_t u );                                §\C{// [0,u)}§
     8981size_t prng( size_t l, size_t u );              §\C{// [l,u]}§
     8982// FASTER, thread members
     8983size_t prng( §thread\LstStringStyle{\textdollar}§ & th );       §\C{// [0,UINT\_MAX]}§
     8984size_t prng( §thread\LstStringStyle{\textdollar}§ & th, size_t u );     §\C{// [0,u)}§
     8985size_t prng( §thread\LstStringStyle{\textdollar}§ & th, size_t l, size_t u );   §\C{// [l,u]}§
    88338986\end{cfa}
    88348987The only difference between the two sets of ©prng© routines is performance.
    … …  
    88418994Hence, these threads generate different sequences of random numbers.
    88428995If each thread needs its own seed, use a sequential ©PRNG© in each thread.
    8843 The slower ©prng© functions \emph{without} a thread argument call ©active_thread© internally to indirectly access the current thread's PRNG state, while the faster ©prng© functions \emph{with} a thread argument directly access the thread through the thread parameter.
     8996The slower ©prng© global functions, \ie \emph{without} a thread argument, call ©active_thread© internally to indirectly access the current thread's PRNG state, while the faster ©prng© functions, \ie \emph{with} a thread argument, directly access the thread through the thread parameter.
    88448997If a thread pointer is available, \eg in thread main, eliminating the call to ©active_thread© significantly reduces the cost of accessing the thread's PRNG state.
    88458998\VRef[Figure]{f:ConcurrentPRNG} shows an example using the slower/faster concurrent PRNG in the program main and a thread.
    … …  
    88569009int main() {
    88579010        set_seed( 1009 );
    8858         $\R{thread\LstStringStyle{\textdollar}}$ ®& th = *active_thread()®;  // program-main thread-address
     9011        §\R{thread\LstStringStyle{\textdollar}}§ ®& th = *active_thread()®;  // program-main thread-address
    88599012        for ( i; 10 ) {
    88609013                sout | nlOff | ®prng()®; sout | ®prng( 5 )®; sout | ®prng( 0, 5 )® | '\t';  // SLOWER
    … …  
    90799232\hline
    90809233\begin{cfa}
    9081 #include <gmp.h>$\indexc{gmp.h}$
     9234#include <gmp.h>§\indexc{gmp.h}§
    90829235int main( void ) {
    90839236        ®gmp_printf®( "Factorial Numbers\n" );
    … …  
    90939246&
    90949247\begin{cfa}
    9095 #include <gmp.hfa>$\indexc{gmp}$
     9248#include <gmp.hfa>§\indexc{gmp}§
    90969249int main( void ) {
    90979250        sout | "Factorial Numbers";
    … …  
    91659318\begin{cfa}[belowskip=0pt]
    91669319// implementation
    9167 struct Rational {$\indexc{Rational}$
     9320struct Rational {§\indexc{Rational}§
    91689321        long int numerator, denominator; §\C{// invariant: denominator > 0}§
    91699322}; // Rational
Note: See TracChangeset for help on using the changeset viewer.