View source for Courses/CS 2114/Lab Manual/Input and Output

= Input and Output =
{{TOCright}}
==Introduction==

The purpose of this lab is to complete the discussion on console input and output and introduce the use of files for input and output of information.

<blockquote><i>Topics Covered in this Lab:</i>
   <ul><li />input and output streams
   <li />formatting of output
   </ul><i>Questions Answered in this Lab:</i>
   <ul><li />How can files be used in a program to read and write information?
   <li />What is a stream and how do streams relate files to keyboard input and monitor output?
   <li />What must be <tt>include</tt>d to do I/O in C++?
   <li />How can the output be formatted?
   </ul><i>Demonstrable Skills Acquired in this Lab:</i>
   <ul><li />ability to manage input and output streams
   <li />ability to format output
   <li />comprehension of basic sequential file access
   </ul>
</blockquote>

==Input and Output==
As you have seen, a program that has a practical purpose must be able to receive data from outside of itself as well as send results to the outside world.  The data obtained by the program is termed ''input''; if you were to imagine a diagram, it would show the data moving '''in'''to the program.  In this same diagram, the results sent to the outside would be shown as moving '''out''' of the program; hence the term ''output''.

==I/O Streams==
In C++, input and output is done by way of <i>streams</i> of <i>bytes</i>, where a byte can be thought of as equivalent to a single keystroke.  These streams are sequential in nature.  If the user of a program types '1', '2', followed by '3', the stream will keep the keystrokes in that same order.  Likewise, the stream will display the output in the exact order written by the programmer such as the example shown below and seen in the previous lab.

{{Begin Section|Example Code}}
[[File:CS2114MoreMeaningfulOutput.png]]
{{End Section}}

Recall the stream extraction operator (<tt>>></tt>) and the stream insertion operator (<tt><<</tt>) "point" to direct the flow of the data.

Consider the <tt>include</tt> and <tt>using</tt> statements of each program to date.

{{Begin Section|Example Code}}
[[File:CS2114iostream_cin_cout.png]]
{{End Section}}

The <tt>iostream</tt> header file associates an input stream from the keyboard with <tt>cin</tt> (<i><u>c</u>onsole <u>in</u>put</i>) and an output stream to the display with <tt>cout</tt> (<i><u>c</u>onsole <u>out</u>put</i>).  The user can then move characters from the keyboard into program variables or move characters from the program to the display without concern to the details of how these actions occur.

It is also possible to define additional streams in a program. Such streams might be associated with a file on the disk drive. The files we will examine will be text files.

The <tt>fstream</tt> library contains three different ways to define a stream associated with a text file.
{| class="wikitable" border="0" cellpadding="4"
|'''Stream'''      || '''Default Purpose'''
|-
|<tt>fstream</tt>  || provides the ability to both read from and write to a file
|-
|<tt>ifstream</tt> || provides the ability to read from a file
|-
|<tt>ofstream</tt> || provides the ability to write to a file
|}

File stream variables, often referred to as ''file handles'', are used in four logical contexts in a program:
:; define: set aside storage for the stream and label it
:; open: associate (or <i>bind</i>) the logical stream identifier with the physical file
:; use: move characters to or from the file stream
:; close: end the association of the logical file with the physical file; release computer resources

When dealing with file streams, it is important to note that the program does not directly read from or write to a file.  Instead, the computer hardware and device drivers take on this role.  The program will actually deal with a buffer, which is just an area in memory where the computer holds a block of read data from a file or a block of data to be written to a file.  The file streams are sequential just as the console streams are.

When a read occurs, the computer will read enough data to fill the buffer; it will "remember" where it finished reading and will begin from there on the next read.  When the program performs a read, it can rely on the computer to supply it with the next available data in the buffer.  There is no need for the program to keep track of where it is in the data.

When the program executes a write statement, the data is actually written to the buffer.  When the buffer becomes full, the computer will write the information contained in the buffer and, again, "remember" where it wrote the last byte so it can begin writing there the next time the buffer is filled or when it is flushed.  When a file opened for writing is closed, the buffer is ''flushed'', or written, before the association between the logical file and the physical file is broken.

==User-Defined Output Streams==
Let's begin by examining <tt>ofstream</tt>.

