ostreambuf_iterator Class
The class template ostreambuf_iterator describes an output iterator object that writes successive character elements onto the output stream with the extraction operator>>. The ostreambuf_iterators differ from those of the ostream_iterator Class in having characters instead of a generic type at the type of object being inserted into the output stream.
Syntax
template <class CharType = char class Traits = char_traits <CharType>>
Parameters
CharType
The type that represents the character type for the ostreambuf_iterator. This argument is optional and the default value is char.
Traits
The type that represents the character type for the ostreambuf_iterator. This argument is optional and the default value is char_traits< CharType>.
Remarks
The ostreambuf_iterator class must satisfy the requirements for an output iterator. Algorithms can be written directly to output streams using an ostreambuf_iterator. The class provides a low-level stream iterator that allows access to the raw (unformatted) I/O stream in the form of characters and the ability to bypass the buffering and character translations associated with the high-level stream iterators.
Constructors
| Constructor | Description |
|---|---|
| ostreambuf_iterator | Constructs an ostreambuf_iterator that is initialized to write characters to the output stream. |
Typedefs
| Type name | Description |
|---|---|
| char_type | A type that provides for the character type of the ostreambuf_iterator. |
| ostream_type | A type that provides for the stream type of the ostream_iterator. |
| streambuf_type | A type that provides for the stream type of the ostreambuf_iterator. |
| traits_type | A type that provides for the character traits type of the ostream_iterator. |
Member functions
| Member function | Description |
|---|---|
| failed | Tests for failure of an insertion into the output stream buffer. |
Operators
| Operator | Description |
|---|---|
| operator* | Dereferencing operator used to implement the output iterator expression * i = x. |
| operator++ | A nonfunctional increment operator that returns an ostreambuf_iterator to the same object it addressed before the operation was called. |
| operator= | The operator inserts a character into the associated stream buffer. |
Requirements
Header: <iterator>
Namespace: std
ostreambuf_iterator::char_type
A type that provides for the character type of the ostreambuf_iterator.
typedef CharType char_type;
Remarks
The type is a synonym for the template parameter CharType.
Example
// ostreambuf_iterator_char_type.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
typedef ostreambuf_iterator<char>::char_type CHT1;
typedef ostreambuf_iterator<char>::traits_type CHTR1;
// ostreambuf_iterator for stream cout
// with new line delimiter:
ostreambuf_iterator< CHT1, CHTR1> charOutBuf ( cout );
// Standard iterator interface for writing
// elements to the output streambuf:
cout << "The characters written to the output stream\n"
<< " by charOutBuf are: ";
*charOutBuf = 'O';
charOutBuf++;
*charOutBuf = 'U';
charOutBuf++;
*charOutBuf = 'T';
charOutBuf++;
cout << "." << endl;
}
/* Output:
The characters written to the output stream
by charOutBuf are: OUT.
*/
ostreambuf_iterator::failed
Tests for failure of an insertion into the output stream buffer.
bool failed() const throw();
Return Value
true if no insertion into the output stream buffer has failed earlier; otherwise false.
Remarks
The member function returns true if, in any prior use of member operator=, the call to subf_-> sputc returned eof.
Example
// ostreambuf_iterator_failed.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
// ostreambuf_iterator for stream cout
ostreambuf_iterator<char> charOut ( cout );
*charOut = 'a';
charOut ++;
*charOut = 'b';
charOut ++;
*charOut = 'c';
cout << " are characters output individually." << endl;
bool b1 = charOut.failed ( );
if (b1)
cout << "At least one insertion failed." << endl;
else
cout << "No insertions failed." << endl;
}
/* Output:
abc are characters output individually.
No insertions failed.
*/
ostreambuf_iterator::operator*
A nonfunctional dereferencing operator used to implement the output iterator expression * i = x.
ostreambuf_iterator<CharType, Traits>& operator*();
Return Value
The ostreambuf iterator object.
Remarks
This operator functions only in the output iterator expression * i = x to output characters to stream buffer. Applied to an ostreambuf iterator, it returns the iterator; *iter returns iter,
Example
// ostreambuf_iterator_op_deref.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
// ostreambuf_iterator for stream cout
// with new line delimiter
ostreambuf_iterator<char> charOutBuf ( cout );
// Standard iterator interface for writing
// elements to the output stream
cout << "Elements written to output stream:" << endl;
*charOutBuf = 'O';
charOutBuf++; // no effect on iterator position
*charOutBuf = 'U';
*charOutBuf = 'T';
}
/* Output:
Elements written to output stream:
OUT
*/
ostreambuf_iterator::operator++
A nonfunctional increment operator that returns an ostream iterator to the same character it addressed before the operation was called.
ostreambuf_iterator<CharType, Traits>& operator++();
ostreambuf_iterator<CharType, Traits>& operator++(int);
Return Value
A reference to the character originally addressed or to an implementation-defined object that is convertible to ostreambuf_iterator< CharType, Traits>.
Remarks
The operator is used to implement the output iterator expression * i = x.
Example
// ostreambuf_iterator_op_incr.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
// ostreambuf_iterator for stream cout
// with new line delimiter
ostreambuf_iterator<char> charOutBuf ( cout );
// Standard iterator interface for writing
// elements to the output stream
cout << "Elements written to output stream:" << endl;
*charOutBuf = 'O';
charOutBuf++; // No effect on iterator position
*charOutBuf = 'U';
*charOutBuf = 'T';
}
/* Output:
Elements written to output stream:
OUT
*/
ostreambuf_iterator::operator=
The operator inserts a character into the associated stream buffer.
ostreambuf_iterator<CharType, Traits>& operator=(CharType _Char);
Parameters
_Char
The character to be inserted into the stream buffer.
Return Value
A reference to the character inserted into the stream buffer.
Remarks
Assignment operator used to implement the output iterator expression * i = x for writing to an output stream.
Example
// ostreambuf_iterator_op_assign.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
// ostreambuf_iterator for stream cout
// with new line delimiter
ostreambuf_iterator<char> charOutBuf ( cout );
// Standard iterator interface for writing
// elements to the output stream
cout << "Elements written to output stream:" << endl;
*charOutBuf = 'O';
charOutBuf++; // No effect on iterator position
*charOutBuf = 'U';
*charOutBuf = 'T';
}
/* Output:
Elements written to output stream:
OUT
*/
ostreambuf_iterator::ostreambuf_iterator
Constructs an ostreambuf_iterator that is initialized to write characters to the output stream.
ostreambuf_iterator(streambuf_type* strbuf) throw();
ostreambuf_iterator(ostream_type& Ostr) throw();
Parameters
strbuf
The output streambuf object used to initialize the output stream-buffer pointer.
Ostr
The output stream object used to initialize the output stream-buffer pointer.
Remarks
The first constructor initializes the output stream-buffer pointer with strbuf.
The second constructor initializes the output stream-buffer pointer with Ostr. rdbuf. The stored pointer must not be a null pointer.
Example
// ostreambuf_iteratorOstreambuf_iterator.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
// ostreambuf_iterator for stream cout
ostreambuf_iterator<char> charOut ( cout );
*charOut = 'O';
charOut ++;
*charOut = 'U';
charOut ++;
*charOut = 'T';
cout << " are characters output individually." << endl;
ostreambuf_iterator<char> strOut ( cout );
string str = "These characters are being written to the output stream.\n ";
copy ( str.begin ( ), str. end ( ), strOut );
}
/* Output:
OUT are characters output individually.
These characters are being written to the output stream.
*/
ostreambuf_iterator::ostream_type
A type that provides for the stream type of the ostream_iterator.
typedef basicOstream<CharType, Traits> ostream_type;
Remarks
The type is a synonym for basicOstream< CharType, Traits>
Example
See ostreambuf_iterator for an example of how to declare and use ostream_type.
ostreambuf_iterator::streambuf_type
A type that provides for the stream type of the ostreambuf_iterator.
typedef basic_streambuf<CharType, Traits> streambuf_type;
Remarks
The type is a synonym for basic_streambuf< CharType, Traits>, a stream class for I/O buffers that becomes streambuf when specialized to character type char.
Example
See ostreambuf_iterator for an example of how to declare and use streambuf_type.
ostreambuf_iterator::traits_type
A type that provides for the character traits type of the ostream_iterator.
typedef Traits traits_type;
Remarks
The type is a synonym for the template parameter Traits.
Example
// ostreambuf_iterator_traits_type.cpp
// compile with: /EHsc
#include <iterator>
#include <vector>
#include <iostream>
int main( )
{
using namespace std;
typedef ostreambuf_iterator<char>::char_type CHT1;
typedef ostreambuf_iterator<char>::traits_type CHTR1;
// ostreambuf_iterator for stream cout
// with new line delimiter:
ostreambuf_iterator< CHT1, CHTR1> charOutBuf ( cout );
// Standard iterator interface for writing
// elements to the output streambuf:
cout << "The characters written to the output stream\n"
<< " by charOutBuf are: ";
*charOutBuf = 'O';
charOutBuf++;
*charOutBuf = 'U';
charOutBuf++;
*charOutBuf = 'T';
charOutBuf++;
cout << "." << endl;
}
/* Output:
The characters written to the output stream
by charOutBuf are: OUT.
*/
See also
<iterator>
Thread Safety in the C++ Standard Library
C++ Standard Library Reference
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for