Stream Error States

The state of a stream may be tested through bits in class ios_base. In a moment, we show how to test these bits, in the example of Fig. 15.22.

Figure 15.22. Testing error states.

(This item is displayed on pages 798 - 799 in the print version)

 1 // Fig. 15.22: Fig15_22.cpp
 2 // Testing error states.
 3 #include 
 4 using std::cin;
 5 using std::cout;
 6 using std::endl;
 7 
 8 int main()
 9 {
10 int integerValue;
11 
12 // display results of cin functions
13 cout << "Before a bad input operation:"
14 << "
cin.rdstate(): " << cin.rdstate()
15 << "
 cin.eof(): " << cin.eof() 
16 << "
 cin.fail(): " << cin.fail() 
17 << "
 cin.bad(): " << cin.bad() 
18 << "
 cin.good(): " << cin.good() 
19 << "

Expects an integer, but enter a character: ";
20 
21 cin >> integerValue; // enter character value
22 cout << endl;
23 
24 // display results of cin functions after bad input
25 cout << "After a bad input operation:"
26 << "
cin.rdstate(): " << cin.rdstate()
27 << "
 cin.eof(): " << cin.eof() 
28 << "
 cin.fail(): " << cin.fail() 
29 << "
 cin.bad(): " << cin.bad() 
30 << "
 cin.good(): " << cin.good() << endl << endl;
31 
32 cin.clear(); // clear stream
33 
34 // display results of cin functions after clearing cin
35 cout << "After cin.clear()" << "
cin.fail(): " << cin.fail()
36 << "
cin.good(): " << cin.good() << endl;
37 return 0;
38 } // end main

 

 Before a bad input operation:
 cin.rdstate(): 0
 cin.eof(): 0
 cin.fail(): 0
 cin.bad(): 0
 cin.good(): 1

 Expects an integer, but enter a character: A

 After a bad input operation:
 cin.rdstate(): 2
 cin.eof(): 0
 cin.fail(): 1
 cin.bad(): 0
 cin.good(): 0

 After cin.clear()
 cin.fail(): 0
 cin.good(): 1

 

The eofbit is set for an input stream after end-of-file is encountered. A program can use member function eof to determine whether end-of-file has been encountered on a stream after an attempt to extract data beyond the end of the stream. The call

---

cin.eof()

returns TRue if end-of-file has been encountered on cin and false otherwise.

The failbit is set for a stream when a format error occurs on the stream, such as when the program is inputting integers and a nondigit character is encountered in the input stream. When such an error occurs, the characters are not lost. The fail member function reports whether a stream operation has failed; usually, recovering from such errors is possible.

The badbit is set for a stream when an error occurs that results in the loss of data. The bad member function reports whether a stream operation failed. Generally, such serious failures are nonrecoverable.

---

The goodbit is set for a stream if none of the bits eofbit, failbit or badbit is set for the stream.

The good member function returns true if the bad, fail and eof functions would all return false. I/O operations should be performed only on "good" streams.

The rdstate member function returns the error state of the stream. A call to cout.rdstate, for example, would return the state of the stream, which then could be tested by a switch statement that examines eofbit, badbit, failbit and goodbit. The preferred means of testing the state of a stream is to use member functions eof, bad, fail and goodusing these functions does not require the programmer to be familiar with particular status bits.

The clear member function is used to restore a stream's state to "good," so that I/O may proceed on that stream. The default argument for clear is goodbit, so the statement

cin.clear();

clears cin and sets goodbit for the stream. The statement

cin.clear( ios::failbit )

sets the failbit. The programmer might want to do this when performing input on cin with a user-defined type and encountering a problem. The name clear might seem inappropriate in this context, but it is correct.

The program of Fig. 15.22 demonstrates member functions rdstate, eof, fail, bad, good and clear. [Note: The actual values output may differ across different compilers.]

The operator! member function of basic_ios returns TRue if the badbit is set, the failbit is set or both are set. The operator void * member function returns false (0) if the badbit is set, the failbit is set or both are set. These functions are useful in file processing when a TRue/false condition is being tested under the control of a selection statement or repetition statement.