===<tt>ofstream</tt>===
{{Create Project|Create a new directory ''sp03'', change into it, and create a new program in file ''sp03t1.cpp'' with an <tt>include</tt> and <tt>using</tt> for <tt>ofstream</tt>.}}

{{Begin Section|Verbatim Code}}
[[File:CS2114include_fstream.png]]
{{End Section}}

File stream variables of type <tt>ofstream</tt> may now be created in the program, just as integer variables of type <tt>int</tt> are; such a variable is more complex than an integer, but it is a variable nevertheless.

Add the following sequence to function <tt>main</tt> to illustrate the four logical contexts of file streams.

{{Begin Section|Verbatim Code}}
[[File:CS2114StreamContexts.png]]
{{End Section}}

<i>Defining</i> a stream variable is very much like defining an integer. <i>Opening</i> a stream variable is said to <i>bind</i> a logical file to a physical file; in the sequence above, <tt>outfile</tt> is bound to "<tt>out1.txt</tt>."  Using a user-defined stream variable is like using <tt>cout</tt> (or <tt>cin</tt>).  Closing a stream variable "unbinds" it from a physical file.  Execute the program and examine the directory containing the program file <i>sp03t1.cpp</i>.  It should now contain the file <i>out1.txt</i> with the "hello, world" contents specified.

A shorthand notation is sometimes used to combine the definition and opening of a file stream.  Add the following to the program.

{{Begin Section|Verbatim Code}}
[[File:CS2114StreamContextShorthand.png]]
{{End Section}}

<!-- CHECK PATH ON SERVER (is Users capitalized??) -->
Execute the program and inspect the current directory for file <i>out2.txt</i>.

Note that a full path name such as <i>c:\My Documents\cs2114\sp03\out2.txt</i> can be specified when opening a file; without a path, the current directory is used.  When specifying a Windows path in a filename, it must be remembered that the first backslash in a character string starts an escape sequence and a second backslash will complete the sequence for the desired backslash; consequently, <tt>"c:\\My Documents\\cs2114\\sp03\\out2.txt"</tt> could specify the example file in C++ program code on a Windows machine.  On a Unix-base machine, the slash used in a path name is a forward slash; nothing special is required to include a forward slash in a path name.  To create <i>out2.txt</i> in a different directory, such as the home directory on the class server, <tt>"/home/username/out2.txt"</tt>, where <i>username</i> is your username, could specify the example file in C++ program code.  Try this now.

Notice that ''out2.txt'' always contains the same data, regardless of the number of times the program is executed.  Take a moment to verify this fact.  By default, when <tt>ofstream</tt> opens a file for writing, if the file already exists, it will be completely overwritten.  However, it is also possible to add to the end of an existing file; this is referred to as <i>appending</i>. Use vi Editor or similar text editor to create a new text file named <i>out3.txt</i> containing the single line "<i>This line was entered manually</i>." Verify the file is in the <tt>sp03</tt> directory. In the program, following the <tt>include</tt> for <tt>fstream</tt>, add a <tt>using</tt> statement for <tt>std::ios</tt> (more about this in a moment) and add the following to function <tt>main</tt>.

{{Begin Section|Verbatim Code}}
[[File:CS2114ofstream_app.png]]
{{End Section}}

Execute the program multiple times opening and closing <i>out3.txt</i> each time; it should be observed to grow by one line on each execution.

<tt>app</tt> is an <tt>ios</tt> flag.  A flag is something that is used to indicate mode or specify behavior; in this instance, <tt>app</tt> is used to indicate that the file should be opened in '''app'''end mode.  The following are the flags that we will use with text files.

{| class="wikitable" border="0" cellpadding="4"
|'''<tt>ios</tt> Flag'''      || '''Opening Mode'''
|-
|<code>app</code> || open the file for writing and place the position indicator at the end of the file
|-
|<code>in</code>  || open the file for reading; position indicator placed at the beginning of the file
|-
|<code>out</code> || open the file for writing; any existing file with same name is erased; as file is empty, the position indicator is at the beginning
|}

===<tt>fstream</tt>===
Occasionally, it is useful to be able to decide whether a file stream is to be used for input or output during program execution; in this case, declare the file variable to be of type <tt>fstream</tt>.  (<tt>fstream</tt> is a class found in the <tt>fstream</tt> library.)  Such a file can be used for output at one point and input at another in a program.  Add the necessary <tt>using</tt> statement for <tt>fstream</tt> then add the following to function <tt>main</tt>, noting the specification of stream direction, or file <i>mode</i>, when the file is opened.

