Changeset 7839f78

Timestamp:

Aug 10, 2023, 10:18:55 PM (16 months ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

master

Children:

13600e8

Parents:

9ff71ff

Message:

update documentation about changes to I/O

File:

• doc/user/user.tex (modified) (16 diffs)

doc/user/user.tex

@@ -11 +11 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Thu Jun 29 21:52:51 2023
-%% Update Count     : 5533
+%% Last Modified On : Thu Aug 10 21:24:07 2023
+%% Update Count     : 5570
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -3721 +3721 @@
 \end{cquote}
 The \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.
-Similar simplification occurs for \Index{tuple} I/O, which flattens the tuple and prints each value separated by ``\lstinline[showspaces=true]{, }''.
+Similar simplification occurs for \Index{tuple} I/O, which flattens the tuple and prints each value separated by ``\lstinline[showspaces=true]{, }'' (comma space).
 \begin{cfa}
 [int, [ int, int ] ] t1 = [ 1, [ 2, 3 ] ], t2 = [ 4, [ 5, 6 ] ];
@@ -3751 +3751 @@
 \end{tabular}
 \end{cquote}
-Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators.
 There 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.
+Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators, which prevents this common error in \CC:
+\begin{C++}
+cin << i; // why is this generating a lot of error messages?
+\end{C++}
 
 For 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.
@@ -3855 +3858 @@
 \Indexc{close} flushes the stream and closes the file.
 \item
-\Indexc{write} (©ofstream© only) write ©size© bytes to the stream.
-The bytes are written lazily to file when internal buffers fill.
+\Indexc{write} (©ofstream© only) writes ©size© bytes to the stream.
+The bytes are written lazily when an internal buffer fills.
 Eager buffer writes are done with ©flush©
 \item
-\Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
+\Indexc{read} (©ifstream© only) reads ©size© bytes from the stream.
 \item
 \Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
@@ -3968 +3971 @@
 
 \item
-If a space is desired before or after one of the special string start/end characters, simply insert a space.
+If a space is desired before or after one of the special string start/end characters, explicitly insert a space.
 \begin{cfa}
 sout | "x ($\R{\texttt{\textvisiblespace}}$" | 1 | "$\R{\texttt{\textvisiblespace}}$) x" | 2 | "$\R{\texttt{\textvisiblespace}}$, x" | 3 | "$\R{\texttt{\textvisiblespace}}$:x:$\R{\texttt{\textvisiblespace}}$" | 4;
@@ -4073 +4076 @@
 1, 2, 34, 5, 6
 \end{cfa}
-©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;
-use ©sep© to accomplish this functionality.
+©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.
+Use ©sep© to accomplish this functionality.
 \begin{cfa}[belowskip=0pt]
 sout | ®sep® | 1 | 2 | 3 | ®sep®; $\C{// sep does nothing at start/end of line}$
@@ -4097 +4100 @@
 \begin{enumerate}[parsep=0pt]
 \item
+\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} reads the newline character, when reading single characters.
+\item
+\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} read the newline character, when reading single characters.
+\item
 \Indexc{nl}\index{manipulator!nl@©nl©} scans characters until the next newline character, \ie ignore the remaining characters in the line.
-\item
-\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} reads the newline character, when reading single characters.
-\item
-\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} read the newline character, when reading single characters.
+If ©nlOn© is enabled, the ©nl© is also consumed.
 \end{enumerate}
 For example, in:
@@ -4113 +4117 @@
 For output:
 \begin{enumerate}[parsep=0pt]
+\item
+\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} implicitly prints a newline at the end of each output expression.
+\item
+\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} implicitly print a newline at the end of each output expression.
 \item
 \Indexc{nl}\index{manipulator!nl@©nl©} inserts a newline.
@@ -4129 +4137 @@
 6
 \end{cfa}
-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
-\item
-\Indexc{nlOn}\index{manipulator!nlOn@©nlOn©} implicitly prints a newline at the end of each output expression.
-\item
-\Indexc{nlOff}\index{manipulator!nlOff@©nlOff©} does \emph{not} implicitly print a newline at the end of each output expression.
+Note, 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
 \end{enumerate}
 
