C++ For Dummies (2014)

---

Other Methods of the Stream Classes

The istream and ostream classes provide a number of methods, as shown in Table 23-3 (this is not a complete list). The prototypes for these functions reside in the fstream include file. They are described in the remainder of this section.

Table 23-3 Major Methods of the I/O Stream Classes

Method	Meaning
bool bad()	Returns true if a serious error has occurred.
void clear(iostate flags = ios_base::goodbit)	Clears (or sets) the I/O state flags.
void close()	Closes the file associated with a stream object.
bool eof()	Returns true if no more characters are left in the file to be read.
iostate exception()	Returns the conditions that will cause an exception.
void exception(iostate)	Sets the conditions that will cause an exception. Multiple conditions can be ORed together; e.g., exception(ios_base::badbit|ios_base::failbit). See Chapter 24 for a discussion of exceptions.
char fill()char fill(char newFill)	Returns or sets the fill character.
fmtflags flags()fmtflags flags(fmtflags f)	Returns or sets format flags. (See the “Controlling format” section.)
void flush()	Flushes the output buffer to the disk.
int gcount()	Returns the number of bytes read during the last input.
char get()	Reads individual characters from the file.
char getline( char* buffer, int count, char delimiter = '\n')	Reads multiple characters either until the end-of-file, until a delimiter is encountered, or until count - 1 characters read. Tack a null onto the end of the line read. Do not store the delimiter read into the buffer.
bool good()	Returns true if no error conditions are set.
void open( const char* filename, openmode mode = default)	Same arguments as the constructor. Performs the same file open on an existing object that the constructor performs when creating a new object.
streamsize precision() streamsize precision( streamsize s)	Reads or sets the number of digits displayed for floating-point variables.
ostream& put(char ch)	Writes a single character to the stream.
istream& read( char* buffer, streamsize num)	Reads a block of data. Reads either num bytes or until an end-of-file is encountered, whichever occurs first.
istream& seekg( pos_type position)istream& seekg( off_type offset, ios_base::seekdir)	Positions the read pointer either position bytes from the beginning of the file or offset bytes from the current position.
istream& seekp( pos_type position)istream& seekp( off_type offset, ios_base::seekdir)	Positions the write pointer.
fmtflags setf(fmtflags)	Sets specific format flags. Returns old value.
pos_type tellg()	Returns the position of the read pointer.
pos_type tellp()	Returns the position of the write pointer.
fmtflags unsetf(fmtflags)	Clears specific format flags. Returns old value.
int width()int width(int w)	Reads or sets the number of characters to be displayed by the next formatted output statement.
ostream& write( const char* buffer, streamsize num)	Writes a block of data to the output file.

Reading and writing streams directly

The inserter and extractor operators provide a convenient mechanism for reading formatted input. However, sometimes you just want to say, “Give it to me; I don't care what the format is.” Several methods are useful in this context.

The simplest function, get(), just returns the next character in the input file. Its output equivalent is put(). The function getline() returns a string of characters up until some terminator — the default is a newline. getline() strips off the terminator but makes no other attempt to reformat or otherwise interpret the input.

The member function read() is even more basic. This function reads the number of characters that you specify, or less if the program encounters an end-of-file. The function gcount() always returns the actual number of characters read. The output equivalent is write().

The following example program uses the read() and write() functions to create a backup of any file you give it by making a copy with the string “.backup” appended to the name:

// FileCopy - make backup copies of the files passed
// to the program
#include <cstdio>
#include <cstdlib>
#include <fstream>
#include <iostream>
using namespace std;

