Index: doc/user/user.tex =================================================================== --- doc/user/user.tex (revision c6dc7f21316a7e361444c525b229e2e99fcf5004) +++ doc/user/user.tex (revision 4f0534f0db8eb4499484c930ee98f7aecd9750c9) @@ -11,6 +11,6 @@ %% Created On : Wed Apr 6 14:53:29 2016 %% Last Modified By : Peter A. Buhr -%% Last Modified On : Sat Jul 13 18:36:18 2019 -%% Update Count : 3876 +%% Last Modified On : Thu Mar 5 12:09:42 2020 +%% Update Count : 3885 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -211,13 +211,14 @@ Even with all its problems, C continues to be popular because it allows writing software at virtually any level in a computer system without restriction. For system programming, where direct access to hardware, storage management, and real-time issues are a requirement, C is usually the only language of choice. -The TIOBE index~\cite{TIOBE} for July 2018 ranks the top five most \emph{popular} programming languages as \Index*{Java} 16\%, C 14\%, \Index*[C++]{\CC{}} 7.5\%, Python 6\%, Visual Basic 4\% = 47.5\%, where the next 50 languages are less than 4\% each, with a long tail. -The top 3 rankings over the past 30 years are: +The TIOBE index~\cite{TIOBE} for February 2020 ranks the top six most \emph{popular} programming languages as \Index*{Java} 17.4\%, C 16.8\%, Python 9.3\%, \Index*[C++]{\CC{}} 6.2\%, \Csharp 5.9\%, Visual Basic 5.9\% = 61.5\%, where the next 50 languages are less than 2\% each, with a long tail. +The top 4 rankings over the past 35 years are: \begin{center} \setlength{\tabcolsep}{10pt} -\begin{tabular}{@{}rccccccc@{}} - & 2018 & 2013 & 2008 & 2003 & 1998 & 1993 & 1988 \\ \hline -Java & 1 & 2 & 1 & 1 & 16 & - & - \\ -\R{C} & \R{2} & \R{1} & \R{2} & \R{2} & \R{1} & \R{1} & \R{1} \\ -\CC & 3 & 4 & 3 & 3 & 2 & 2 & 5 \\ +\begin{tabular}{@{}rcccccccc@{}} + & 2020 & 2015 & 2010 & 2005 & 2000 & 1995 & 1990 & 1985 \\ \hline +Java & 1 & 2 & 1 & 2 & 3 & - & - & - \\ +\R{C} & \R{2} & \R{1} & \R{2} & \R{1} & \R{1} & \R{2} & \R{1} & \R{1} \\ +Python & 3 & 7 & 6 & 6 & 22 & 21 & - & - \\ +\CC & 4 & 4 & 4 & 3 & 2 & 1 & 2 & 12 \\ \end{tabular} \end{center} @@ -512,6 +513,6 @@ Keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism: \begin{cfa} -int ®`®otype®`® = 3; §\C{// make keyword an identifier}§ -double ®`®forall®`® = 3.5; +int ®``®otype = 3; §\C{// make keyword an identifier}§ +double ®``®forall = 3.5; \end{cfa} @@ -524,10 +525,8 @@ // include file uses the CFA keyword "with". #if ! defined( with ) §\C{// nesting ?}§ -#define with ®`®with®`® §\C{// make keyword an identifier}§ +#define with ®``®with §\C{// make keyword an identifier}§ #define __CFA_BFD_H__ #endif - -®#include_next §\C{// must have internal check for multiple expansion}§ -® +§{\color{red}\#\textbf{include\_next} }§ §\C{// must have internal check for multiple expansion}§ #if defined( with ) && defined( __CFA_BFD_H__ ) §\C{// reset only if set}§ #undef with @@ -576,11 +575,11 @@ \section{Exponentiation Operator} -C, \CC, and Java (and many other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow}, to perform the exponentiation operation. -\CFA extends the basic operators with the exponentiation operator ©?\?©\index{?\\?@©?\?©} and ©?\=?©\index{?\\=?@©\=?©}, as in, ©x \ y© and ©x \= y©, which means $x^y$ and $x \leftarrow x^y$. +C, \CC, and Java (and many other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow(x,y)}, to perform the exponentiation operation. +\CFA extends the basic operators with the exponentiation operator ©?®\®?©\index{?\\?@©?®\®?©} and ©?\=?©\index{?\\=?@©®\®=?©}, as in, ©x ®\® y© and ©x ®\®= y©, which means $x^y$ and $x \leftarrow x^y$. The priority of the exponentiation operator is between the cast and multiplicative operators, so that ©w * (int)x \ (int)y * z© is parenthesized as ©((w * (((int)x) \ ((int)y))) * z)©. -As for \Index{division}, there are exponentiation operators for integral and floating types, including the builtin \Index{complex} types. +There are exponentiation operators for integral and floating types, including the builtin \Index{complex} types. Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication\footnote{The multiplication computation is $O(\log y)$.} (or shifting if the exponent is 2). -Overflow from large exponents or negative exponents return zero. +Overflow for a large exponent or negative exponent returns zero. Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the exponent cannot be negative. \begin{cfa} @@ -589,5 +588,5 @@ 1 1 256 -64 125 ®0® 3273344365508751233 ®0® ®0® -0.015625 18.3791736799526 0.264715-1.1922i \end{cfa} -Note, ©5 ®\® 32© and ©5L ®\® 64© overflow, and ©-4 ®\® -3© is a fraction but stored in an integer so all three computations generate an integral zero. +Note, ©5 \ 32© and ©5L \ 64© overflow, and ©-4 \ -3© is a fraction but stored in an integer so all three computations generate an integral zero. Parenthesis are necessary for complex constants or the expression is parsed as ©1.0f+®(®2.0fi \ 3.0f®)®+2.0fi©. The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation version is available. @@ -598,5 +597,5 @@ OT ?®\®?( OT ep, unsigned long int y ); \end{cfa} -The user type ©T© must define multiplication, one, ©1©, and, ©*©. +The user type ©T© must define multiplication, one (©1©), and ©*©. @@ -626,147 +625,56 @@ -\subsection{Loop Control} - -The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges (see Figure~\ref{f:LoopControlExamples}). -\begin{itemize} -\item -An empty conditional implies ©1©. -\item -The up-to range ©~©\index{~@©~©} means exclusive range [M,N). -\item -The up-to range ©~=©\index{~=@©~=©} means inclusive range [M,N]. -\item -The down-to range ©-~©\index{-~@©-~©} means exclusive range [N,M). -\item -The down-to range ©-~=©\index{-~=@©-~=©} means inclusive range [N,M]. -\item -©@© means put nothing in this field. -\item -©0© is the implicit start value; -\item -©1© is the implicit increment value. -\item -The up-to range uses ©+=© for increment; -\item -The down-to range uses ©-=© for decrement. -\item -The loop index is polymorphic in the type of the start value or comparison value when start is implicitly ©0©. -\end{itemize} - -\begin{figure} +%\section{\texorpdfstring{\protect\lstinline@case@ Clause}{case Clause}} +\subsection{\texorpdfstring{\LstKeywordStyle{case} Clause}{case Clause}} + +C restricts the ©case© clause of a ©switch© statement to a single value. +For multiple ©case© clauses associated with the same statement, it is necessary to have multiple ©case© clauses rather than multiple values. +Requiring a ©case© clause for each value does not seem to be in the spirit of brevity normally associated with C. +Therefore, the ©case© clause is extended with a list of values, as in: \begin{cquote} -\begin{tabular}{@{}l|l@{}} -\multicolumn{1}{c|}{loop control} & \multicolumn{1}{c}{output} \\ -\hline -\begin{cfa} -sout | nlOff; -while ®()® { sout | "empty"; break; } sout | nl; -do { sout | "empty"; break; } while ®()®; sout | nl; -for ®()® { sout | "empty"; break; } sout | nl; -for ( ®0® ) { sout | "A"; } sout | "zero" | nl; -for ( ®1® ) { sout | "A"; } sout | nl; -for ( ®10® ) { sout | "A"; } sout | nl; -for ( ®1 ~= 10 ~ 2® ) { sout | "B"; } sout | nl; -for ( ®10 -~= 1 ~ 2® ) { sout | "C"; } sout | nl; -for ( ®0.5 ~ 5.5® ) { sout | "D"; } sout | nl; -for ( ®5.5 -~ 0.5® ) { sout | "E"; } sout | nl; -for ( ®i; 10® ) { sout | i; } sout | nl; -for ( ®i; 1 ~= 10 ~ 2® ) { sout | i; } sout | nl; -for ( ®i; 10 -~= 1 ~ 2® ) { sout | i; } sout | nl; -for ( ®i; 0.5 ~ 5.5® ) { sout | i; } sout | nl; -for ( ®i; 5.5 -~ 0.5® ) { sout | i; } sout | nl; -for ( ®ui; 2u ~= 10u ~ 2u® ) { sout | ui; } sout | nl; -for ( ®ui; 10u -~= 2u ~ 2u® ) { sout | ui; } sout | nl; -enum { N = 10 }; -for ( ®N® ) { sout | "N"; } sout | nl; -for ( ®i; N® ) { sout | i; } sout | nl; -for ( ®i; N -~ 0® ) { sout | i; } sout | nl; -const int start = 3, comp = 10, inc = 2; -for ( ®i; start ~ comp ~ inc + 1® ) { sout | i; } sout | nl; -for ( ®i; 1 ~ @® ) { if ( i > 10 ) break; - sout | i; } sout | nl; -for ( ®i; 10 -~ @® ) { if ( i < 0 ) break; - sout | i; } sout | nl; -for ( ®i; 2 ~ @ ~ 2® ) { if ( i > 10 ) break; - sout | i; } sout | nl; -for ( ®i; 2.1 ~ @ ~ @® ) { if ( i > 10.5 ) break; - sout | i; i += 1.7; } sout | nl; -for ( ®i; 10 -~ @ ~ 2® ) { if ( i < 0 ) break; - sout | i; } sout | nl; -for ( ®i; 12.1 ~ @ ~ @® ) { if ( i < 2.5 ) break; - sout | i; i -= 1.7; } sout | nl; -for ( ®i; 5 : j; -5 ~ @® ) { sout | i | j; } sout | nl; -for ( ®i; 5 : j; -5 -~ @® ) { sout | i | j; } sout | nl; -for ( ®i; 5 : j; -5 ~ @ ~ 2® ) { sout | i | j; } sout | nl; -for ( ®i; 5 : j; -5 -~ @ ~ 2® ) { sout | i | j; } sout | nl; -for ( ®j; -5 ~ @ : i; 5® ) { sout | i | j; } sout | nl; -for ( ®j; -5 -~ @ : i; 5® ) { sout | i | j; } sout | nl; -for ( ®j; -5 ~ @ ~ 2 : i; 5® ) { sout | i | j; } sout | nl; -for ( ®j; -5 -~ @ ~ 2 : i; 5® ) { sout | i | j; } sout | nl; -for ( ®j; -5 -~ @ ~ 2 : i; 5 : k; 1.5 ~ @® ) { - sout | i | j | k; } sout | nl; -for ( ®j; -5 -~ @ ~ 2 : k; 1.5 ~ @ : i; 5® ) { - sout | i | j | k; } sout | nl; -for ( ®k; 1.5 ~ @ : j; -5 -~ @ ~ 2 : i; 5® ) { - sout | i | j | k; } sout | nl; +\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}} +\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}} & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}} \\ +\begin{cfa} +switch ( i ) { + case ®1, 3, 5®: + ... + case ®2, 4, 6®: + ... +} \end{cfa} & \begin{cfa} - -empty -empty -empty -zero -A -A A A A A A A A A A -B B B B B -C C C C C -D D D D D -E E E E E -0 1 2 3 4 5 6 7 8 9 -1 3 5 7 9 -10 8 6 4 2 -0.5 1.5 2.5 3.5 4.5 -5.5 4.5 3.5 2.5 1.5 -2 4 6 8 10 -10 8 6 4 2 - -N N N N N N N N N N -0 1 2 3 4 5 6 7 8 9 -10 9 8 7 6 5 4 3 2 1 - -3 6 9 - -1 2 3 4 5 6 7 8 9 10 - -10 9 8 7 6 5 4 3 2 1 0 - -2 4 6 8 10 - -2.1 3.8 5.5 7.2 8.9 - -10 8 6 4 2 0 - -12.1 10.4 8.7 7 5.3 3.6 -0 -5 1 -4 2 -3 3 -2 4 -1 -0 -5 1 -6 2 -7 3 -8 4 -9 -0 -5 1 -3 2 -1 3 1 4 3 -0 -5 1 -7 2 -9 3 -11 4 -13 -0 -5 1 -4 2 -3 3 -2 4 -1 -0 -5 1 -6 2 -7 3 -8 4 -9 -0 -5 1 -3 2 -1 3 1 4 3 -0 -5 1 -7 2 -9 3 -11 4 -13 - -0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 - -0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 - -0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 +switch ( i ) { + case 1: case 3 : case 5: + ... + case 2: case 4 : case 6: + ... +} +\end{cfa} +& +\begin{cfa} + +// odd values + +// even values + + \end{cfa} \end{tabular} \end{cquote} -\caption{Loop Control Examples} -\label{f:LoopControlExamples} -\end{figure} +In addition, subranges are allowed to specify case values.\footnote{ +gcc has the same mechanism but awkward syntax, \lstinline@2 ...42@, because a space is required after a number, otherwise the period is a decimal point.} +\begin{cfa} +switch ( i ) { + case ®1~5:® §\C{// 1, 2, 3, 4, 5}§ + ... + case ®10~15:® §\C{// 10, 11, 12, 13, 14, 15}§ + ... +} +\end{cfa} +Lists of subranges are also allowed. +\begin{cfa} +case ®1~5, 12~21, 35~42®: +\end{cfa} @@ -977,57 +885,195 @@ -%\section{\texorpdfstring{\protect\lstinline@case@ Clause}{case Clause}} -\subsection{\texorpdfstring{\LstKeywordStyle{case} Statement}{case Statement}} - -C restricts the ©case© clause of a ©switch© statement to a single value. -For multiple ©case© clauses associated with the same statement, it is necessary to have multiple ©case© clauses rather than multiple values. -Requiring a ©case© clause for each value does not seem to be in the spirit of brevity normally associated with C. -Therefore, the ©case© clause is extended with a list of values, as in: -\begin{cquote} -\begin{tabular}{@{}l@{\hspace{3em}}l@{\hspace{2em}}l@{}} -\multicolumn{1}{c@{\hspace{3em}}}{\textbf{\CFA}} & \multicolumn{1}{c@{\hspace{2em}}}{\textbf{C}} \\ -\begin{cfa} -switch ( i ) { - case ®1, 3, 5®: +\subsection{Non-terminating and Labelled \texorpdfstring{\LstKeywordStyle{fallthrough}}{Non-terminating and Labelled fallthrough}} + +The ©fallthrough© clause may be non-terminating within a ©case© clause or have a target label to common code from multiple case clauses. +\begin{center} +\begin{tabular}{@{}lll@{}} +\begin{cfa} +choose ( ... ) { + case 3: + if ( ... ) { + ... ®fallthru;® // goto case 4 + } else { + ... + } + // implicit break + case 4: + + + + +\end{cfa} +& +\begin{cfa} +choose ( ... ) { + case 3: + ... ®fallthrough common;® + case 4: + ... ®fallthrough common;® + + ®common:® // below fallthrough + // at case-clause level + ... // common code for cases 3/4 + // implicit break + case 4: + + +\end{cfa} +& +\begin{cfa} +choose ( ... ) { + case 3: + choose ( ... ) { + case 4: + for ( ... ) { + // multi-level transfer + ... ®fallthru common;® + } + ... + } ... - case ®2, 4, 6®: - ... -} + ®common:® // below fallthrough + // at case-clause level +\end{cfa} +\end{tabular} +\end{center} +The target label must be below the ©fallthrough© and may not be nested in a control structure, and +the target label must be at the same or higher level as the containing ©case© clause and located at +the same level as a ©case© clause; the target label may be case ©default©, but only associated +with the current ©switch©/©choose© statement. + + +\subsection{Loop Control} + +The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges (see Figure~\ref{f:LoopControlExamples}). +\begin{itemize} +\item +The loop index is polymorphic in the type of the comparison value N (when the start value is implicit) or the start value M. +\item +An empty conditional implies comparison value of ©1© (true). +\item +A comparison N is implicit up-to exclusive range [0,N©®)®©. +\item +A comparison ©=© N is implicit up-to inclusive range [0,N©®]®©. +\item +The up-to range M ©~©\index{~@©~©} N means exclusive range [M,N©®)®©. +\item +The up-to range M ©~=©\index{~=@©~=©} N means inclusive range [M,N©®]®©. +\item +The down-to range M ©-~©\index{-~@©-~©} N means exclusive range [N,M©®)®©. +\item +The down-to range M ©-~=©\index{-~=@©-~=©} N means inclusive range [N,M©®]®©. +\item +©0© is the implicit start value; +\item +©1© is the implicit increment value. +\item +The up-to range uses operator ©+=© for increment; +\item +The down-to range uses operator ©-=© for decrement. +\item +©@© means put nothing in this field. +\item +©:© means start another index. +\end{itemize} + +\begin{figure} +\begin{tabular}{@{}l|l@{}} +\multicolumn{1}{c|}{loop control} & \multicolumn{1}{c}{output} \\ +\hline +\begin{cfa}[xleftmargin=0pt] +while ®()® { sout | "empty"; break; } +do { sout | "empty"; break; } while ®()®; +for ®()® { sout | "empty"; break; } +for ( ®0® ) { sout | "A"; } sout | "zero"; +for ( ®1® ) { sout | "A"; } +for ( ®10® ) { sout | "A"; } +for ( ®= 10® ) { sout | "A"; } +for ( ®1 ~= 10 ~ 2® ) { sout | "B"; } +for ( ®10 -~= 1 ~ 2® ) { sout | "C"; } +for ( ®0.5 ~ 5.5® ) { sout | "D"; } +for ( ®5.5 -~ 0.5® ) { sout | "E"; } +for ( ®i; 10® ) { sout | i; } +for ( ®i; = 10® ) { sout | i; } +for ( ®i; 1 ~= 10 ~ 2® ) { sout | i; } +for ( ®i; 10 -~= 1 ~ 2® ) { sout | i; } +for ( ®i; 0.5 ~ 5.5® ) { sout | i; } +for ( ®i; 5.5 -~ 0.5® ) { sout | i; } +for ( ®ui; 2u ~= 10u ~ 2u® ) { sout | ui; } +for ( ®ui; 10u -~= 2u ~ 2u® ) { sout | ui; } +enum { N = 10 }; +for ( ®N® ) { sout | "N"; } +for ( ®i; N® ) { sout | i; } +for ( ®i; N -~ 0® ) { sout | i; } +const int start = 3, comp = 10, inc = 2; +for ( ®i; start ~ comp ~ inc + 1® ) { sout | i; } +for ( i; 1 ~ ®@® ) { if ( i > 10 ) break; sout | i; } +for ( i; 10 -~ ®@® ) { if ( i < 0 ) break; sout | i; } +for ( i; 2 ~ ®@® ~ 2 ) { if ( i > 10 ) break; sout | i; } +for ( i; 2.1 ~ ®@® ~ ®@® ) { if ( i > 10.5 ) break; sout | i; i += 1.7; } +for ( i; 10 -~ ®@® ~ 2 ) { if ( i < 0 ) break; sout | i; } +for ( i; 12.1 ~ ®@® ~ ®@® ) { if ( i < 2.5 ) break; sout | i; i -= 1.7; } +for ( i; 5 ®:® j; -5 ~ @ ) { sout | i | j; } +for ( i; 5 ®:® j; -5 -~ @ ) { sout | i | j; } +for ( i; 5 ®:® j; -5 ~ @ ~ 2 ) { sout | i | j; } +for ( i; 5 ®:® j; -5 -~ @ ~ 2 ) { sout | i | j; } +for ( i; 5 ®:® j; -5 ~ @ ) { sout | i | j; } +for ( i; 5 ®:® j; -5 -~ @ ) { sout | i | j; } +for ( i; 5 ®:® j; -5 ~ @ ~ 2 ) { sout | i | j; } +for ( i; 5 ®:® j; -5 -~ @ ~ 2 ) { sout | i | j; } +for ( i; 5 ®:® j; -5 -~ @ ~ 2 ®:® k; 1.5 ~ @ ) { sout | i | j | k; } +for ( i; 5 ®:® j; -5 -~ @ ~ 2 ®:® k; 1.5 ~ @ ) { sout | i | j | k; } +for ( i; 5 ®:® k; 1.5 ~ @ ®:® j; -5 -~ @ ~ 2 ) { sout | i | j | k; } \end{cfa} & \begin{cfa} -switch ( i ) { - case 1: case 3 : case 5: - ... - case 2: case 4 : case 6: - ... -} -\end{cfa} -& -\begin{cfa} - -// odd values - -// even values - - +empty +empty +empty +zero +A +A A A A A A A A A A +A A A A A A A A A A A +B B B B B +C C C C C +D D D D D +E E E E E +0 1 2 3 4 5 6 7 8 9 +0 1 2 3 4 5 6 7 8 9 10 +1 3 5 7 9 +10 8 6 4 2 +0.5 1.5 2.5 3.5 4.5 +5.5 4.5 3.5 2.5 1.5 +2 4 6 8 10 +10 8 6 4 2 + +N N N N N N N N N N +0 1 2 3 4 5 6 7 8 9 +10 9 8 7 6 5 4 3 2 1 + +3 6 9 +1 2 3 4 5 6 7 8 9 10 +10 9 8 7 6 5 4 3 2 1 0 +2 4 6 8 10 +2.1 3.8 5.5 7.2 8.9 +10 8 6 4 2 0 +12.1 10.4 8.7 7. 5.3 3.6 +0 -5 1 -4 2 -3 3 -2 4 -1 +0 -5 1 -6 2 -7 3 -8 4 -9 +0 -5 1 -3 2 -1 3 1 4 3 +0 -5 1 -7 2 -9 3 -11 4 -13 +0 -5 1 -4 2 -3 3 -2 4 -1 +0 -5 1 -6 2 -7 3 -8 4 -9 +0 -5 1 -3 2 -1 3 1 4 3 +0 -5 1 -7 2 -9 3 -11 4 -13 +0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 +0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 +0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5 \end{cfa} \end{tabular} -\end{cquote} -In addition, subranges are allowed to specify case values.\footnote{ -gcc has the same mechanism but awkward syntax, \lstinline@2 ...42@, because a space is required after a number, otherwise the period is a decimal point.} -\begin{cfa} -switch ( i ) { - case ®1~5:® §\C{// 1, 2, 3, 4, 5}§ - ... - case ®10~15:® §\C{// 10, 11, 12, 13, 14, 15}§ - ... -} -\end{cfa} -Lists of subranges are also allowed. -\begin{cfa} -case ®1~5, 12~21, 35~42®: -\end{cfa} - +\caption{Loop Control Examples} +\label{f:LoopControlExamples} +\end{figure} % for () => for ( ;; ) @@ -6547,5 +6593,5 @@ hence, names in these include files are not mangled\index{mangling!name} (see~\VRef{s:Interoperability}). All other C header files must be explicitly wrapped in ©extern "C"© to prevent name mangling. -For \Index*[C++]{\CC{}}, the name-mangling issue is often handled internally in many C header-files through checks for preprocessor variable ©__cplusplus©, which adds appropriate ©extern "C"© qualifiers. +This approach is different from \Index*[C++]{\CC{}} where the name-mangling issue is handled internally in C header-files through checks for preprocessor variable ©__cplusplus©, which adds appropriate ©extern "C"© qualifiers. @@ -6561,94 +6607,120 @@ The storage-management routines extend their C equivalents by overloading, alternate names, providing shallow type-safety, and removing the need to specify the allocation size for non-array types. -Storage management provides the following capabilities: +C storage management provides the following capabilities: \begin{description} -\item[fill] -after allocation the storage is filled with a specified character. +\item[filled] +after allocation with a specified character or value. \item[resize] -an existing allocation is decreased or increased in size. -In either case, new storage may or may not be allocated and, if there is a new allocation, as much data from the existing allocation is copied. +an existing allocation to decreased or increased its size. +In either case, new storage may or may not be allocated and, if there is a new allocation, as much data from the existing allocation is copied into the new allocation. For an increase in storage size, new storage after the copied data may be filled. -\item[alignment] -an allocation starts on a specified memory boundary, \eg, an address multiple of 64 or 128 for cache-line purposes. +\item[align] +an allocation on a specified memory boundary, \eg, an address multiple of 64 or 128 for cache-line purposes. \item[array] the allocation size is scaled to the specified number of array elements. An array may be filled, resized, or aligned. \end{description} -The table shows allocation routines supporting different combinations of storage-management capabilities: -\begin{center} -\begin{tabular}{@{}r|r|l|l|l|l@{}} +\VRef[Table]{t:AllocationVersusCapabilities} shows allocation routines supporting different combinations of storage-management capabilities: +\begin{table} +\centering +\begin{tabular}{@{}r|l|l|l|l|l@{}} \multicolumn{1}{c}{}& & \multicolumn{1}{c|}{fill} & resize & alignment & array \\ \hline C & ©malloc© & no & no & no & no \\ & ©calloc© & yes (0 only) & no & no & yes \\ - & ©realloc© & no/copy & yes & no & no \\ + & ©realloc© & copy & yes & no & no \\ & ©memalign© & no & no & yes & no \\ + & ©aligned_alloc© & no & no & yes & no \\ & ©posix_memalign© & no & no & yes & no \\ \hline -C11 & ©aligned_alloc© & no & no & yes & no \\ -\hline -\CFA & ©alloc© & no/copy/yes & no/yes & no & yes \\ - & ©align_alloc© & no/yes & no & yes & yes \\ +\CFA & ©cmemalign© & yes (0 only) & no & yes & yes \\ + & ©realloc© & copy & yes & yes & no \\ + & ©alloc© & no & no & no & no \\ + & ©alloc© & copy & no/yes & no & yes \\ + & ©alloc© & no/copy/yes & no/yes & no & yes \\ + & ©alloc_set© & no/yes & no & yes & yes \\ + & ©alloc_align© & no/yes & no & yes & yes \\ + & ©alloc_align_set© & no/yes & no & yes & yes \\ \end{tabular} -\end{center} -It is impossible to resize with alignment because the underlying ©realloc© allocates storage if more space is needed, and it does not honour alignment from the original allocation. +\caption{Allocation Routines versus Storage-Management Capabilities} +\label{t:AllocationVersusCapabilities} +\end{table} + +\CFA memory management extends the resize capability with the notion of \newterm{sticky properties}. +Hence, initial allocation capabilities are remembered and maintained when resize requires copying. +For example, an initial alignment and fill capability are preserved during a resize copy so the copy has the same alignment and extended storage is filled. +Without sticky properties it is dangerous to use ©realloc©, resulting in an idiom of manually performing the reallocation to maintain correctness. + \leavevmode \begin{cfa}[aboveskip=0pt,belowskip=0pt] -// C unsafe allocation extern "C" { -void * malloc( size_t size );§\indexc{memset}§ -void * calloc( size_t dim, size_t size );§\indexc{calloc}§ -void * realloc( void * ptr, size_t size );§\indexc{realloc}§ -void * memalign( size_t align, size_t size );§\indexc{memalign}§ -int posix_memalign( void ** ptr, size_t align, size_t size );§\indexc{posix_memalign}§ - -// C unsafe initialization/copy -void * memset( void * dest, int c, size_t size ); -void * memcpy( void * dest, const void * src, size_t size ); -} + // C unsafe allocation + void * malloc( size_t size );§\indexc{malloc}§ + void * calloc( size_t dim, size_t size );§\indexc{calloc}§ + void * realloc( void * ptr, size_t size );§\indexc{realloc}§ + void * memalign( size_t align, size_t size );§\indexc{memalign}§ + void * aligned_alloc( size_t align, size_t size );§\indexc{aligned_alloc}§ + int posix_memalign( void ** ptr, size_t align, size_t size );§\indexc{posix_memalign}§ + void * cmemalign( size_t alignment, size_t noOfElems, size_t elemSize );§\indexc{cmemalign}§ // CFA + + // C unsafe initialization/copy + void * memset( void * dest, int c, size_t size );§\indexc{memset}§ + void * memcpy( void * dest, const void * src, size_t size );§\indexc{memcpy}§ +} + +void * realloc( void * oaddr, size_t nalign, size_t size ); // CFA heap forall( dtype T | sized(T) ) { -// §\CFA§ safe equivalents, i.e., implicit size specification + // §\CFA§ safe equivalents, i.e., implicit size specification T * malloc( void ); T * calloc( size_t dim ); T * realloc( T * ptr, size_t size ); T * memalign( size_t align ); + T * cmemalign( size_t align, size_t dim ); T * aligned_alloc( size_t align ); int posix_memalign( T ** ptr, size_t align ); -// §\CFA§ safe general allocation, fill, resize, array + // §\CFA§ safe general allocation, fill, resize, alignment, array T * alloc( void );§\indexc{alloc}§ - T * alloc( char fill ); T * alloc( size_t dim ); - T * alloc( size_t dim, char fill ); T * alloc( T ptr[], size_t dim ); - T * alloc( T ptr[], size_t dim, char fill ); - -// §\CFA§ safe general allocation, align, fill, array - T * align_alloc( size_t align ); - T * align_alloc( size_t align, char fill ); - T * align_alloc( size_t align, size_t dim ); - T * align_alloc( size_t align, size_t dim, char fill ); - -// §\CFA§ safe initialization/copy, i.e., implicit size specification - T * memset( T * dest, char c );§\indexc{memset}§ + T * alloc_set( char fill );§\indexc{alloc_set}§ + T * alloc_set( T fill ); + T * alloc_set( size_t dim, char fill ); + T * alloc_set( size_t dim, T fill ); + T * alloc_set( size_t dim, const T fill[] ); + T * alloc_set( T ptr[], size_t dim, char fill ); + + T * alloc_align( size_t align ); + T * alloc_align( size_t align, size_t dim ); + T * alloc_align( T ptr[], size_t align ); // aligned realloc array + T * alloc_align( T ptr[], size_t align, size_t dim ); // aligned realloc array + T * alloc_align_set( size_t align, char fill ); + T * alloc_align_set( size_t align, T fill ); + T * alloc_align_set( size_t align, size_t dim, char fill ); + T * alloc_align_set( size_t align, size_t dim, T fill ); + T * alloc_align_set( size_t align, size_t dim, const T fill[] ); + T * alloc_align_set( T ptr[], size_t align, size_t dim, char fill ); + + // §\CFA§ safe initialization/copy, i.e., implicit size specification + T * memset( T * dest, char fill );§\indexc{memset}§ T * memcpy( T * dest, const T * src );§\indexc{memcpy}§ -// §\CFA§ safe initialization/copy array - T * amemset( T dest[], char c, size_t dim ); + // §\CFA§ safe initialization/copy, i.e., implicit size specification, array types + T * amemset( T dest[], char fill, size_t dim ); T * amemcpy( T dest[], const T src[], size_t dim ); } -// §\CFA§ allocation/deallocation and constructor/destructor -forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * new( Params p );§\indexc{new}§ -forall( dtype T | { void ^?{}( T * ); } ) void delete( T * ptr );§\indexc{delete}§ -forall( dtype T, ttype Params | { void ^?{}( T * ); void delete( Params ); } ) +// §\CFA§ allocation/deallocation and constructor/destructor, non-array types +forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * new( Params p );§\indexc{new}§ +forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void delete( T * ptr );§\indexc{delete}§ +forall( dtype T, ttype Params | sized(T) | { void ^?{}( T & ); void delete( Params ); } ) void delete( T * ptr, Params rest ); -// §\CFA§ allocation/deallocation and constructor/destructor, array -forall( dtype T | sized(T), ttype Params | { void ?{}( T *, Params ); } ) T * anew( size_t dim, Params p );§\indexc{anew}§ -forall( dtype T | sized(T) | { void ^?{}( T * ); } ) void adelete( size_t dim, T arr[] );§\indexc{adelete}§ -forall( dtype T | sized(T) | { void ^?{}( T * ); }, ttype Params | { void adelete( Params ); } ) +// §\CFA§ allocation/deallocation and constructor/destructor, array types +forall( dtype T | sized(T), ttype Params | { void ?{}( T &, Params ); } ) T * anew( size_t dim, Params p );§\indexc{anew}§ +forall( dtype T | sized(T) | { void ^?{}( T & ); } ) void adelete( size_t dim, T arr[] );§\indexc{adelete}§ +forall( dtype T | sized(T) | { void ^?{}( T & ); }, ttype Params | { void adelete( Params ); } ) void adelete( size_t dim, T arr[], Params rest ); \end{cfa}