Lecture Notes for Advanced Programming II

27 January 2003 - Stream I-O

Outline

History
Stream structure and types
Unformatted input and output
Stream states
- Non-good stream states
- The EOS stream state
Formatted input-output
- Data-type formats
- Formatted I-O operators
- Stream manipulators
Stream sources.
- File streams
- String streams

History

C didn't include I-O as part of the language.
- I-O was provided by the stdio library.
C++ continued that tradition.
- No I-O in the language, I-O from the AT&T stream I-O library (among others).
Stream I-O was added to the C++ standard library.
- Similarly for stdio in C.
C++ Stream I-O is complicated and powerful.
- It's flexible, and international too (facets).

Stream Structure

A stream is a sequence of data elements.
- A stream may contain an arbitrary number of elements.
The parts of a stream.
- Stream position
- Stream pointer
- Stream data elements
- The stream ends.
  - The end-of-stream (or eos) position.

Stream Types

Streams can be distinguished by two main characteristics:
1. data movement and
2. data-element type.
Data can move into or out of a stream.
- Input streams move data out of a stream.
- Output streams move data into a stream.
- Input-output streams do both.
The data-element types can be arbitrary.
- The two major ones are char and wchar_t.
- Others are possible but probably require a lot of work.
char wchar_t

input <istream> <wistream>

output <ostream> <wostream>

both <iostream> <wiostream>

Unformatted Input

Unformatted input copies data elements from the stream.
- The element referenced by the stream pointer is read.
- The stream pointer moves right one for each element read.
- No element can be read from the end-of-stream position.

Some read operations.


istream & istream::get(char & c)

istream & istream::getline(
  char * str, streamsize cnt)

istream & istream::ignore()

istream & istream::unget()

streamsize istream::gcount()

Unformatted Output

Unformatted output copies data elements to the stream.
- The element referenced by the stream pointer is written.
- The existing element, if any, is overwritten.
- The stream pointer moves right one for each element written.
- The end-of-stream position shifts one to the right if written.

Stream Output Operations

The write operations.

ostream & put(char c)

ostream & write(
  const char * s, streamsize cnt)

ostream & flush()

Stream States

A stream operation can put a stream in one of four states:
1. fail when a soft error occurred during the operation.
2. bad when a hard error occurred during the operation
3. eof when the end-of-stream condition occurs during the operation.
4. good when none of the other states occurred during the operation.
Not all operations can cause all states.
- Output can't cause the eof state and probably won't cause the fail state.
Streams have four predicates to test stream state.
- good(), fail(), bad(), and eof().
- fail() tests for the fail or bad states.
Stream state is sticky; once set, it stays set until clear()ed.
- This can be an annoying source of hard-to-find program errors.

Non-Good Stream States

A recoverable, transient, non-fatal error causes the fail state.
- A format error, a file not found.
A non-recoverable, permanent, fatal error causes the bad state.
- The network collapses, a disk falls over.
The fail and bad states are mostly implementation dependent.
The end-of-stream state occurs when
1. the stream pointer's at the end-of-stream position, and
2. the end-of-stream position is read.
- Just moving the stream pointer to the end-of-stream position does not set the eof state.

The EOS Stream State

The end-of-stream state occurs when
1. the stream pointer's at the end-of-stream position, and
2. the end-of-stream position is read.
- Just moving the stream pointer to the end-of-stream position does not set the eof state.
Don't do this Do this
~~while cin.eof()~~ ~~cin >> x~~ // whatever
while true cin >> x if cin.eof() break // whatever
Remember: should you read the text before or after the test?

State Test Operators

The bang unary prefix operator ! tests a stream's fail or bad state.
- !cin is the same as cin.fail().
```
std::ofstream of(filename)
if (!of)
  // Can't open the file.
```
- ! does not test the stream's end-of-stream state.
Streams also convert to void * pointers.
- And void * pointers convert to a boolean value.
- If cin.fail() is false,
  then cin converts to a non-null void * converts to true.
- If cin.fail() is true,
  then cin converts to a null void * converts to false.
- Pointer conversion does not test the stream's end-of-stream state.
Favor the state predicates over the test operators.
- Make your meaning clear.
- Test for more than just failure (eos in particular).

Formatted Input-Output

An int is a 32-bit (say) number.
- What number is 000000000000000000000011111010011?
Computers have the same problem: an integer is a 9-decimal-digit (say) number.
- But a computer can't deal with 2003.
Similarly, humans understand lots of symbols.
- The 127 ASCII characters, say.
Computers, on the other hand, only understand the symbols 0 and 1.
Formatted I-O helps deal with both these problems.
- Translation between binary and decimal notations.
- Translation between binary and richer symbol sets.