int main(int nNumberofArgs, char* pszArgs[])
{
// repeat the process for every file passed
for (int n = 1; n < nNumberofArgs; n++)
{
// create a filename and a ".backup" name
string szSource(pszArgs[n]);
string szTarget = szSource + ".backup";

// now open the source for reading and the
// target for writing
ifstream input(szSource.c_str(),
ios_base::in|ios_base::binary);

ofstream output(szTarget.c_str(),
ios_base::out|ios_base::binary|ios_base::trunc);
if (input.good() && output.good())
{
cout << "Backing up " << szSource << "...";

// read and write 4k blocks until either an
// error occurs or the file reaches EOF
while(!input.eof() && input.good())
{
char buffer[4096];
input.read(buffer, 4096);
output.write(buffer, input.gcount());
}
cout << "finished" << endl;
}
else
{
cerr << "Couldn't copy " << szSource << endl;
}
}

cout << "Press Enter to continue..." << endl;
cin.ignore(10, '\n');
cin.get();
return 0;
}

The program iterates through the arguments passed to it, remembering that pszArgs[0] points to the name of the program itself. For every source file passed as an argument, the program creates the target filename by tacking “.backup” onto the end. It then opens the source file for binary input and the target for binary output, specifying to truncate the target file if it already exists.

If either the input or output object has an error set, the program outputs a “Couldn't copy” message without attempting to figure out what went wrong. If both objects are good(), however, the program enters a loop in which it reads 4K blocks from the input and writes them out to theoutput.

Notice that in the call to write(), the program uses the value returned from gcount() rather than hardcoding 4096. This is because, unless the source file just happens to be an integer multiple of 4096 bytes in length, the last call to read() will fetch less than the requested number of bytes before encountering end-of-file.

Controlling format

The flags(), setf(), and unsetf() methods are all used to set or retrieve a set of format flags maintained within the istream or ostream object. These format flags get set when the object is created to a default value that represents the most common format options. The options are shown in Table 23-4.

Table 23-4 The I/O Stream Format Flags

Flag	If flag is true, then …
boolalpha	Displays bool as either true or false rather than 1 or 0.
dec	Reads or writes integers in decimal format (default).
fixed	Displays floating point in fixed point as opposed to scientific (default).
hex	Reads or writes integers in hexadecimal.
left	Displays output left justified (i.e., pads on the right).
oct	Reads or writes integers in octal.
right	Displays output right justified (i.e., pads on the left).
scientific	Displays floating point in scientific format.
showbase	Displays a leading 0 for octal output and leading 0x for hexadecimal output.
showpoint	Displays a decimal point for floating-point output even if the fractional portion is 0.
skipws	Skips over whitespace when reading using the extractor.
unitbuf	Flushes output after each output operation.
uppercase	Replaces lowercase letters with their uppercase equivalents on output.

The following code segment has been used in the past to display numbers in hexadecimal format (see the BitTest program in Chapter 4):

// read the current format flags
// (this is important when you need to restore the output
// format at a later time)
ios_base::fmtflags prevValue = cout.flags();

// clear the decimal flag
cout.unsetf(cout.dec);

// now set the hexadecimal flag
cout.setf(cout.hex);

// ...do stuff..

// call flags() to restore the format flags to their
// previous value
cout.flags(prevValue);

In this example, the program must both set the hexadecimal flags using setf() and unset (that is, clear) the decimal flag using unsetf() because the decimal, octal, and hexadecimal flags are mutually exclusive.

The final call to flags() restores the format flags to their previously read value. This is not necessary if the program is about to terminate anyway.

Further format control is provided by the width() method that sets the minimum width of the next output operation. In the event that the field does not take up the full width specified, the inserter adds the requisite number of fill characters. The default fill character is a space, but you can change this by calling fill(). Whether C++ adds the fill characters on the left or right is determined by whether the left or right format flag is set.

For example, the following segment

int i = 123;
cout.setf(cout.right);
cout.unsetf(cout.left);
cout.fill('+');
cout << "i = [";
cout.width(10);
cout << i;
cout << "]" << endl;

generates the following output:

i = [+++++++123]

Notice that the width() method applies only to the very next output statement. Unlike the other formatting flags, the width() must be reset after every value that you output.

What's up with endl?

