Apache C++ Standard Library Reference Guide

## ostreambuf_iterator

Library: Iterators

    ostreambuf_iterator  output_iterator

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Constructors
- Member Operators
- Public Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type failed() operator*() | operator++() operator=() ostreambuf_iterator() | ostream_type streambuf_type traits_type |

### Summary

Writes successive characters onto the stream buffer object from which it was constructed

### Synopsis

    #include <iterator>

    namespace std {
      template<class charT, class traits = char_traits<charT> >
      class ostreambuf_iterator;
    }

### Description

The class template ostreambuf_iterator writes successive characters onto the stream buffer object from which it was constructed. `operator=()` is used to write the characters. In case of failure, the member function `failed()` returns `true`.

### Interface

    namespace std {

      template<class charT, class traits = char_traits<charT> >
      class ostreambuf_iterator
        : public iterator <output_iterator_tag, void,
                           void, void, void>
      {
      public:

        typedef charT char_type;
        typedef traits traits_type;
        typedef basic_streambuf<charT, traits> streambuf_type;
        typedef basic_ostream<charT, traits> ostream_type;

        ostreambuf_iterator(ostream_type& s) throw();
        ostreambuf_iterator(streambuf_type *s) throw();
        ostreambuf_iterator& operator=(char_type c);

        ostreambuf_iterator& operator*();
        ostreambuf_iterator& operator++();
        ostreambuf_iterator operator++(int);

        bool failed( ) const throw();

      };
    }

### Member Types

    char_type

The type `char_type` is a synonym for the template parameter `charT`.

    ostream_type

The type `ostream_type` is a synonym for the type `basic_ostream<char_type, traits_type>`.

    streambuf_type

The type `streambuf_type` is a synonym for the type `basic_streambuf<char_type, traits_type>`.

    traits_type

The type `traits_type` is a synonym for the template parameter `traits`.

### Constructors

    ostreambuf_iterator(ostream_type& s) throw();

Constructs an ostreambuf_iterator that uses the basic_streambuf object pointed to by `s.rdbuf()`to output characters. If `s.rdbuf()` is a null pointer, calls to the member function `failed()` return `true`.

    ostreambuf_iterator(streambuf_type *s) throw();

Constructs an ostreambuf_iterator that uses the basic_streambuf object pointed to by `s` to output characters. If `s` is a null pointer, calls to the member function`failed()` return `true`.

### Member Operators

    ostreambuf_iterator&
    operator=(char_type c);

Inserts the character `c` into the output sequence of the attached stream buffer. If the operation fails, calls to the member function `failed()` return `true`.

    ostreambuf_iterator&
    operator++();

Returns `*this`.

    ostreambuf_iterator
    operator++(int);

Returns `*this`.

    ostreambuf_iterator
    operator*();

Returns `*this`.

### Public Member Functions

    bool
    failed() const
      throw();

Returns `true` if the iterator failed while inserting a character. Otherwise returns `false`.

### Example

    //
    //  ostreambuf_iterator.cpp
    //

    #include <iostream>   // for cout, endl
    #include <iterator>   // for istreambuf_iterator,
                          //     ostreambuf_iterator
    #include <fstream>    // for filebuf

    #include <stdio.h>    // for tmpnam and remove

    int main ( )
    {
        char namebuf [L_tmpnam];

        // create a temporary filename
        const char *fname = tmpnam (namebuf);

        if (!fname)
            return 1;

        // create a filebuf object
        std::filebuf buf;

        // open the file and link it to the filebuf object
        buf.open (fname, std::ios::in | std::ios::out |
                         std::ios::trunc);

        // create an ostreambuf_iterator and link it to
        // the filebuf object
        std::ostreambuf_iterator<char, std::char_traits<char> >
                                out_iter (&buf);

        // output into the file using the ostreambuf_iterator
        for (char i = 64; i < 127; i++)
            out_iter = i;

        // seek to the beginning of the file
        buf.pubseekpos(0);

        // create an istreambuf_iterator and link it to
        // the filebuf object
        std::istreambuf_iterator<char, std::char_traits<char> >
                                in_iter (&buf);

        // construct an end of stream iterator
        std::istreambuf_iterator<char, std::char_traits<char> >
                                end;

        std::cout << std::endl;

        // output the contents of the file
        while (!in_iter.equal (end))
            std::cout << *in_iter++;

        std::cout << std::endl;

        // remove temporary file
        remove (fname);

        return 0;
    }

    Program Output:

    @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~

### See Also

basic_streambuf, basic_ostream, istreambuf_iterator

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 24.5.4