@@ -4139 +4143 @@
 \subsection{Output Value Manipulators}
 
-The following \Index{manipulator}s control formatting of output values (printing), and only affect the format of the argument.
+The following \Index{manipulator}s control formatting (printing) of the argument output values.
 \begin{enumerate}
 \item
@@ -4154 +4158 @@
 \begin{cfa}[belowskip=0pt]
 sout | oct( 0 ) | oct( 27HH ) | oct( 27H ) | oct( 27 ) | oct( 27L );
-0 033 033 033 033
+®0® 033 033 033 033
 sout | oct( -27HH ) | oct( -27H ) | oct( -27 ) | oct( -27L );
 0345 0177745 037777777745 01777777777777777777745
@@ -4164 +4168 @@
 \begin{cfa}[belowskip=0pt]
 sout | hex( 0 ) | hex( 27HH ) | hex( 27H ) | hex( 27 ) | hex( 27L );
-0 0x1b 0x1b 0x1b 0x1b
+0x0 0x1b 0x1b 0x1b 0x1b
 sout | hex( -27HH ) | hex( -27H ) | hex( -27 ) | hex( -27L );
 0xe5 0xffe5 0xffffffe5 0xffffffffffffffe5
 
 sout | hex( 0.0 ) | hex( 27.5F ) | hex( 27.5 ) | hex( 27.5L );
-0x0.p+0 0x1.b8p+4 0x1.b8p+4 0xd.cp+1
+0x0p+0 0x1.b8p+4 0x1.b8p+4 0xd.cp+1
 sout | hex( -27.5F ) | hex( -27.5 ) | hex( -27.5L );
 -0x1.b8p+4 -0x1.b8p+4 -0xd.cp+1
@@ -4413 +4417 @@
 Instead, the next sequence of non-whitespace characters are read, and the input sequence is terminated with delimiter ©'\0'©.
 The string variable \emph{must} be large enough to contain the input sequence.
-
-The following \Index{manipulator}s control formatting of input values (reading), and only affect the format of the argument.
-
+To 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:
+\begin{cfa}
+char line[64];
+sin | wdi( ®sizeof(line)®, line ); // must specify size
+\end{cfa}
+
+A scanset is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
+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) ©'§'©.
+The following string is matched by this scanset:
+\begin{cfa}
+!&%$  abAA () ZZZ  ??  xx§§§§
+\end{cfa}
+To match a minus, put it as the first character, ©"-0-9"©.
+Note, other complex forms of regular-expression matching is not supported.
+
+The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
 \begin{enumerate}
 \item
@@ -4458 +4475 @@
 
 \item
-\Indexc{incl}( scanset, input-string )\index{manipulator!incl@©incl©}
-For C-string types, the scanset matches any number of characters \emph{in} the set.
+\Indexc{incl}( scanset, wdi-input-string )\index{manipulator!incl@©incl©}
+For C-string types only, the scanset matches any number of characters \emph{in} the set.
 Matching characters are read into the C input-string and null terminated.
 \begin{cfa}[belowskip=0pt]
@@ -4470 +4487 @@
 
 \item
-\Indexc{excl}( scanset, input-string )\index{manipulator!excl@©excl©}
+\Indexc{excl}( scanset, wdi-input-string )\index{manipulator!excl@©excl©}
 For C-string types, the scanset matches any number of characters \emph{not in} the set.
 Non-matching characters are read into the C input-string and null terminated.
@@ -4480 +4497 @@
 ®xyz®bca
 \end{cfa}
+
+\item
+\Indexc{getline}( char delimit, wdi-input-string )\index{manipulator!getline@©getline©}
+Is an @excl@ with scanset ©"delimit"©, which consumes all characters up to the delimit character.
+If the delimit character is omitted, it defaults to ©'\n'© (newline).
 \end{enumerate}