Data Type Formats

A value's format depends on the value's type.
- Integers have the format -?[0-9]+.
- Floating-point numbers have a complicated format.
Space characters are not part of any value format.
- Initial space characters are skipped.
- Trailing space characters end the value.
- This is true for characters and strings too.
The Boolean value true has format 1; false has format 0.
- This can be changed, however.

Formatted I-O Operators

The binary stream extraction operator >> performs formatted input from a stream.
```
istream >> variable
```
The binary stream insertion operator << performs formatted output to a stream.
```
ostream << value
```
This is a convention; extraction and insertion can be rewritten to do unformatted I-O.
The value of the extraction or insertion expression is the stream being read or written.
- This allows cascaded operators.
```
istream >> x >> y

ostream << "y = " << y << "\n"
```

Stream Manipulators

How do you output a hexadecimal number?
- The default is to output decimal numbers.
Stream manipulators are functions that influence the way streams operate.
- They influence formatting mostly, but can have other effects.
You are probably familiar with the endl and perhaps the flush manipulators.

Sticky vs. Non-Sticky Stream Manipulators

A sticky stream manipulator permanently change stream behavior.
- Permanently until the next change, that is.
- The hex manipulator sets the base to hexadecimal.
```
std::cout << 18 << std::hex << ' ' 
          << 19 << ' ' << 20
```
  produces
```
18 13 14
```
A non-sticky stream manipulator only effects the stream for the next value.
- The setw() manipulator sets the field width for the next value read or written.
```
cout << 3 << std::setw(4) << 4 << 5
```
  produces
```
3   45
```
Remembering which manipulator is which is a pain.

File Streams

A stream can be attached to many data sources, files for example.
Streams that attach to files are known as fstreams.
- A file istream is an ifstream.
- A file ostream is an ofstream.
- A file iostream is an fstream.
- Use the <fstream> header for them all.
The .close() member function dis-associates a stream from a file.
- This is called in the destructor, but call it explicitly anyway.
- Recover resources early.
- Demonstrate you know what you're doing.
The .is_open() member predicate determines if an association exists.

Opening File Streams

fs.open(fname) associates file stream fs and the file with the name fname using the default modes.
- For ifstreams, the default mode is reading.
- For ofstreams, the default mode is writing.
- For fstreams, the default mode is reading and writing.
fs.open(fname, modes) uses the modes modes instead of the default modes.
- Defined modes are
  .
  
  in open for reading
  
  out open for writing
  
  app writes append
  
  ate start at the eos position
  
  trunc empty the file
  
  binary do not modify characters
- Not all mode combinations are allowed.

String Streams

A stream attached to a string is a string stream.
- An input string stream is an istringstream.
- An output string stream is an ostringstream.
- An input-output string stream is a stringstream.
- All are defined in <sstream>.
- Don't use <strstream>; it's deprecated.
The ss.str() member function returns the string associated with the string stream ss.
The ss.str(str) member function sets the string associated with the string stream ss to the string str.
- The string stream constructors can also do this.
```
istringstream is("hello");
```
  is the same as
```
istringstream is;
is.str("hello");
```

Stream Positions

There are actually two stream pointers.
- One for reading (getting) and one for writing (putting).
The tell functions return the stream pointer's position.
- tellp() for write pointers and tellg() for read pointers.
The seek functions reposition the stream pointer.
- seekp() for write pointers and seekg() for read pointers.
The stream position type is complicated.
- But it's not an integer.
- You can't tell file size by subtracting positions.

Points to Remember

Streams can be distinguished by element type, I-O operation, and source.
Basic stream I-O moves data elements into or out of a stream.
I-O operations put streams in various states.
- They are implementation dependent and sticky.
Understand the end-of-stream condition.
- Do you read before or after the test?
Stream insertion and extraction provide formatted IO.
- Know the data-type formats.
Stream manipulators diddle with stream behavior.
- They can be tricky though (sticky vs. non-sticky).
Streams can be fed from many sources.
- Two common ones are files and strings.

This page last modified on 6 May 2004.

	`char`	`wchar_t`
input	`<istream>`	`<wistream>`
output	`<ostream>`	`<wostream>`
both	`<iostream>`	`<wiostream>`

`in`	open for reading
`out`	open for writing
`app`	writes append
`ate`	start at the eos position
`trunc`	empty the file
`binary`	do not modify characters