Changeset 2a301ff for doc/user/user.tex


Ignore:
Timestamp:
Aug 31, 2023, 11:31:15 PM (2 years ago)
Author:
JiadaL <j82liang@…>
Branches:
master
Children:
950c58e
Parents:
92355883 (diff), 686912c (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:

Resolve conflict

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/user/user.tex

    r92355883 r2a301ff  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Mon Jun  5 21:18:29 2023
    14 %% Update Count     : 5521
     13%% Last Modified On : Thu Aug 10 21:24:07 2023
     14%% Update Count     : 5570
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
    … …  
    37213721\end{cquote}
    37223722The \CFA form has half the characters of the \CC form, and is similar to \Index*{Python} I/O with respect to implicit separators and newline.
    3723 Similar simplification occurs for \Index{tuple} I/O, which flattens the tuple and prints each value separated by ``\lstinline[showspaces=true]{, }''.
     3723Similar simplification occurs for \Index{tuple} I/O, which flattens the tuple and prints each value separated by ``\lstinline[showspaces=true]{, }'' (comma space).
    37243724\begin{cfa}
    37253725[int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
    … …  
    37513751\end{tabular}
    37523752\end{cquote}
    3753 Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators.
    37543753There 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.
     3754Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators, which prevents this common error in \CC:
     3755\begin{C++}
     3756cin << i; // why is this generating a lot of error messages?
     3757\end{C++}
    37553758
    37563759For 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.
    … …  
    38553858\Indexc{close} flushes the stream and closes the file.
    38563859\item
    3857 \Indexc{write} (©ofstream© only) write ©size© bytes to the stream.
    3858 The bytes are written lazily to file when internal buffers fill.
     3860\Indexc{write} (©ofstream© only) writes ©size© bytes to the stream.
     3861The bytes are written lazily when an internal buffer fills.
    38593862Eager buffer writes are done with ©flush©
    38603863\item
    3861 \Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
     3864\Indexc{read} (©ifstream© only) reads ©size© bytes from the stream.
    38623865\item
    38633866\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
    … …  
    39683971
    39693972\item
    3970 If a space is desired before or after one of the special string start/end characters, simply insert a space.
     3973If a space is desired before or after one of the special string start/end characters, explicitly insert a space.
    39713974\begin{cfa}
    39723975sout | "x ($\R{\texttt{\textvisiblespace}}$" | 1 | "$\R{\texttt{\textvisiblespace}}$) x" | 2 | "$\R{\texttt{\textvisiblespace}}$, x" | 3 | "$\R{\texttt{\textvisiblespace}}$:x:$\R{\texttt{\textvisiblespace}}$" | 4;
    … …  
    39813984
    39823985The following \Index{manipulator}s control \Index{implicit output separation}.
    3983 The effect of these manipulators is global for an output stream (except ©sepOn© and ©sepOff©).
     3986The effect of these manipulators is global for an output stream (except ©sep© and ©nosep©).
    39843987\begin{enumerate}
    39853988\item
    3986 \Indexc{sepSet}\index{manipulator!sepSet@©sepSet©} and \Indexc{sep}\index{manipulator!sep@©sep©}/\Indexc{sepGet}\index{manipulator!sepGet@©sepGet©} set and get the separator string.
     3989\Indexc{sepSet}\index{manipulator!sepSet@©sepSet©} and \Indexc{sepVal}\index{manipulator!sepVal@©sepVal©}/\Indexc{sepGet}\index{manipulator!sepGet@©sepGet©} set and get the separator string.
    39873990The separator string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
    39883991\begin{cfa}[belowskip=0pt]
    39893992sepSet( sout, ", $\LstStringStyle{\textdollar}$" ); $\C{// set separator from " " to ", \$"}$
    3990 sout | 1 | 2 | 3 | " \"" | ®sep® | "\"";
     3993sout | 1 | 2 | 3 | " \"" | ®sepVal® | "\"";
    39913994\end{cfa}
    39923995\begin{cfa}[showspaces=true,aboveskip=0pt]
    3993 1®, $\LstStringStyle{\textdollar}$®2®, $\LstStringStyle{\textdollar}$®3 ®", $\LstStringStyle{\textdollar}$"®
     39961®, $\color{red}\LstStringStyle{\textdollar}$®2®, $\color{red}\LstStringStyle{\textdollar}$®3 ®", $\color{red}\LstStringStyle{\textdollar}$"®
    39943997\end{cfa}
    39953998\begin{cfa}[belowskip=0pt]
    … …  
    40194022
    40204023\item
    4021 \Indexc{sepSetTuple}\index{manipulator!sepSetTuple@©sepSetTuple©} and \Indexc{sepTuple}\index{manipulator!sepTuple@©sepTuple©}/\Indexc{sepGetTuple}\index{manipulator!sepGetTuple@©sepGetTuple©} get and set the tuple separator-string.
     4024\Indexc{sepSetTuple}\index{manipulator!sepSetTuple@©sepSetTuple©} and \Indexc{sepTupleVal}\index{manipulator!sepTupleVal@©sepTupleVal©}/\Indexc{sepGetTuple}\index{manipulator!sepGetTuple@©sepGetTuple©} get and set the tuple separator-string.
    40224025The tuple separator-string can be at most 16 characters including the ©'\0'© string terminator (15 printable characters).
    40234026\begin{cfa}[belowskip=0pt]
    40244027sepSetTuple( sout, " " ); $\C{// set tuple separator from ", " to " "}$
    4025 sout | t1 | t2 | " \"" | ®sepTuple® | "\"";
     4028sout | t1 | t2 | " \"" | ®sepTupleVal® | "\"";
    40264029\end{cfa}
    40274030\begin{cfa}[showspaces=true,aboveskip=0pt]
    … …  
    40384041
    40394042\item
    4040 \Indexc{sepDisable}\index{manipulator!sepDisable@©sepDisable©} and \Indexc{sepEnable}\index{manipulator!sepEnable@©sepEnable©} globally toggle printing the separator.
     4043\Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} and \Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} globally toggle printing the separator.
    40414044\begin{cfa}[belowskip=0pt]
    4042 sout | sepDisable | 1 | 2 | 3; $\C{// turn off implicit separator}$
     4045sout | ®sepOff® | 1 | 2 | 3; $\C{// turn off implicit separator}$
    40434046\end{cfa}
    40444047\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40464049\end{cfa}
    40474050\begin{cfa}[belowskip=0pt]
    4048 sout | sepEnable | 1 | 2 | 3; $\C{// turn on implicit separator}$
     4051sout | ®sepOn® | 1 | 2 | 3; $\C{// turn on implicit separator}$
    40494052\end{cfa}
    40504053\begin{cfa}[mathescape=off,showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40534056
    40544057\item
    4055 \Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} locally toggle printing the separator with respect to the next printed item, and then return to the global separator setting.
     4058\Indexc{sep}\index{manipulator!sep@©sep©} and \Indexc{nosep}\index{manipulator!nosep@©nosep©} locally toggle printing the separator with respect to the next printed item, and then return to the global separator setting.
    40564059\begin{cfa}[belowskip=0pt]
    4057 sout | 1 | sepOff | 2 | 3; $\C{// turn off implicit separator for the next item}$
     4060sout | 1 | ®nosep® | 2 | 3; $\C{// turn off implicit separator for the next item}$
    40584061\end{cfa}
    40594062\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40614064\end{cfa}
    40624065\begin{cfa}[belowskip=0pt]
    4063 sout | sepDisable | 1 | sepOn | 2 | 3; $\C{// turn on implicit separator for the next item}$
     4066sout | sepOff | 1 | ®sep® | 2 | 3; $\C{// turn on implicit separator for the next item}$
    40644067\end{cfa}
    40654068\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40684071The tuple separator also responses to being turned on and off.
    40694072\begin{cfa}[belowskip=0pt]
    4070 sout | t1 | sepOff | t2; $\C{// turn off implicit separator for the next item}$
     4073sout | t1 | ®nosep® | t2; $\C{// turn off implicit separator for the next item}$
    40714074\end{cfa}
    40724075\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    407340761, 2, 34, 5, 6
    40744077\end{cfa}
    4075 ©sepOn© \emph{cannot} be used to start/end a line with a separator because separators do not appear at the start/end of a line;
    4076 use ©sep© to accomplish this functionality.
     4078©sep© \emph{cannot} be used to start/end a line with a separator because separators do not appear at the start/end of a line.
     4079Use ©sep© to accomplish this functionality.
    40774080\begin{cfa}[belowskip=0pt]
    4078 sout | sepOn | 1 | 2 | 3 | sepOn; $\C{// sepOn does nothing at start/end of line}$
     4081sout | ®sep® | 1 | 2 | 3 | ®sep®; $\C{// sep does nothing at start/end of line}$
    40794082\end{cfa}
    40804083\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40824085\end{cfa}
    40834086\begin{cfa}[belowskip=0pt]
    4084 sout | sep | 1 | 2 | 3 | sep ; $\C{// use sep to print separator at start/end of line}$
     4087sout | ®sepVal® | 1 | 2 | 3 | ®sepVal® ; $\C{// use sepVal to print separator at start/end of line}$
    40854088\end{cfa}
    40864089\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    … …  
    40974100\begin{enumerate}[parsep=0pt]
    40984101\item
     4102\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} reads the newline character, when reading single characters.
     4103\item
     4104\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} read the newline character, when reading single characters.
     4105\item
    40994106\Indexc{nl}\index{manipulator!nl@©nl©} scans characters until the next newline character, \ie ignore the remaining characters in the line.
    4100 \item
    4101 \Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} reads the newline character, when reading single characters.
    4102 \item
    4103 \Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} read the newline character, when reading single characters.
     4107If ©nlOn© is enabled, the ©nl© is also consumed.
    41044108\end{enumerate}
    41054109For example, in:
    … …  
    41144118\begin{enumerate}[parsep=0pt]
    41154119\item
     4120\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} implicitly prints a newline at the end of each output expression.
     4121\item
     4122\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} implicitly print a newline at the end of each output expression.
     4123\item
    41164124\Indexc{nl}\index{manipulator!nl@©nl©} inserts a newline.
    41174125\begin{cfa}
    4118 sout | nl; $\C{// only print newline}$
     4126sout | ®nl®; $\C{// only print newline}$
    41194127sout | 2; $\C{// implicit newline}$
    4120 sout | 3 | nl | 4 | nl; $\C{// terminating nl merged with implicit newline}$
    4121 sout | 5 | nl | nl; $\C{// again terminating nl merged with implicit newline}$
     4128sout | 3 | ®nl® | 4 | ®nl®; $\C{// terminating nl merged with implicit newline}$
     4129sout | 5 | ®nl® | ®nl®; $\C{// again terminating nl merged with implicit newline}$
    41224130sout | 6; $\C{// implicit newline}$
    41234131
    … …  
    412941376
    41304138\end{cfa}
    4131 Note, a terminating ©nl© is merged (overrides) with the implicit newline at the end of the ©sout© expression, otherwise it is impossible to print a single newline
    4132 \item
    4133 \Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} implicitly prints a newline at the end of each output expression.
    4134 \item
    4135 \Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} implicitly print a newline at the end of each output expression.
     4139Note, a terminating ©nl© is merged with (overrides) the implicit newline at the end of the ©sout© expression, otherwise it is impossible to print a single newline
    41364140\end{enumerate}
    41374141
    … …  
    41394143\subsection{Output Value Manipulators}
    41404144
    4141 The following \Index{manipulator}s control formatting of output values (printing), and only affect the format of the argument.
     4145The following \Index{manipulator}s control formatting (printing) of the argument output values.
    41424146\begin{enumerate}
    41434147\item
    … …  
    41544158\begin{cfa}[belowskip=0pt]
    41554159sout | oct( 0 ) | oct( 27HH ) | oct( 27H ) | oct( 27 ) | oct( 27L );
    4156 0 033 033 033 033
     4160®0® 033 033 033 033
    41574161sout | oct( -27HH ) | oct( -27H ) | oct( -27 ) | oct( -27L );
    415841620345 0177745 037777777745 01777777777777777777745
    … …  
    41644168\begin{cfa}[belowskip=0pt]
    41654169sout | hex( 0 ) | hex( 27HH ) | hex( 27H ) | hex( 27 ) | hex( 27L );
    4166 0 0x1b 0x1b 0x1b 0x1b
     41700x0 0x1b 0x1b 0x1b 0x1b
    41674171sout | hex( -27HH ) | hex( -27H ) | hex( -27 ) | hex( -27L );
    416841720xe5 0xffe5 0xffffffe5 0xffffffffffffffe5
    41694173
    41704174sout | hex( 0.0 ) | hex( 27.5F ) | hex( 27.5 ) | hex( 27.5L );
    4171 0x0.p+0 0x1.b8p+4 0x1.b8p+4 0xd.cp+1
     41750x0p+0 0x1.b8p+4 0x1.b8p+4 0xd.cp+1
    41724176sout | hex( -27.5F ) | hex( -27.5 ) | hex( -27.5L );
    41734177-0x1.b8p+4 -0x1.b8p+4 -0xd.cp+1
    … …  
    42864290For the C-string type, precision is the maximum number of printed characters, so the string is truncated if it exceeds the maximum.
    42874291\begin{cfa}[belowskip=0pt]
    4288 sout | wd( 6,8, "abcd" ) | wd( 6,8, "abcdefghijk" ) | wd( 6,3, "abcd" );
     4292sout | wd( 6,8, "abcd" ) | wd( 6,8, "abcdefghijk" ) | wd( 6,3, "abcd" ) | ®wd( 10, "" )® | 'X';
    42894293\end{cfa}
    42904294\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
    4291   abcd abcdefgh    abc
    4292 \end{cfa}
     4295  abcd abcdefgh    abc®          ®X
     4296\end{cfa}
     4297Note, printing the null string with minimum width L pads with L spaces.
    42934298
    42944299\item
    … …  
    43734378        sout | t1 | t2 | " \"" | sepGetTuple( sout ) | "\"";
    43744379
    4375         sout | sepDisable | 1 | 2 | 3;          // globally turn off implicit separator
    4376         sout | sepEnable | 1 | 2 | 3;           // globally turn on implicit separator
    4377 
    4378         sout | 1 | sepOff | 2 | 3;                      // locally turn on implicit separator
    4379         sout | sepDisable | 1 | sepOn | 2 | 3; // globally turn off implicit separator
    4380         sout | sepEnable;
    4381         sout | t1 | sepOff | t2;                                // locally turn on/off implicit separator
    4382 
    4383         sout | sepOn | 1 | 2 | 3 | sepOn ;      // sepOn does nothing at start/end of line
     4380        sout | sepOff | 1 | 2 | 3;              // globally turn off implicit separator
     4381        sout | sepOn | 1 | 2 | 3;               // globally turn on implicit separator
     4382
     4383        sout | 1 | nosep | 2 | 3;                       // locally turn on implicit separator
     4384        sout | sepOff | 1 | sep | 2 | 3; // globally turn off implicit separator
     4385        sout | sepOn;
     4386        sout | t1 | nosep | t2;                         // locally turn on/off implicit separator
     4387
     4388        sout | sep | 1 | 2 | 3 | sep ;  // sep does nothing at start/end of line
    43844389        sout | sep | 1 | 2 | 3 | sep ;          // use sep to print separator at start/end of line
    43854390}
    … …  
    44124417Instead, the next sequence of non-whitespace characters are read, and the input sequence is terminated with delimiter ©'\0'©.
    44134418The string variable \emph{must} be large enough to contain the input sequence.
    4414 
    4415 The following \Index{manipulator}s control formatting of input values (reading), and only affect the format of the argument.
    4416 
     4419To 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:
     4420\begin{cfa}
     4421char line[64];
     4422sin | wdi( ®sizeof(line)®, line ); // must specify size
     4423\end{cfa}
     4424
     4425A scanset is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
     4426For 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) ©'§'©.
     4427The following string is matched by this scanset:
     4428\begin{cfa}
     4429!&%$  abAA () ZZZ  ??  xx§§§§
     4430\end{cfa}
     4431To match a minus, put it as the first character, ©"-0-9"©.
     4432Note, other complex forms of regular-expression matching is not supported.
     4433
     4434The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
    44174435\begin{enumerate}
    44184436\item
    … …  
    44574475
    44584476\item
    4459 \Indexc{incl}( scanset, input-string )\index{manipulator!incl@©incl©}
    4460 For C-string types, the scanset matches any number of characters \emph{in} the set.
     4477\Indexc{incl}( scanset, wdi-input-string )\index{manipulator!incl@©incl©}
     4478For C-string types only, the scanset matches any number of characters \emph{in} the set.
    44614479Matching characters are read into the C input-string and null terminated.
    44624480\begin{cfa}[belowskip=0pt]
    … …  
    44694487
    44704488\item
    4471 \Indexc{excl}( scanset, input-string )\index{manipulator!excl@©excl©}
     4489\Indexc{excl}( scanset, wdi-input-string )\index{manipulator!excl@©excl©}
    44724490For C-string types, the scanset matches any number of characters \emph{not in} the set.
    44734491Non-matching characters are read into the C input-string and null terminated.
    … …  
    44794497®xyz®bca
    44804498\end{cfa}
     4499
     4500\item
     4501\Indexc{getline}( char delimit, wdi-input-string )\index{manipulator!getline@©getline©}
     4502Is an @excl@ with scanset ©"delimit"©, which consumes all characters up to the delimit character.
     4503If the delimit character is omitted, it defaults to ©'\n'© (newline).
    44814504\end{enumerate}
    44824505
    … …  
    46924715        sout  | i | j | k | x | y | s;
    46934716}
    4694 
     4717\end{cfa}
     4718\begin{cfa}[showspaces=true]
    469547193 0x5          7 1.234568e+07 987.654n abc
    469647203 0x5          7 1.234568e+07 987.654n abc
Note: See TracChangeset for help on using the changeset viewer.