Most programs in this book terminate an output stream by inserting the object endl. However, some programs include \n within the text to output a newline. What's the deal?

The \n is, in fact, the newline character. The expression cout << “First line\nSecond line; outputs two lines. The endl object outputs a newline, but continues one step further.

Disks are slow devices. Writing to disk more often than necessary will slow down your program considerably. To avoid this, the fstream class collects output into an internal buffer known as a cache (pronounced like “cash”). The class writes the contents to disk when the buffer is full (this is known as flushing the cache). The endl object outputs a newline and then flushes the output cache. The member function flush() flushes the output cache without tacking a newline onto the end.

Note that the standard error object cerr does not buffer output.

Positioning the pointer within a file

The istream class maintains a read pointer that is the location within the file of the next byte to read. This is measured as “number of bytes from the beginning of the file.” You can retrieve this using the tellg() method. (Similarly, the tellp() returns a pointer to the next location to write in an ostream object.) Having saved off the location, you can later return to the same location by passing the value to seekg().

An overloaded version of seekg() takes not an absolute position but an offset and a seek direction. The legal value for the seek direction is one of the following three constants:

· ios_base::beg (beg for beginning of file): The offset must be positive and is taken to be the number of bytes from the beginning of the file.

· ios_base::end (end for end of file): The offset must be negative and is taken to be the number of bytes from the end of the file.

· ios_base::cur (cur for current position): The offset can be either positive or negative and is the number of bytes to move the pointer (either forward or backward) from its current position.

Moving the read (or write) pointer around in a file can be very slow (in computer terms), so be judicious in the use of this feature.

Using the stringstream Subclasses

The stream classes give the programmer mechanisms for easily breaking input among int, float, and char array variables (among others). A set of so-called stringstream classes allow the program to read from an array of characters in memory as if it were reading from a file. The classesistringstream and ostringstream are defined in the include file sstream.

The older versions of these classes are istrstream and ostrstream defined in the include file strstream.

The stringstream classes have the same semantics as the corresponding file-based classes. This is demonstrated in the following StringStream program, which parses account information from a file:

// StringStream - read and parse the contents of a file
#include <cstdio>
#include <cstdlib>
#include <fstream>
#include <sstream>
#include <iostream>
using namespace std;

// parseAccountInfo - read a passed buffer as if it were
// an actual file - read the following
// format:
// name, account balance
// return true if all worked well
bool parseString(const char* pString,
char* pName, int arraySize,
long& accountNum, double& balance)
{
// associate an istrstream object with the input
// character string
istringstream inp(pString);

// read up to the comma separator
inp.getline(pName, arraySize, ',');

// now the account number
inp >> accountNum;

// and the balance
inp >> balance;

// return the error status
return !inp.fail();
}

int main(int nNumberofArgs, char* pszArgs[])
{
// must provide filename
char szFileName[128];
cout << "Input name of file to parse:";
cin.getline(szFileName, 128);

// get a file stream
ifstream* pFileStream = new ifstream(szFileName);
if (!pFileStream->good())
{
cerr << "Can't open " << pszArgs[1] << endl;
return 0;
}

// read a line out of file, parse it and display
// results
for(int nLineNum = 1;;nLineNum++)
{
// read a buffer
char buffer[256];
pFileStream->getline(buffer, 256);
if (pFileStream->fail())
{
break;
}
cout << nLineNum << ":" << buffer << endl;

// parse the individual fields
char name[80];
long accountNum;
double balance;
bool result = parseString(buffer, name, 80,
accountNum, balance);
if (result == false)
{
cerr << "Error parsing string\n" << endl;
continue;
}

// output the fields we parsed out
cout << "Read the following fields:" << endl;
cout << " name = " << name << "\n"
<< " account = " << accountNum << "\n"
<< " balance = " << balance << endl;

// put the fields back together in a different
// order (inserting the 'ends' makes sure the
// buffer is null terminated
ostringstream out;
out << name << ", "
<< balance << " "
<< accountNum << ends;

string oString = out.str();
cout << "Reordered fields: " << oString << endl;
}

cout << "Press Enter to continue..." << endl;
cin.ignore(10, '\n');
cin.get();
return 0;
}

