Changeset c132d50 for doc/user/user.tex
- Timestamp:
- Apr 28, 2021, 10:06:28 PM (3 years ago)
- 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
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/user/user.tex
r091011a rc132d50 11 11 %% Created On : Wed Apr 6 14:53:29 2016 12 12 %% Last Modified By : Peter A. Buhr 13 %% Last Modified On : Sun Apr 25 19:03:03202114 %% Update Count : 495113 %% Last Modified On : Wed Apr 28 21:48:59 2021 14 %% Update Count : 5051 15 15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 16 16 … … 3312 3312 3313 3313 \section{Tuples} 3314 \label{tuples} 3314 3315 3315 3316 In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call. … … 3420 3421 3421 3422 \subsection{Tuple Coercions} 3423 \label{tuple coercions}\label{coercions!tuple} 3422 3424 3423 3425 There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring. … … 3464 3466 3465 3467 \subsection{Mass Assignment} 3468 \label{mass assignment}\label{assignment!mass} 3466 3469 3467 3470 \CFA permits assignment to several variables at once using mass assignment~\cite{CLU}. … … 3504 3507 3505 3508 \subsection{Multiple Assignment} 3509 \label{multiple assignment}\label{assignment!multiple} 3506 3510 3507 3511 \CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}. … … 3545 3549 3546 3550 \subsection{Cascade Assignment} 3551 \index{cascade assignment}\index{assignment!cascade} 3547 3552 3548 3553 As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment. … … 3564 3569 \section{Stream I/O Library} 3565 3570 \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} 3568 3573 3569 3574 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. 3570 3575 Stream 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.3576 Implicit formatting means \CFA selects the output or input format for values that matches the variable's type. 3572 3577 Explicit formatting means additional information is specified to augment how an output or input of value is interpreted. 3573 \CFA formatting i s 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. 3574 3579 Specifically: 3575 3580 \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. 3585 3590 Without 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 valuesthan Python, plus implicit newline at the end of a print.3591 Furthermore, 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. 3589 3594 \end{itemize} 3595 3596 The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©). 3597 Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file. 3598 Stream ©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} 3603 Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively. 3590 3604 The \CFA header file for the I/O library is \Indexc{fstream.hfa}. 3605 3606 3607 \subsection{Basic I/O} 3591 3608 3592 3609 For implicit formatted output, the common case is printing a series of variables separated by whitespace. … … 3601 3618 \begin{cfa} 3602 3619 3603 cout << x ®<< " "® << y ®<< " "® << z<< endl;3620 cout << x ®<< " "® << y ®<< " "® << z << endl; 3604 3621 \end{cfa} 3605 3622 & … … 3653 3670 \end{tabular} 3654 3671 \end{cquote} 3655 Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.3672 Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators. 3656 3673 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. 3657 3674 … … 3698 3715 \end{cquote} 3699 3716 3717 \VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file. 3718 Note, a stream variable may be copied because it is a reference to an underlying stream data-structures. 3719 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. 3720 3721 \begin{figure} 3722 \begin{cfa} 3723 #include ®<fstream.hfa>® 3724 3725 int 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. 3770 Returns 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. 3777 The bytes are written lazily to file when internal buffers fill. 3778 Eager 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. 3783 Pushed-back characters returned by subsequent reads in the reverse order of pushing. 3784 \end{itemize} 3785 The constructor functions: 3786 \begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt] 3787 \item 3788 create an unbound stream, which is subsequently bound to a file with ©open©. 3789 \item 3790 create a bound stream to the associated file with given ©mode©. 3791 \end{itemize} 3792 The destructor closes the stream. 3793 3794 \begin{figure} 3795 \begin{cfa} 3796 // *********************************** ofstream *********************************** 3797 3798 bool fail( ofstream & );$\indexc{fail}\index{ofstream@©ofstream©!©fail©}$ 3799 void clear( ofstream & );$\indexc{clear}\index{ofstream@©ofstream©!©clear©}$ 3800 int flush( ofstream & );$\indexc{flush}\index{ofstream@©ofstream©!©flush©}$ 3801 void open( ofstream &, const char name[], const char mode[] = "w" );$\indexc{open}\index{ofstream@©ofstream©!©open©}$ 3802 void close( ofstream & );$\indexc{close}\index{ofstream@©ofstream©!©close©}$ 3803 ofstream & write( ofstream &, const char data[], size_t size );$\indexc{write}\index{ofstream@©ofstream©!©write©}$ 3804 3805 void ?{}( ofstream & );$\index{ofstream@©ofstream©!©?{}©}$ 3806 void ?{}( ofstream &, const char name[], const char mode[] = "w" ); 3807 void ^?{}( ofstream & );$\index{ofstream@©ofstream©!©^?{}©}$ 3808 3809 // *********************************** ifstream *********************************** 3810 3811 bool fail( ifstream & is );$\indexc{fail}\index{ifstream@©ifstream©!©fail©}$ 3812 void clear( ifstream & );$\indexc{clear}\index{ifstream@©ifstream©!©clear©}$ 3813 bool eof( ifstream & is );$\indexc{eof}\index{ifstream@©ifstream©!©eof©}$ 3814 void open( ifstream & is, const char name[], const char mode[] = "r" );$\indexc{open}\index{ifstream@©ifstream©!©open©}$ 3815 void close( ifstream & is );$\indexc{close}\index{ifstream@©ifstream©!©close©}$ 3816 ifstream & read( ifstream & is, char data[], size_t size );$\indexc{read}\index{ifstream@©ifstream©!©read©}$ 3817 ifstream & ungetc( ifstream & is, char c );$\indexc{unget}\index{ifstream@©ifstream©!©unget©}$ 3818 3819 void ?{}( ifstream & is );$\index{ifstream@©ifstream©!©?{}©}$ 3820 void ?{}( ifstream & is, const char name[], const char mode[] = "r" ); 3821 void ^?{}( ifstream & is );$\index{ifstream@©ifstream©!©^?{}©}$ 3822 \end{cfa} 3823 \caption{Stream Functions} 3824 \label{f:StreamFunctions} 3825 \end{figure} 3700 3826 3701 3827 … … 4030 4156 sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" ); 4031 4157 \end{cfa} 4032 \begin{cfa}[showspaces=true,aboveskip=0pt ,belowskip=0pt]4158 \begin{cfa}[showspaces=true,aboveskip=0pt] 4033 4159 ® ®34 ® ®34 34 4034 4160 ® ®4.000000 ® ®4.000000 4.000000 … … 4378 4504 \end{cfa} 4379 4505 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 4509 All 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 4516 int 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} 4543 The constructor functions: 4544 \begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt] 4545 \item 4546 create 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 4553 ostrstream & write( ostrstream & os, FILE * stream = stdout ); 4554 4555 void ?{}( ostrstream &, char buf[], size_t size ); 4556 4557 // *********************************** istrstream *********************************** 4558 4559 void ?{}( istrstream & is, char buf[] ); 4560 \end{cfa} 4561 \caption{String Stream Functions} 4562 \label{f:StringStreamFunctions} 4563 \end{figure} 4387 4564 4388 4565 … … 8111 8288 \begin{cquote} 8112 8289 \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}} \\ 8114 8291 \hline 8115 8292 \begin{cfa} 8116 #include <gmp >$\indexc{gmp}$8293 #include <gmp.hfa>$\indexc{gmp}$ 8117 8294 int main( void ) { 8118 8295 sout | "Factorial Numbers";
Note: See TracChangeset
for help on using the changeset viewer.