Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/user/user.tex

    rca0e0a9 r63aea5a  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Thu Sep 24 16:34:52 2020
    14 %% Update Count     : 3997
     13%% Last Modified On : Fri Mar  6 13:34:52 2020
     14%% Update Count     : 3924
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
    … …  
    3030\usepackage{upquote}                                                                    % switch curled `'" to straight
    3131\usepackage{calc}
     32\usepackage{xspace}
    3233\usepackage{varioref}                                                                   % extended references
    33 \usepackage[labelformat=simple,aboveskip=0pt,farskip=0pt]{subfig}
    34 \renewcommand{\thesubfigure}{\alph{subfigure})}
     34\usepackage{listings}                                                                   % format program code
    3535\usepackage[flushmargin]{footmisc}                                              % support label/reference in footnote
    3636\usepackage{latexsym}                                   % \Box glyph
    3737\usepackage{mathptmx}                                   % better math font with "times"
    3838\usepackage[usenames]{color}
    39 \newcommand{\CFALatin}{}
     39\input{common}                                          % common CFA document macros
     40\usepackage[dvips,plainpages=false,pdfpagelabels,pdfpagemode=UseNone,colorlinks=true,pagebackref=true,linkcolor=blue,citecolor=blue,urlcolor=blue,pagebackref=true,breaklinks=true]{hyperref}
     41\usepackage{breakurl}
     42
     43\usepackage[pagewise]{lineno}
     44\renewcommand{\linenumberfont}{\scriptsize\sffamily}
     45\usepackage[firstpage]{draftwatermark}
     46\SetWatermarkLightness{0.9}
     47
     48% Default underscore is too low and wide. Cannot use lstlisting "literate" as replacing underscore
     49% removes it as a variable-name character so keywords in variables are highlighted. MUST APPEAR
     50% AFTER HYPERREF.
     51\renewcommand{\textunderscore}{\leavevmode\makebox[1.2ex][c]{\rule{1ex}{0.075ex}}}
     52
     53\setlength{\topmargin}{-0.45in}                                                 % move running title into header
     54\setlength{\headsep}{0.25in}
     55
     56%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     57
     58\CFAStyle                                                                                               % use default CFA format-style
     59\lstnewenvironment{C++}[1][]                            % use C++ style
     60{\lstset{language=C++,moredelim=**[is][\protect\color{red}]{®}{®},#1}}
     61{}
     62
    4063% inline code ©...© (copyright symbol) emacs: C-q M-)
    4164% red highlighting ®...® (registered trademark symbol) emacs: C-q M-.
    … …  
    4568% keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
    4669% math escape $...$ (dollar symbol)
    47 \input{common}                                          % common CFA document macros
    48 \usepackage[dvips,plainpages=false,pdfpagelabels,pdfpagemode=UseNone,colorlinks=true,pagebackref=true,linkcolor=blue,citecolor=blue,urlcolor=blue,pagebackref=true,breaklinks=true]{hyperref}
    49 \usepackage{breakurl}
    50 
    51 \renewcommand\footnoterule{\kern -3pt\rule{0.3\linewidth}{0.15pt}\kern 2pt}
    52 
    53 \usepackage[pagewise]{lineno}
    54 \renewcommand{\linenumberfont}{\scriptsize\sffamily}
    55 \usepackage[firstpage]{draftwatermark}
    56 \SetWatermarkLightness{0.9}
    57 
    58 % Default underscore is too low and wide. Cannot use lstlisting "literate" as replacing underscore
    59 % removes it as a variable-name character so keywords in variables are highlighted. MUST APPEAR
    60 % AFTER HYPERREF.
    61 \renewcommand{\textunderscore}{\leavevmode\makebox[1.2ex][c]{\rule{1ex}{0.075ex}}}
    62 
    63 \setlength{\topmargin}{-0.45in}                                                 % move running title into header
    64 \setlength{\headsep}{0.25in}
    65 
    66 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    67 
    68 \CFADefaults                                                                                    % use default CFA format-style
    69 \lstnewenvironment{C++}[1][]                            % use C++ style
    70 {\lstset{language=C++,moredelim=**[is][\protect\color{red}]{®}{®},#1}}
    71 {}
    72 
    73 \newsavebox{\myboxA}
    74 \newsavebox{\myboxB}
    7570
    7671%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    8479\newcommand{\G}[1]{{\Textbf[OliveGreen]{#1}}}
    8580\newcommand{\KWC}{K-W C\xspace}
     81
     82\newsavebox{\LstBox}
    8683
    8784%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    256253
    257254The signature feature of \CFA is \emph{\Index{overload}able} \Index{parametric-polymorphic} functions~\cite{forceone:impl,Cormack90,Duggan96} with functions generalized using a ©forall© clause (giving the language its name):
    258 \begin{cfa}
     255\begin{lstlisting}
    259256®forall( otype T )® T identity( T val ) { return val; }
    260257int forty_two = identity( 42 ); §\C{// T is bound to int, forty\_two == 42}§
    261 \end{cfa}
     258\end{lstlisting}
    262259% extending the C type system with parametric polymorphism and overloading, as opposed to the \Index*[C++]{\CC{}} approach of object-oriented extensions.
    263260\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}.
    … …  
    278275\begin{comment}
    279276A simple example is leveraging the existing type-unsafe (©void *©) C ©bsearch© to binary search a sorted floating array:
    280 \begin{cfa}
     277\begin{lstlisting}
    281278void * bsearch( const void * key, const void * base, size_t dim, size_t size,
    282279                                int (* compar)( const void *, const void * ));
    … …  
    287284double key = 5.0, vals[10] = { /* 10 sorted floating values */ };
    288285double * val = (double *)bsearch( &key, vals, 10, sizeof(vals[0]), comp ); §\C{// search sorted array}§
    289 \end{cfa}
     286\end{lstlisting}
    290287which can be augmented simply with a polymorphic, type-safe, \CFA-overloaded wrappers:
    291 \begin{cfa}
     288\begin{lstlisting}
    292289forall( otype T | { int ?<?( T, T ); } ) T * bsearch( T key, const T * arr, size_t size ) {
    293290        int comp( const void * t1, const void * t2 ) { /* as above with double changed to T */ }
    … …  
    300297double * val = bsearch( 5.0, vals, 10 ); §\C{// selection based on return type}§
    301298int posn = bsearch( 5.0, vals, 10 );
    302 \end{cfa}
     299\end{lstlisting}
    303300The nested function ©comp© provides the hidden interface from typed \CFA to untyped (©void *©) C, plus the cast of the result.
    304301Providing a hidden ©comp© function in \CC is awkward as lambdas do not use C calling-conventions and template declarations cannot appear at block scope.
    … …  
    308305\CFA has replacement libraries condensing hundreds of existing C functions into tens of \CFA overloaded functions, all without rewriting the actual computations.
    309306For example, it is possible to write a type-safe \CFA wrapper ©malloc© based on the C ©malloc©:
    310 \begin{cfa}
     307\begin{lstlisting}
    311308forall( dtype T | sized(T) ) T * malloc( void ) { return (T *)malloc( sizeof(T) ); }
    312309int * ip = malloc(); §\C{// select type and size from left-hand side}§
    313310double * dp = malloc();
    314311struct S {...} * sp = malloc();
    315 \end{cfa}
     312\end{lstlisting}
    316313where the return type supplies the type/size of the allocation, which is impossible in most type systems.
    317314\end{comment}
    … …  
    946943the same level as a ©case© clause; the target label may be case ©default©, but only associated
    947944with the current ©switch©/©choose© statement.
     945
     946
     947\subsection{Loop Control}
     948
     949The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges (see Figure~\ref{f:LoopControlExamples}).
     950\begin{itemize}
     951\item
     952The loop index is polymorphic in the type of the comparison value N (when the start value is implicit) or the start value M.
     953\item
     954An empty conditional implies comparison value of ©1© (true).
     955\item
     956A comparison N is implicit up-to exclusive range [0,N©®)®©.
     957\item
     958A comparison ©=© N is implicit up-to inclusive range [0,N©®]®©.
     959\item
     960The up-to range M ©~©\index{~@©~©} N means exclusive range [M,N©®)®©.
     961\item
     962The up-to range M ©~=©\index{~=@©~=©} N means inclusive range [M,N©®]®©.
     963\item
     964The down-to range M ©-~©\index{-~@©-~©} N means exclusive range [N,M©®)®©.
     965\item
     966The down-to range M ©-~=©\index{-~=@©-~=©} N means inclusive range [N,M©®]®©.
     967\item
     968©0© is the implicit start value;
     969\item
     970©1© is the implicit increment value.
     971\item
     972The up-to range uses operator ©+=© for increment;
     973\item
     974The down-to range uses operator ©-=© for decrement.
     975\item
     976©@© means put nothing in this field.
     977\item
     978©:© means start another index.
     979\end{itemize}
    948980
    949981\begin{figure}
    … …  
    10541086
    10551087
    1056 \subsection{Loop Control}
    1057 
    1058 The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges (see Figure~\ref{f:LoopControlExamples}).
    1059 \begin{itemize}
    1060 \item
    1061 The loop index is polymorphic in the type of the comparison value N (when the start value is implicit) or the start value M.
    1062 \item
    1063 An empty conditional implies comparison value of ©1© (true).
    1064 \item
    1065 A comparison N is implicit up-to exclusive range [0,N©®)®©.
    1066 \item
    1067 A comparison ©=© N is implicit up-to inclusive range [0,N©®]®©.
    1068 \item
    1069 The up-to range M ©~©\index{~@©~©} N means exclusive range [M,N©®)®©.
    1070 \item
    1071 The up-to range M ©~=©\index{~=@©~=©} N means inclusive range [M,N©®]®©.
    1072 \item
    1073 The down-to range M ©-~©\index{-~@©-~©} N means exclusive range [N,M©®)®©.
    1074 \item
    1075 The down-to range M ©-~=©\index{-~=@©-~=©} N means inclusive range [N,M©®]®©.
    1076 \item
    1077 ©0© is the implicit start value;
    1078 \item
    1079 ©1© is the implicit increment value.
    1080 \item
    1081 The up-to range uses operator ©+=© for increment;
    1082 \item
    1083 The down-to range uses operator ©-=© for decrement.
    1084 \item
    1085 ©@© means put nothing in this field.
    1086 \item
    1087 ©:© means start another index.
    1088 \end{itemize}
    1089 
    1090 
    10911088%\subsection{\texorpdfstring{Labelled \protect\lstinline@continue@ / \protect\lstinline@break@}{Labelled continue / break}}
    10921089\subsection{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break} Statement}{Labelled continue / break Statement}}
    … …  
    10981095for ©break©, the target label can also be associated with a ©switch©, ©if© or compound (©{}©) statement.
    10991096\VRef[Figure]{f:MultiLevelExit} shows ©continue© and ©break© indicating the specific control structure, and the corresponding C program using only ©goto© and labels.
    1100 The innermost loop has 8 exit points, which cause continuation or termination of one or more of the 7 \Index{nested control-structure}s.
     1097The innermost loop has 7 exit points, which cause continuation or termination of one or more of the 7 \Index{nested control-structure}s.
    11011098
    11021099\begin{figure}
    1103 \centering
    1104 \begin{lrbox}{\myboxA}
    1105 \begin{cfa}[tabsize=3]
    1106 ®Compound:® {
    1107         ®Try:® try {
    1108                 ®For:® for ( ... ) {
    1109                         ®While:® while ( ... ) {
    1110                                 ®Do:® do {
    1111                                         ®If:® if ( ... ) {
    1112                                                 ®Switch:® switch ( ... ) {
    1113                                                         case 3:
    1114                                                                 ®break Compound®;
    1115                                                                 ®break Try®;
    1116                                                                 ®break For®;      /* or */  ®continue For®;
    1117                                                                 ®break While®;  /* or */  ®continue While®;
    1118                                                                 ®break Do®;      /* or */  ®continue Do®;
    1119                                                                 ®break If®;
    1120                                                                 ®break Switch®;
    1121                                                         } // switch
    1122                                                 } else {
    1123                                                         ... ®break If®; ...     // terminate if
    1124                                                 } // if
    1125                                 } while ( ... ); // do
    1126                         } // while
    1127                 } // for
    1128         } ®finally® { // always executed
    1129         } // try
     1100\begin{tabular}{@{\hspace{\parindentlnth}}l@{\hspace{\parindentlnth}}l@{\hspace{\parindentlnth}}l@{}}
     1101\multicolumn{1}{@{\hspace{\parindentlnth}}c@{\hspace{\parindentlnth}}}{\textbf{\CFA}}   & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}}      \\
     1102\begin{cfa}
     1103®LC:® {
     1104        ... §declarations§ ...
     1105        ®LS:® switch ( ... ) {
     1106          case 3:
     1107                ®LIF:® if ( ... ) {
     1108                        ®LF:® for ( ... ) {
     1109                                ®LW:® while ( ... ) {
     1110                                        ... break ®LC®; ...
     1111                                        ... break ®LS®; ...
     1112                                        ... break ®LIF®; ...
     1113                                        ... continue ®LF;® ...
     1114                                        ... break ®LF®; ...
     1115                                        ... continue ®LW®; ...
     1116                                        ... break ®LW®; ...
     1117                                } // while
     1118                        } // for
     1119                } else {
     1120                        ... break ®LIF®; ...
     1121                } // if
     1122        } // switch
    11301123} // compound
    11311124\end{cfa}
    1132 \end{lrbox}
    1133 
    1134 \begin{lrbox}{\myboxB}
    1135 \begin{cfa}[tabsize=3]
     1125&
     1126\begin{cfa}
    11361127{
    1137 
    1138                 ®ForC:® for ( ... ) {
    1139                         ®WhileC:® while ( ... ) {
    1140                                 ®DoC:® do {
    1141                                         if ( ... ) {
    1142                                                 switch ( ... ) {
    1143                                                         case 3:
    1144                                                                 ®goto Compound®;
    1145                                                                 ®goto Try®;
    1146                                                                 ®goto ForB®;      /* or */  ®goto ForC®;
    1147                                                                 ®goto WhileB®;  /* or */  ®goto WhileC®;
    1148                                                                 ®goto DoB®;      /* or */  ®goto DoC®;
    1149                                                                 ®goto If®;
    1150                                                                 ®goto Switch®;
    1151                                                         } ®Switch:® ;
    1152                                                 } else {
    1153                                                         ... ®goto If®; ...      // terminate if
    1154                                                 } ®If:®;
    1155                                 } while ( ... ); ®DoB:® ;
    1156                         } ®WhileB:® ;
    1157                 } ®ForB:® ;
    1158 
    1159 
    1160 } ®Compound:® ;
    1161 \end{cfa}
    1162 \end{lrbox}
    1163 
    1164 \subfloat[\CFA]{\label{f:CFibonacci}\usebox\myboxA}
    1165 \hspace{2pt}
    1166 \vrule
    1167 \hspace{2pt}
    1168 \subfloat[C]{\label{f:CFAFibonacciGen}\usebox\myboxB}
     1128        ... §declarations§ ...
     1129        switch ( ... ) {
     1130          case 3:
     1131                if ( ... ) {
     1132                        for ( ... ) {
     1133                                while ( ... ) {
     1134                                        ... goto ®LC®; ...
     1135                                        ... goto ®LS®; ...
     1136                                        ... goto ®LIF®; ...
     1137                                        ... goto ®LFC®; ...
     1138                                        ... goto ®LFB®; ...
     1139                                        ... goto ®LWC®; ...
     1140                                        ... goto ®LWB®; ...
     1141                                  ®LWC®: ; } ®LWB:® ;
     1142                          ®LFC:® ; } ®LFB:® ;
     1143                } else {
     1144                        ... goto ®LIF®; ...
     1145                } ®L3:® ;
     1146        } ®LS:® ;
     1147} ®LC:® ;
     1148\end{cfa}
     1149&
     1150\begin{cfa}
     1151
     1152
     1153
     1154
     1155
     1156
     1157
     1158// terminate compound
     1159// terminate switch
     1160// terminate if
     1161// continue loop
     1162// terminate loop
     1163// continue loop
     1164// terminate loop
     1165
     1166
     1167
     1168// terminate if
     1169
     1170
     1171
     1172\end{cfa}
     1173\end{tabular}
    11691174\caption{Multi-level Exit}
    11701175\label{f:MultiLevelExit}
    … …  
    14211426try {
    14221427        f(...);
    1423 } catch( E e ; §boolean-predicate§ ) {          §\C{// termination handler}§
     1428} catch( E e ; §boolean-predicate§ ) {          §\C[8cm]{// termination handler}§
    14241429        // recover and continue
    1425 } catchResume( E e ; §boolean-predicate§ ) { §\C{// resumption handler}§
     1430} catchResume( E e ; §boolean-predicate§ ) { §\C{// resumption handler}\CRT§
    14261431        // repair and return
    14271432} finally {
    … …  
    34863491For 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.
    34873492\begin{cquote}
    3488 \begin{lrbox}{\myboxA}
     3493\begin{lrbox}{\LstBox}
    34893494\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    34903495int x;   double y   char z;
    … …  
    34923497\end{lrbox}
    34933498\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{3em}}l@{}}
    3494 \multicolumn{1}{@{}l@{}}{\usebox\myboxA} \\
     3499\multicolumn{1}{@{}l@{}}{\usebox\LstBox} \\
    34953500\multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CFA}}        & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{\CC}}       & \multicolumn{1}{c}{\textbf{Python}}   \\
    34963501\begin{cfa}[aboveskip=0pt,belowskip=0pt]
    … …  
    66676672For example, an initial alignment and fill capability are preserved during a resize copy so the copy has the same alignment and extended storage is filled.
    66686673Without sticky properties it is dangerous to use ©realloc©, resulting in an idiom of manually performing the reallocation to maintain correctness.
    6669 \begin{cfa}
    6670 
    6671 \end{cfa}
    66726674
    66736675\CFA memory management extends allocation to support constructors for initialization of allocated storage, \eg in
    … …  
    67196721
    67206722        // §\CFA§ safe general allocation, fill, resize, alignment, array
    6721         T * alloc( void );§\indexc{alloc}§                                      §\C[3.5in]{// variable, T size}§
    6722         T * alloc( size_t dim );                                                        §\C{// array[dim], T size elements}§
    6723         T * alloc( T ptr[], size_t dim );                                       §\C{// realloc array[dim], T size elements}§
    6724 
    6725         T * alloc_set( char fill );§\indexc{alloc_set}§         §\C{// variable, T size, fill bytes with value}§
    6726         T * alloc_set( T fill );                                                        §\C{// variable, T size, fill with value}§
    6727         T * alloc_set( size_t dim, char fill );                         §\C{// array[dim], T size elements, fill bytes with value}§
    6728         T * alloc_set( size_t dim, T fill );                            §\C{// array[dim], T size elements, fill elements with value}§
    6729         T * alloc_set( size_t dim, const T fill[] );            §\C{// array[dim], T size elements, fill elements with array}§
    6730         T * alloc_set( T ptr[], size_t dim, char fill );        §\C{// realloc array[dim], T size elements, fill bytes with value}§
    6731 
    6732         T * alloc_align( size_t align );                                        §\C{// aligned variable, T size}§
    6733         T * alloc_align( size_t align, size_t dim );            §\C{// aligned array[dim], T size elements}§
    6734         T * alloc_align( T ptr[], size_t align );                       §\C{// realloc new aligned array}§
    6735         T * alloc_align( T ptr[], size_t align, size_t dim ); §\C{// realloc new aligned array[dim]}§
    6736 
    6737         T * alloc_align_set( size_t align, char fill );         §\C{// aligned variable, T size, fill bytes with value}§
    6738         T * alloc_align_set( size_t align, T fill );            §\C{// aligned variable, T size, fill with value}§
    6739         T * alloc_align_set( size_t align, size_t dim, char fill ); §\C{// aligned array[dim], T size elements, fill bytes with value}§
    6740         T * alloc_align_set( size_t align, size_t dim, T fill ); §\C{// aligned array[dim], T size elements, fill elements with value}§
    6741         T * alloc_align_set( size_t align, size_t dim, const T fill[] ); §\C{// aligned array[dim], T size elements, fill elements with array}§
    6742         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}§
     6723        T * alloc( void );§\indexc{alloc}§
     6724        T * alloc( size_t dim );
     6725        T * alloc( T ptr[], size_t dim );
     6726        T * alloc_set( char fill );§\indexc{alloc_set}§
     6727        T * alloc_set( T fill );
     6728        T * alloc_set( size_t dim, char fill );
     6729        T * alloc_set( size_t dim, T fill );
     6730        T * alloc_set( size_t dim, const T fill[] );
     6731        T * alloc_set( T ptr[], size_t dim, char fill );
     6732
     6733        T * alloc_align( size_t align );
     6734        T * alloc_align( size_t align, size_t dim );
     6735        T * alloc_align( T ptr[], size_t align ); // aligned realloc array
     6736        T * alloc_align( T ptr[], size_t align, size_t dim ); // aligned realloc array
     6737        T * alloc_align_set( size_t align, char fill );
     6738        T * alloc_align_set( size_t align, T fill );
     6739        T * alloc_align_set( size_t align, size_t dim, char fill );
     6740        T * alloc_align_set( size_t align, size_t dim, T fill );
     6741        T * alloc_align_set( size_t align, size_t dim, const T fill[] );
     6742        T * alloc_align_set( T ptr[], size_t align, size_t dim, char fill );
    67436743
    67446744        // §\CFA§ safe initialization/copy, i.e., implicit size specification
Note: See TracChangeset for help on using the changeset viewer.