This program begins by opening a file called Accounts.txt containing account information in the format of name, accountNumber, balance,\n. Assuming that the file was opened successfully, the program enters a loop, reading lines until the contents of the file are exhausted. The call to getline() reads up to the default newline terminator. The program passes the line just read to the function parseString().

parseString() associates an istringstream object with the character string. The program reads characters up to the ',' (or the end of the string buffer) using the getline() member function. The program then uses the conventional extractors to read accountNum and balance.

After the call to parseString(), main() outputs the buffer read from the file followed by the parsed values. It then uses the ostringstream class to reconstruct a string object with the same data but a different format (just for the fun of it).

The result from a sample execution appears as follows:

Input name of file to parse:Accounts.txt
1:Chester, 12345 56.60
Read the following fields:
name = Chester
account = 12345
balance = 56.6
Reordered fields: Chester, 56.6 12345
2:Arthur, 34567 67.50
Read the following fields:
name = Arthur
account = 34567
balance = 67.5
Reordered fields: Arthur, 67.5 34567
3:Trudie, 56x78 78.90
Error parsing string

4:Valerie, 78901 89.10
Read the following fields:
name = Valerie
account = 78901
balance = 89.1
Reordered fields: Valerie, 89.1 78901
Press Enter to continue ...

Reflect a second before continuing. Notice how the program was able to resync itself after the error in the input file. Notice, also, the simplicity of the heart of the program, the parseString() function. Consider what this function would look like without the benefit of the istringstreamclass.

Manipulating Manipulators

You can use stream I/O to output numbers and character strings by using default formats. Usually the defaults are fine, but sometimes they don’t cut it.

For example, I was less than tickled when the total from the result of a financial calculation from a recent program appeared as 249.600006 rather than 249.6 (or, better yet, 249.60). There must be a way to bend the defaults to my desires. True to form, C++ provides not one but two ways to control the format of output.

Depending on the default settings of your compiler, you may get 249.6 as your output. Nevertheless, you really want 249.60.

First, you can control the format by invoking a series of member functions on the stream object. For example, the number of significant digits to display is set by using the function precision() as follows (see Table 23-3):

#include <iostream>
void fn(double interest, double dollarAmount)
{
cout << "Dollar amount = ";
cout.precision(2);
cout << dollarAmount;
cout.precision(4);
cout << interest << endl;
}

In this example, the function precision() sets the precision to 2 immediately before outputting the value dollarAmount. This gives you a number such as 249.60, the type of result you want. It then sets the precision to 4 before outputting the interest.

A second approach uses what are called manipulators. (Sounds like someone behind the scenes of the New York Stock Exchange, doesn’t it?) Manipulators are objects defined in the include file iomanip to have the same effect as the member function calls. (You must include iomanip to have access to the manipulators.) The only advantage to manipulators is that the program can insert them directly into the stream rather than resort to a separate function call.

The most common manipulators and their corresponding meanings are shown in Table 23-5.

Table 23-5 Common Manipulators and Stream Format Control Functions

Manipulator	Member Function	Description
dec	setf(dec)	Sets radix to 10
hex	setf(hex)	Sets radix to 16
oct	setf(oct)	Sets radix to 8
setfill(c)	fill(c)	Sets the fill character to c
setprecision(n)	precision(n)	Sets display precision to n
setw(n)	width(n)	Sets width of field to n characters*

* This returns to its default value after the next field is output.

If you rewrite the preceding example to use manipulators, the program appears as follows:

#include <iostream>
#include <iomanip>
void fn(double interest, double dollarAmount)
{
cout << "Dollar amount = "
<< setprecision(2) << dollarAmount
<< setprecision(4) << interest << endl;