Changeset c132d50

Timestamp:

Apr 28, 2021, 10:06:28 PM (3 years ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

ADT, arm-eh, ast-experimental, enum, forall-pointer-decay, jacob/cs343-translation, master, new-ast-unique-expr, pthread-emulation, qualifiedEnum

Children:

3ec79f7

Parents:

091011a

Message:

update stream documentation and add strstream documentation

File:

• doc/user/user.tex (modified) (14 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 : Sun Apr 25 19:03:03 2021
-%% Update Count     : 4951
+%% Last Modified On : Wed Apr 28 21:48:59 2021
+%% Update Count     : 5051
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -3312 +3312 @@
 
 \section{Tuples}
+\label{tuples}
 
 In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
@@ -3420 +3421 @@
 
 \subsection{Tuple Coercions}
+\label{tuple coercions}\label{coercions!tuple}
 
 There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
@@ -3464 +3466 @@
 
 \subsection{Mass Assignment}
+\label{mass assignment}\label{assignment!mass}
 
 \CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
@@ -3504 +3507 @@
 
 \subsection{Multiple Assignment}
+\label{multiple assignment}\label{assignment!multiple}
 
 \CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
@@ -3545 +3549 @@
 
 \subsection{Cascade Assignment}
+\index{cascade assignment}\index{assignment!cascade}
 
 As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
@@ -3564 +3569 @@
 \section{Stream I/O Library}
 \label{s:StreamIOLibrary}
-\index{input/output stream library}
-\index{stream library}
+\index{input}\index{output}
+\index{stream library}\index{library!stream}
 
 The 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.
 Stream I/O can be implicitly or explicitly formatted.
-Implicit formatting means \CFA selects the output or input format for values that match with the type of a variable.
+Implicit formatting means \CFA selects the output or input format for values that matches the variable's type.
 Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
-\CFA formatting is a cross between C ©printf© and \CC ©cout© manipulators, and Python implicit spacing and newline.
+\CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
 Specifically:
 \begin{itemize}
@@ -3584 +3589 @@
 Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
 Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
-(To guarantee no side-effects, manipulator values must be saved and restored across function calls.)
-\item
-\CFA has more sophisticated implicit spacing between values than Python, plus implicit newline at the end of a print.
+Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
+\item
+\CFA has more sophisticated implicit value spacing than Python, plus implicit newline at the end of a print.
 \end{itemize}
+
+The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
+Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file.
+Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
+\begin{cfa}
+®exit®   | "x (" | x | ") negative value."; // terminate and return EXIT_FAILURE to shell
+®abort® | "x (" | x | ") negative value."; // terminate and generate stack trace and core file
+\end{cfa}
+Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
 The \CFA header file for the I/O library is \Indexc{fstream.hfa}.
+
+
+\subsection{Basic I/O}
 
 For implicit formatted output, the common case is printing a series of variables separated by whitespace.
@@ -3601 +3618 @@
 \begin{cfa}
 
-cout << x ®<< " "® << y ®<< " "® << z << endl;
+cout  <<  x  ®<< " "®  <<  y  ®<< " "®  <<  z  << endl;
 \end{cfa}
 &
@@ -3653 +3670 @@
 \end{tabular}
 \end{cquote}
-Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.
+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.
 
@@ -3698 +3715 @@
 \end{cquote}
 
+\VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
+Note, a stream variable may be copied because it is a reference to an underlying stream data-structures.
+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.
+
+\begin{figure}
+\begin{cfa}
+#include ®<fstream.hfa>®
+
+int main( int argc, char * argv[] ) {
+        ®ifstream® in  = stdin;                                 $\C{// copy default files}$
+        ®ofstream® out = stdout;
+
+        try {
+                choose ( argc ) {
+                  case 2, 3:
+                        ®open®( in, argv[1] );                  $\C{// open input file first as output creates file}$
+                        if ( argc == 3 ) ®open®( out, argv[2] ); $\C{// do not create output unless input opens}$
+                  case 1: ;                                                     $\C{// use default files}$
+                  default:
+                        ®exit® | "Usage" | argv[0] | "[ input-file (default stdin) "
+                                   "[ output-file (default stdout) ] ]";
+                } // choose
+        } catch( ®Open_Failure® * ex; ex->istream == &in ) {
+                ®exit® | "Unable to open input file" | argv[1];
+        } catch( ®Open_Failure® * ex; ex->ostream == &out ) {
+                ®close®( in );                                          $\C{// optional}$
+                ®exit® | "Unable to open output file" | argv[2];
+        } // try
+
+        out | nlOff;                                                    $\C{// turn off auto newline}$
+        in | nlOn;                                                              $\C{// turn on reading newline}$
+        char ch;
+        for () {                                                                $\C{// read/write characters}$
+                in | ch;
+          if ( eof( in ) ) break;                               $\C{// eof ?}$
+                out | ch;
+        } // for
+} // main
+\end{cfa}
+\caption{\CFA Command-Line Processing}
+\label{f:CFACommand-LineProcessing}
+\end{figure}
+
+\VRef[Figure]{f:StreamFunctions} shows the stream operations.
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+\Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
+\item
+\Indexc{clear} resets the stream error-indicator.
+\item
+\Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
+\item
+\Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
+Returns true if the end-of-file indicator is set, otherwise false.
+\item
+\Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
+\item
+\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.
+Eager buffer writes are done with ©flush©
+\item
+\Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
+\item
+\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
+Pushed-back characters returned by subsequent reads in the reverse order of pushing.
+\end{itemize}
+The constructor functions:
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+create an unbound stream, which is subsequently bound to a file with ©open©.
+\item
+create a bound stream to the associated file with given ©mode©.
+\end{itemize}
+The destructor closes the stream.
+
+\begin{figure}
+\begin{cfa}
+// *********************************** ofstream ***********************************
+
+bool fail( ofstream & );$\indexc{fail}\index{ofstream@©ofstream©!©fail©}$
+void clear( ofstream & );$\indexc{clear}\index{ofstream@©ofstream©!©clear©}$
+int flush( ofstream & );$\indexc{flush}\index{ofstream@©ofstream©!©flush©}$
+void open( ofstream &, const char name[], const char mode[] = "w" );$\indexc{open}\index{ofstream@©ofstream©!©open©}$
+void close( ofstream & );$\indexc{close}\index{ofstream@©ofstream©!©close©}$
+ofstream & write( ofstream &, const char data[], size_t size );$\indexc{write}\index{ofstream@©ofstream©!©write©}$
+
+void ?{}( ofstream & );$\index{ofstream@©ofstream©!©?{}©}$
+void ?{}( ofstream &, const char name[], const char mode[] = "w" );
+void ^?{}( ofstream & );$\index{ofstream@©ofstream©!©^?{}©}$
+
+// *********************************** ifstream ***********************************
+
+bool fail( ifstream & is );$\indexc{fail}\index{ifstream@©ifstream©!©fail©}$
+void clear( ifstream & );$\indexc{clear}\index{ifstream@©ifstream©!©clear©}$
+bool eof( ifstream & is );$\indexc{eof}\index{ifstream@©ifstream©!©eof©}$
+void open( ifstream & is, const char name[], const char mode[] = "r" );$\indexc{open}\index{ifstream@©ifstream©!©open©}$
+void close( ifstream & is );$\indexc{close}\index{ifstream@©ifstream©!©close©}$
+ifstream & read( ifstream & is, char data[], size_t size );$\indexc{read}\index{ifstream@©ifstream©!©read©}$
+ifstream & ungetc( ifstream & is, char c );$\indexc{unget}\index{ifstream@©ifstream©!©unget©}$
+
+void ?{}( ifstream & is );$\index{ifstream@©ifstream©!©?{}©}$
+void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
+void ^?{}( ifstream & is );$\index{ifstream@©ifstream©!©^?{}©}$
+\end{cfa}
+\caption{Stream Functions}
+\label{f:StreamFunctions}
+\end{figure}
 
 
@@ -4030 +4156 @@
 sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" );
 \end{cfa}
-\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
+\begin{cfa}[showspaces=true,aboveskip=0pt]
 ®  ®34 ® ®34 34
 ®  ®4.000000 ® ®4.000000 4.000000
@@ -4378 +4504 @@
 \end{cfa}
 
-\Textbf{WARNING:} ©printf©\index{printf@©printf©}, ©scanf©\index{scanf@©scanf©} and their derivatives are unsafe when used with user-level threading, as in \CFA.
-These stream routines use kernel-thread locking (©futex©\index{futex@©futex©}), which block kernel threads, to prevent interleaving of I/O.
-However, the following simple example illustrates how a deadlock can occur (other complex scenarios are possible).
-Assume a single kernel thread and two user-level threads calling ©printf©.
-One user-level thread acquires the I/O lock and is time-sliced while performing ©printf©.
-The other user-level thread then starts execution, calls ©printf©, and blocks the only kernel thread because it cannot acquire the I/O lock.
-It does not help if the kernel lock is multiple acquisition, \ie, the lock owner can acquire it multiple times, because it then results in two user threads in the ©printf© critical section, corrupting the stream.
+
+\section{String Stream}
+
+All the stream formatting capabilities are available to format text to/from a C string rather than to a stream file.
+\VRef[Figure]{f:StringStreamProcessing} shows writing (output) and reading (input) from a C string.
+\begin{figure}
+\begin{cfa}
+#include <fstream.hfa>
+#include <strstream.hfa>
+
+int main() {
+        enum { size = 256 };
+        char buf[size]; $\C{// output buffer}$
+        ®ostrstream osstr = { buf, size };® $\C{// bind output buffer/size}$
+        int i = 3, j = 5, k = 7;
+        double x = 12345678.9, y = 98765.4321e-11;
+
+        osstr | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)); $\C{// same lines of output}$
+        write( osstr );
+        printf( "%s", buf );
+        sout | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y));
+
+        char buf2[] = "12 14 15 3.5 7e4"; $\C{// input buffer}$
+        ®istrstream isstr = { buf2 };®
+        isstr | i | j | k | x | y;
+        sout | i | j | k | x | y;
+}
+\end{cfa}
+\caption{String Stream Processing}
+\label{f:StringStreamProcessing}
+\end{figure}
+
+\VRef[Figure]{f:StringStreamFunctions} shows the string stream operations.
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+\Indexc{write} (©ostrstream© only) writes all the buffered characters to the specified stream (©stdout© default).
+\end{itemize}
+The constructor functions:
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+create a bound stream to a write buffer (©ostrstream©) of ©size© or a read buffer (©istrstream©) containing a C string terminated with ©'\0'©.
+\end{itemize}
+
+\begin{figure}
+\begin{cfa}
+// *********************************** ostrstream ***********************************
+
+ostrstream & write( ostrstream & os, FILE * stream = stdout );
+
+void ?{}( ostrstream &, char buf[], size_t size );
+
+// *********************************** istrstream ***********************************
+
+void ?{}( istrstream & is, char buf[] );
+\end{cfa}
+\caption{String Stream Functions}
+\label{f:StringStreamFunctions}
+\end{figure}
 
 
@@ -8111 +8288 @@
 \begin{cquote}
 \begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
-\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}@{}}   \\
+\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c@{}}{\textbf{C}}   \\
 \hline
 \begin{cfa}
-#include <gmp>$\indexc{gmp}$
+#include <gmp.hfa>$\indexc{gmp}$
 int main( void ) {
         sout | "Factorial Numbers";