Previous fileTop of DocumentContentsIndex pageNext file
Apache C++ Standard Library User's Guide

2.3 Stream Iterators

Stream iterators are used to access an existing input or output stream using iterator operations. An input stream iterator permits an input stream to be read using iterator operations. Similarly, an output stream iterator writes to an output stream when iterator operations are executed.

2.3.1 Input Stream Iterators

As we noted in the discussion of input iterators, the C++ Standard Library provides a mechanism for turning an input stream into an input iterator through the template <class T, class charT, class Traits, class Distance> std::istream_iterator . When declared, the four template arguments are the element type, the stream character type, the character traits type, and a type that measures the distance between elements. The latter two default to std::char_traits<charT > and std::ptrdiff_t. The default is almost always the appropriate behavior. The single argument provided to the constructor for an istream_iterator is the stream to be accessed. Each time that operator++() is invoked on an input stream iterator, a new value from the stream is read using operator>>() and stored. This value is then available through the use of the dereference operator operator*(). The value constructed by istream_iterator when no arguments are provided to the constructor can be used as an ending iterator value. For example, the following code finds the first value 7 in a file of integer values:

The element denoted by an iterator for an input stream is valid only until the next element in the stream is requested. Also, since an input stream iterator is an input iterator, elements can only be accessed, not modified by assignment. Finally, elements can be accessed only once, and only in a forward moving direction.

2.3.2 Output Stream Iterators

The output stream iterator mechanism is analogous to the input stream iterator. Each time a value is assigned to the iterator, it is written on the associated output stream using operator>>(). To create an output stream iterator, you must specify the associated output stream as an argument with the constructor. Values written to the output stream must recognize the stream >> operation. An optional second argument to the constructor is a string used as a separator between each pair of values. For example, the following code copies all the values from a vector into the standard output, and separates each value by a space:

Simple file transformation algorithms can be created by combining input and output stream iterators and the various algorithms provided by the C++ Standard Library. The following short program reads a file of integers from the standard input, removes all occurrences of the value 7, and copies the remainder to the standard output, separating each value by a new line:

Previous fileTop of DocumentContentsIndex pageNext file