{{Begin Section|Verbatim Code}}
[[File:CS2114fstreamOutput.png]]
{{End Section}}

Execute the program again and verify that <i>out4.txt</i> has been created as expected.

It is possible to use <tt>fstream</tt> to open a file for appending.  Create a new text file named <i>out5.txt</i> containing the single line "<i>This line was also entered manually</i>."  Close the file and add the following to function <tt>main</tt>.

{{Begin Section|Verbatim Code}}
[[File:CS2114fstreamOutput_app.png]]
{{End Section}}

Note that the file mode is set as the <i>bitwise or</i> of file modes <tt>out</tt> and <tt>app</tt> (append).  To avoid explaining the bitwise operators further at this time, suffice it to say that <i>or</i> means <i>both</i> in this instance; thus, characters sent to the stream of <tt>outfile5</tt> will be appended to the end of the existing file.  Execute the program several times, opening and closing <i>out5.txt</i> each time; it should be observed to grow by one line on each execution.  Note that file mode <tt>ios::out</tt> used with an existing file causes the file to be destructively overwritten.  Remove <tt>ios::app</tt> from the definition, execute the program again and verify the file contains a single line.


==User-Defined Input Streams==
The preceding examples all dealt with file output.  To illustrate file input, begin by creating file <i>data03iL.txt</i> in the ''sp03'' directory with the following contents.
<source lang=text>
80
74
87
</source>

The contents of file <i>data03iL.txt</i> could represent an exam average, a final exam average and a lab average.  Experiment with file input by adding a <tt>using</tt> statement for <tt>ifstream</tt> then adding the following to function <tt>main</tt> to read the first of these averages.

{{Begin Section|Verbatim Code}}
[[File:CS2114ReadFromFile.png]]
{{End Section}}

Execute the program and verify that the first average is indeed read.  The stream variable <tt>infile</tt> functions much like <tt>cin</tt>; note however that when <tt>cin</tt> moves data from its stream (the keyboard) to the designated variable, it also copies that data to the display.  No such copy takes place for a stream variable such as <tt>infile</tt>.

It should also be pointed out that the integer representing 80 is stored in the input file as two separate characters, <code>'8'</code> and <code>'0'</code>.  On input, these characters are removed from the stream and converted into a single integer value.  The same thing happens in reverse when the integer is subsequently written to the screen via <tt>cout</tt>; the single integer is transformed into two characters for display.

=== Verifying Existence of Input File ===
Extra care needs to be taken with an input stream.  It is an easy mistake to attempt to read from a file which does not exist; for example, the file name <i>data03iL.txt</i> might have been spelled incorrectly or it might have been created in the wrong directory.  File streams have the ability to report whether or not they have been opened successfully.  The file stream's <tt>is_open()</tt> function will return a value of <tt>true</tt> if the stream has been successfully opened, so this value can be used to verify at run-time that the file is indeed present.  Include <tt>cstdlib</tt> at the top of the program, then modify your <tt>main</tt> function beginning at the location currently occupied by the first statement shown below so that the lines beginning with <code>if</code> and ending with the closing brace are inserted exactly as shown.

{{Begin Section|Verbatim Code}}
[[File:CS2114ifstreamVerify.png|550px]]
{{End Section}}

Function <tt>exit</tt>, which is located in <tt>cstdlib</tt>, the C Standard Library, causes much the same thing to occur as the <tt>return</tt> in <tt>main</tt>; note that where 0 is indicated by <tt>return</tt> to signal a program's successful completion, the 1 parameter of <tt>exit</tt> indicates failure.  Execute the program to verify that <i>data03iL.txt</i> is present; change the program's spelling of the filename to <i>dataiL.txt</i> and re-execute the program to verify that the program performs correctly when the file cannot be found.

Correct the spelling of the input filename before continuing.

==Formatted Output==
In the same way as the <tt>iostream</tt> library provides the ability to obtain and display information via the console and <tt>fstream</tt> library provides the ability to obtain and store information via a file, the <tt>iomanip</tt> library provides the ability to control the way the output appears both on the display and in a file.  The following is a list of manipulators provided by <tt>iomanip</tt> that can be used to alter the way data is output by default.

