Changeset c132d50 for doc


Ignore:
Timestamp:
Apr 28, 2021, 10:06:28 PM (3 months ago)
Author:
Peter A. Buhr <pabuhr@…>
Branches:
arm-eh, jacob/cs343-translation, master
Children:
3ec79f7
Parents:
091011a
Message:

update stream documentation and add strstream documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/user/user.tex

    r091011a rc132d50  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Sun Apr 25 19:03:03 2021
    14 %% Update Count     : 4951
     13%% Last Modified On : Wed Apr 28 21:48:59 2021
     14%% Update Count     : 5051
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
     
    33123312
    33133313\section{Tuples}
     3314\label{tuples}
    33143315
    33153316In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
     
    34203421
    34213422\subsection{Tuple Coercions}
     3423\label{tuple coercions}\label{coercions!tuple}
    34223424
    34233425There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
     
    34643466
    34653467\subsection{Mass Assignment}
     3468\label{mass assignment}\label{assignment!mass}
    34663469
    34673470\CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
     
    35043507
    35053508\subsection{Multiple Assignment}
     3509\label{multiple assignment}\label{assignment!multiple}
    35063510
    35073511\CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
     
    35453549
    35463550\subsection{Cascade Assignment}
     3551\index{cascade assignment}\index{assignment!cascade}
    35473552
    35483553As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
     
    35643569\section{Stream I/O Library}
    35653570\label{s:StreamIOLibrary}
    3566 \index{input/output stream library}
    3567 \index{stream library}
     3571\index{input}\index{output}
     3572\index{stream library}\index{library!stream}
    35683573
    35693574The 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.
    35703575Stream I/O can be implicitly or explicitly formatted.
    3571 Implicit formatting means \CFA selects the output or input format for values that match with the type of a variable.
     3576Implicit formatting means \CFA selects the output or input format for values that matches the variable's type.
    35723577Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
    3573 \CFA formatting is a cross between C ©printf© and \CC ©cout© manipulators, and Python implicit spacing and newline.
     3578\CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
    35743579Specifically:
    35753580\begin{itemize}
     
    35843589Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
    35853590Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
    3586 (To guarantee no side-effects, manipulator values must be saved and restored across function calls.)
    3587 \item
    3588 \CFA has more sophisticated implicit spacing between values than Python, plus implicit newline at the end of a print.
     3591Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
     3592\item
     3593\CFA has more sophisticated implicit value spacing than Python, plus implicit newline at the end of a print.
    35893594\end{itemize}
     3595
     3596The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
     3597Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file.
     3598Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
     3599\begin{cfa}
     3600®exit®   | "x (" | x | ") negative value."; // terminate and return EXIT_FAILURE to shell
     3601®abort® | "x (" | x | ") negative value."; // terminate and generate stack trace and core file
     3602\end{cfa}
     3603Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
    35903604The \CFA header file for the I/O library is \Indexc{fstream.hfa}.
     3605
     3606
     3607\subsection{Basic I/O}
    35913608
    35923609For implicit formatted output, the common case is printing a series of variables separated by whitespace.
     
    36013618\begin{cfa}
    36023619
    3603 cout << x ®<< " "® << y ®<< " "® << z << endl;
     3620cout  <<  x  ®<< " "®  <<  y  ®<< " "®  <<  z << endl;
    36043621\end{cfa}
    36053622&
     
    36533670\end{tabular}
    36543671\end{cquote}
    3655 Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.
     3672Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators.
    36563673There 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.
    36573674
     
    36983715\end{cquote}
    36993716
     3717\VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
     3718Note, a stream variable may be copied because it is a reference to an underlying stream data-structures.
     3719All 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.
     3720
     3721\begin{figure}
     3722\begin{cfa}
     3723#include ®<fstream.hfa>®
     3724
     3725int main( int argc, char * argv[] ) {
     3726        ®ifstream® in  = stdin;                                 $\C{// copy default files}$
     3727        ®ofstream® out = stdout;
     3728
     3729        try {
     3730                choose ( argc ) {
     3731                  case 2, 3:
     3732                        ®open®( in, argv[1] );                  $\C{// open input file first as output creates file}$
     3733                        if ( argc == 3 ) ®open®( out, argv[2] ); $\C{// do not create output unless input opens}$
     3734                  case 1: ;                                                     $\C{// use default files}$
     3735                  default:
     3736                        ®exit® | "Usage" | argv[0] | "[ input-file (default stdin) "
     3737                                   "[ output-file (default stdout) ] ]";
     3738                } // choose
     3739        } catch( ®Open_Failure® * ex; ex->istream == &in ) {
     3740                ®exit® | "Unable to open input file" | argv[1];
     3741        } catch( ®Open_Failure® * ex; ex->ostream == &out ) {
     3742                ®close®( in );                                          $\C{// optional}$
     3743                ®exit® | "Unable to open output file" | argv[2];
     3744        } // try
     3745
     3746        out | nlOff;                                                    $\C{// turn off auto newline}$
     3747        in | nlOn;                                                              $\C{// turn on reading newline}$
     3748        char ch;
     3749        for () {                                                                $\C{// read/write characters}$
     3750                in | ch;
     3751          if ( eof( in ) ) break;                               $\C{// eof ?}$
     3752                out | ch;
     3753        } // for
     3754} // main
     3755\end{cfa}
     3756\caption{\CFA Command-Line Processing}
     3757\label{f:CFACommand-LineProcessing}
     3758\end{figure}
     3759
     3760\VRef[Figure]{f:StreamFunctions} shows the stream operations.
     3761\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     3762\item
     3763\Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
     3764\item
     3765\Indexc{clear} resets the stream error-indicator.
     3766\item
     3767\Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
     3768\item
     3769\Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
     3770Returns true if the end-of-file indicator is set, otherwise false.
     3771\item
     3772\Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
     3773\item
     3774\Indexc{close} flushes the stream and closes the file.
     3775\item
     3776\Indexc{write} (©ofstream© only) write ©size© bytes to the stream.
     3777The bytes are written lazily to file when internal buffers fill.
     3778Eager buffer writes are done with ©flush©
     3779\item
     3780\Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
     3781\item
     3782\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
     3783Pushed-back characters returned by subsequent reads in the reverse order of pushing.
     3784\end{itemize}
     3785The constructor functions:
     3786\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     3787\item
     3788create an unbound stream, which is subsequently bound to a file with ©open©.
     3789\item
     3790create a bound stream to the associated file with given ©mode©.
     3791\end{itemize}
     3792The destructor closes the stream.
     3793
     3794\begin{figure}
     3795\begin{cfa}
     3796// *********************************** ofstream ***********************************
     3797
     3798bool fail( ofstream & );$\indexc{fail}\index{ofstream@©ofstream©!©fail©}$
     3799void clear( ofstream & );$\indexc{clear}\index{ofstream@©ofstream©!©clear©}$
     3800int flush( ofstream & );$\indexc{flush}\index{ofstream@©ofstream©!©flush©}$
     3801void open( ofstream &, const char name[], const char mode[] = "w" );$\indexc{open}\index{ofstream@©ofstream©!©open©}$
     3802void close( ofstream & );$\indexc{close}\index{ofstream@©ofstream©!©close©}$
     3803ofstream & write( ofstream &, const char data[], size_t size );$\indexc{write}\index{ofstream@©ofstream©!©write©}$
     3804
     3805void ?{}( ofstream & );$\index{ofstream@©ofstream©!©?{}©}$
     3806void ?{}( ofstream &, const char name[], const char mode[] = "w" );
     3807void ^?{}( ofstream & );$\index{ofstream@©ofstream©!©^?{}©}$
     3808
     3809// *********************************** ifstream ***********************************
     3810
     3811bool fail( ifstream & is );$\indexc{fail}\index{ifstream@©ifstream©!©fail©}$
     3812void clear( ifstream & );$\indexc{clear}\index{ifstream@©ifstream©!©clear©}$
     3813bool eof( ifstream & is );$\indexc{eof}\index{ifstream@©ifstream©!©eof©}$
     3814void open( ifstream & is, const char name[], const char mode[] = "r" );$\indexc{open}\index{ifstream@©ifstream©!©open©}$
     3815void close( ifstream & is );$\indexc{close}\index{ifstream@©ifstream©!©close©}$
     3816ifstream & read( ifstream & is, char data[], size_t size );$\indexc{read}\index{ifstream@©ifstream©!©read©}$
     3817ifstream & ungetc( ifstream & is, char c );$\indexc{unget}\index{ifstream@©ifstream©!©unget©}$
     3818
     3819void ?{}( ifstream & is );$\index{ifstream@©ifstream©!©?{}©}$
     3820void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
     3821void ^?{}( ifstream & is );$\index{ifstream@©ifstream©!©^?{}©}$
     3822\end{cfa}
     3823\caption{Stream Functions}
     3824\label{f:StreamFunctions}
     3825\end{figure}
    37003826
    37013827
     
    40304156sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" );
    40314157\end{cfa}
    4032 \begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
     4158\begin{cfa}[showspaces=true,aboveskip=0pt]
    40334159®  ®34 ® ®34 34
    40344160®  ®4.000000 ® ®4.000000 4.000000
     
    43784504\end{cfa}
    43794505
    4380 \Textbf{WARNING:} ©printf©\index{printf@©printf©}, ©scanf©\index{scanf@©scanf©} and their derivatives are unsafe when used with user-level threading, as in \CFA.
    4381 These stream routines use kernel-thread locking (©futex©\index{futex@©futex©}), which block kernel threads, to prevent interleaving of I/O.
    4382 However, the following simple example illustrates how a deadlock can occur (other complex scenarios are possible).
    4383 Assume a single kernel thread and two user-level threads calling ©printf©.
    4384 One user-level thread acquires the I/O lock and is time-sliced while performing ©printf©.
    4385 The other user-level thread then starts execution, calls ©printf©, and blocks the only kernel thread because it cannot acquire the I/O lock.
    4386 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.
     4506
     4507\section{String Stream}
     4508
     4509All the stream formatting capabilities are available to format text to/from a C string rather than to a stream file.
     4510\VRef[Figure]{f:StringStreamProcessing} shows writing (output) and reading (input) from a C string.
     4511\begin{figure}
     4512\begin{cfa}
     4513#include <fstream.hfa>
     4514#include <strstream.hfa>
     4515
     4516int main() {
     4517        enum { size = 256 };
     4518        char buf[size]; $\C{// output buffer}$
     4519        ®ostrstream osstr = { buf, size };® $\C{// bind output buffer/size}$
     4520        int i = 3, j = 5, k = 7;
     4521        double x = 12345678.9, y = 98765.4321e-11;
     4522
     4523        osstr | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)); $\C{// same lines of output}$
     4524        write( osstr );
     4525        printf( "%s", buf );
     4526        sout | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y));
     4527
     4528        char buf2[] = "12 14 15 3.5 7e4"; $\C{// input buffer}$
     4529        ®istrstream isstr = { buf2 };®
     4530        isstr | i | j | k | x | y;
     4531        sout | i | j | k | x | y;
     4532}
     4533\end{cfa}
     4534\caption{String Stream Processing}
     4535\label{f:StringStreamProcessing}
     4536\end{figure}
     4537
     4538\VRef[Figure]{f:StringStreamFunctions} shows the string stream operations.
     4539\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     4540\item
     4541\Indexc{write} (©ostrstream© only) writes all the buffered characters to the specified stream (©stdout© default).
     4542\end{itemize}
     4543The constructor functions:
     4544\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
     4545\item
     4546create a bound stream to a write buffer (©ostrstream©) of ©size© or a read buffer (©istrstream©) containing a C string terminated with ©'\0'©.
     4547\end{itemize}
     4548
     4549\begin{figure}
     4550\begin{cfa}
     4551// *********************************** ostrstream ***********************************
     4552
     4553ostrstream & write( ostrstream & os, FILE * stream = stdout );
     4554
     4555void ?{}( ostrstream &, char buf[], size_t size );
     4556
     4557// *********************************** istrstream ***********************************
     4558
     4559void ?{}( istrstream & is, char buf[] );
     4560\end{cfa}
     4561\caption{String Stream Functions}
     4562\label{f:StringStreamFunctions}
     4563\end{figure}
    43874564
    43884565
     
    81118288\begin{cquote}
    81128289\begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
    8113 \multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}@{}}   \\
     8290\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c@{}}{\textbf{C}}   \\
    81148291\hline
    81158292\begin{cfa}
    8116 #include <gmp>$\indexc{gmp}$
     8293#include <gmp.hfa>$\indexc{gmp}$
    81178294int main( void ) {
    81188295        sout | "Factorial Numbers";
Note: See TracChangeset for help on using the changeset viewer.