{| class="wikitable" border="0" cellpadding="4"
|'''Manipulator'''     || '''Default Purpose'''              || '''Use''' <!--With Stream Insertion Operator'''-->
|-
|<tt>setw</tt>         || set width in which to display data || <tt>setw(17)</tt>
|-
|<tt>fixed</tt>        || use fixed-point (decimal) notation || <tt>fixed</tt>
|-
|<tt>setprecision</tt> || set decimal precision; when used in conjunction with <tt>fixed</tt>, set number of decimal positions || <tt>setprecision(3)</tt>
|-
|<tt>left</tt>         || set left alignment                 || <tt>left</tt>
|-
|<tt>right</tt>        || set right alignment                || <tt>right</tt>
|}

<p><tt>endl</tt>, found in <tt>iostream</tt>, is one other stream manipulator we will use often.  It inserts a newline and then flushes the buffer.</p>

When using the <tt>setw</tt> manipulator, if the number indicated is not large enough, the data will be displayed in its entirety using as many positions as necessary.  This will result in data values being written side-by-side with no spacing between.  By default, C++ will display very small and very large floating-point numbers in scientific notation; <tt>fixed</tt> will alter this behavior.  By default, C++ will display six decimals of precision; setprecision modifies this behavior.  Once <tt>fixed</tt> and <tt>setprecision</tt> have been set, they remain set until changed or reset; <tt>setw</tt> must be used each time the field width is to be set.

Include the <tt>iomanip</tt> library and add <tt>using</tt> statements for each of the above manipulators.  Copy and paste the following to function ''main'' and examine the code and the results on the display and in the file.

{{Begin Section|Verbatim Code}}
<source lang=cpp>
    // demonstrate precision and fixed notation
    double number = 1234.56789;
    cout << "number with no manipulators:  " << number << endl;
    cout << setprecision(5) << "number with 5 decimals of precision:  "
         << number << endl;
    cout << fixed
         << "number in decimal notation "
         << "(5 decimals of precision still set):  "
         << number << endl;
    cout << setprecision(3)
         << "number in decimal notation with 3 decimals of precision:  "
         << number << endl;

    cout << endl << endl;

    // demonstrate setw and alignment
    // setw only
    cout << setw(10) << "Name" << setw(6) << "Exam1" << setw(6) << "Exam2"
         << setw(6) << "Exam3" << setw(6) << "Exam4" << endl;

    cout << setw(10) << "Buggs" << setw(6) << 77 << setw(6) << 81
         << setw(6) << 74 << setw(6) << 89 << endl;

    // precision still set, note run-on due to insufficient width
    cout << setw(10) << "Daffy" << setw(6) << 89.5 << setw(6) << 93.4
         << setw(6) << 88 << setw(6) << 91.3 << endl;

    // attempt to left align only the name
    cout << left << setw(10) << "Donald" << setw(6) << 85 << setw(6) << 89
         << setw(6) << 93 << setw(6) << 100 << endl;

    // reset precision, left align name, right align scores
    cout << setprecision(1);
    cout << left << setw(10) << "Elmer" << right << setw(6) << 98.7
         << setw(6) << 79 << setw(6) << 68 << setw(6) << 75.5 << endl;

    // demonstrate setw does not remain in effect
    cout << setw(10) << "Taz" << setw(6) << 73 << 76 << 79 << 83 << endl;

    cout << endl << endl;

    // correct table output sent to file
    ofstream fout("table.txt");

    fout << left << setw(10) << "Name" << right << setw(6) << "Exam1" << setw(6)
         << "Exam2" << setw(6) << "Exam3" << setw(6) << "Exam4" << endl;
    fout << left << setw(10) << "Buggs" << right << setw(6) << 77 << setw(6)
         << 81 << setw(6) << 74 << setw(6) << 89 << endl;
    fout << left << setw(10) << "Daffy" << right << setw(6) << 89.5 << setw(6)
         << 93.4 << setw(6) << 88 << setw(6) << 91.3 << endl;
    fout << left << setw(10) << "Donald" << right << setw(6) << 85 << setw(6)
         << 89 << setw(6) << 93 << setw(6) << 100 << endl;
    fout << left << setw(10) << "Elmer" << right << setw(6) << 98.7
         << setw(6) << 79 << setw(6) << 68 << setw(6) << 75.5 << endl;
    fout << left << setw(10) << "Taz" << right << setw(6) << 73 << setw(6)
         << 76 << setw(6) << 79 << setw(6) << 83 << endl;

    fout.close();
</source>
{{End Section}}

Notice that although <tt>number</tt> is rounded on the display, the actual value stored in <tt>number</tt> does not change as evidenced by the output following the rounding.  Output formatting is just that - formatting.  No changes are made to the values stored in variables.


== Reading Characters and Strings ==

{{Create Project|Create a new program in file ''sp03t2.cpp'' with an <tt>include</tt> and <tt>using</tt> for <tt>cin</tt>.}}

<tt>cin</tt> works with any data type, including <tt>char</tt> (character), as well as user defined objects such as ''string''.  Recall that ''string'' is available through the <tt>string</tt> library and will hold a series of characters.  
* create a <tt>char</tt> variable named <tt>ch</tt> and a ''string'' variable called <tt>name</tt>
* prompt the user to enter a character and then his/her name
* read the character into <tt>ch</tt> and the name into <tt>name</tt>
* echo the character back to the screen and greet the user by name

Execute the program and test this code with 
{{Test Data|the letter <tt>B</tt> followed by a space followed by the name <tt>Buggs</tt>}}
The program should work as expected with this input.  Execute the program again and test it with
{{Test Data|the letter <tt>B</tt> followed by the <tt>Enter</tt> key followed by the name <tt>Buggs</tt>}}
Again, the program should work as expected with this input.  Execute the program again and test it with
{{Test Data|the tab character (press the <tt>Tab</tt> key) followed by <tt>Enter</tt> followed by the name <tt>Buggs</tt>}}

A problem occurs with this test data.  What happened when the program attempted to read the tab character?  Recall that <tt>cin</tt> uses whitespace to separate pieces of data.  Since the tab character is considered whitespace, it was ignored by <tt>cin</tt>, so the <tt>B</tt> from the name <tt>Buggs</tt> was read for the character <tt>ch</tt> and the remaining characters, <tt>uggs</tt>, were read as the string <tt>name</tt>.

===<code>cin.get()</code>===
Whitespace cannot be read by <tt>cin</tt> as it is used as a data delimiter.  To read whitespace as a character, a programmer should employ the <tt>cin</tt> object's <tt>get()</tt> method.  <tt>cin.get()</tt> will read a single character including any considered to be whitespace.  The syntax of <tt>cin.get()</tt> is as follows.
{{Begin Section|Code Syntax}}
<source lang=cpp>cin.get(ch);</source>
{{End Section}}
A less commonly seen syntax is
{{Begin Section|Code Syntax}}
<source lang=cpp>ch = cin.get();</source>
{{End Section}}

In either usage shown above, <tt>ch</tt> is the variable in which the character is stored.

Modify your program as follows

* remove the input statement from your code
* add a character input statement implementing <tt>cin.get()</tt>
* immediately following the character input statement, add a <tt>cin</tt> statement to read the name 

Execute the program and test it with 
{{Test Data|the tab character (press the <tt>Tab</tt> key) followed by a space followed by the name <tt>Buggs</tt>}}
The program should work as expected with this input.  Execute the program again and test it with 
{{Test Data|the letter <tt>B</tt> followed by a space followed by the name <tt>Buggs Bunny</tt>}}

A problem occurs with this test data.  As whitespace is used to delimit data, <tt>cin</tt> read <tt>Buggs</tt> then stopped.  The result is that <tt>Buggs</tt> is stored in the string <tt>name</tt> and <tt>Bunny</tt> remains in the buffer until the program ends execution.


===<code>getline()</code>===
<tt>getline()</tt> will read whitespace within a series of characters.  The syntax for the <tt>getline()</tt> function is
{{Begin Section|Code Syntax}}
<source lang=cpp>getline(istream, stringIdentifier);</source>
{{End Section}}
or, optionally,
{{Begin Section|Code Syntax}}
<source lang=cpp>getline(istream, stringIdentifier, delimiter);</source>
{{End Section}}

where <tt>istream</tt> is the input stream, such as <tt>cin</tt>, <tt>stringIdentifier</tt> is the variable which will store the string.  Optionally, the programmer can specify a <tt>delimiter</tt>, a single character, that is used to separate data.  By default, the delimiter is the newline character.  The newline character is introduced into the stream whenever the ''Enter'' key is pressed.

Modify your program 
* delete the input of the string from your code
* use the <tt>getline()</tt> function to read the name using a default delimiter of the newline character<br /><source lang=cpp>getline(cin,name);</source>

The <tt>geline()</tt> call used above will read any characters that were typed up until the ''Enter'' key was pressed and store those character in the string called <tt>name</tt>.  

{{Information|If strings are separated by a character, such as a comma, as in the line <source lang=text>Santa Fe,New Mexico\n</source><tt>getline()</tt> should be utilized with the delimiter specified.  To read the city name specified in the above line into the string named <tt>city</tt> use the statement <source lang=cpp>getline(cin, city, ',');</source> ''Santa Fe'' will be stored in <tt>city</tt>, the comma delimiter will be discarded and the characters ''New Mexico\n'' will still be waiting in the buffer.}}


Execute the program again and test it with 
{{Test Data|the letter <tt>B</tt> followed by a space followed by the name <tt>Buggs Bunny</tt>}}
The program should work as expected with this input.  Execute the program again and test it with 
{{Test Data|<tt>ABC</tt> followed by a space followed by the name <tt>Buggs Bunny</tt>}}

A problem occurs with this test data.  The single character A is read into the character <tt>ch</tt> but the string <tt>name</tt> contains <tt>BC Buggs Bunny</tt> rather than <tt>Buggs Bunny</tt>.

===<code>cin.ignore()</code>===
The need to discard input has been demonstrated.  <tt>cin</tt>'s <tt>ignore()</tt> method is capable of discarding unwanted input.  The syntax for <tt>cin.ignore()</tt> is
{{Begin Section|Code Syntax}}
<source lang=cpp>cin.ignore(number_of_characters_to_ignore);</source>
{{End Section}}

An example call would be
{{Begin Section|Example Code}}
<source lang=cpp>cin.ignore(); // ignore one character</source>
{{End Section}}

This call to <tt>cin.ignore()</tt> will discard the next character in the buffer.  To discard the next ten characters in the buffer, execute the call <code>cin.ignore(10);</code>

To resolve the issue previously introduced, we could add 
{{Begin Section|Example Code}}
<source lang=cpp>cin.ignore(2); // ignore two characters</source>
{{End Section}}
in order to ignore the unwanted <tt>BC</tt> from our last input.  However, the space between <tt>BC</tt> and <tt>Buggs</tt> must also be ignored.  Additionally, this line of code will not work if <tt>ABCD</tt> followed by a space followed by <tt>Buggs Bunny</tt> is entered.

An alternative is to additionally specify a delimiter.
{{Begin Section|Code Syntax}}
<source lang=cpp>cin.ignore(number_of_characters_to_ignore, delimiter);</source>
{{End Section}}

Again, the delimiter is a single character used to separate pieces of data.  When a delimiter is specified, either the <tt>number_of_characters_to_ignore</tt> is ignored, or the number of characters up to and including the delimiter is ignored.  So if the <tt>number_of_characters_to_ignore</tt> is not large enough, there will still be a problem.

One way to resolve this problem is to specify the maximum number of characters the stream can contain at one time.
{{Begin Section|Example Code}}
<source lang=cpp>
// clear the buffer
cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
</source> 
{{End Section}}
where <tt>std::numeric_limits<std::streamsize>::max()</tt> is accessed by including the <tt>limits</tt> library.  The effect of the above call to <tt>cin.ignore()</tt> is to discard all input up to and including the specified delimiter of <tt>\n</tt> or to discard all input in the buffer if no delimiter is encountered.

Modify your program to 
* read a character (statement already in place in program) then
* discard any number of characters until a space is seen then
* read a name (statement already in place in program)

Execute the program again and test it with 
{{Test Data|<tt>ABC</tt> followed by a space followed by the name <tt>Buggs Bunny</tt>}}
The program should work as expected with this input.  Execute the program again and test it with 
{{Test Data|<tt>B</tt> followed by a space followed by the name <tt>Buggs Bunny</tt>}}
The program should work as expected with this input.

<br /><br />