third_party/boost/io/doc/ostream_joiner.adoc

////
Copyright 2019 Glen Joseph Fernandes
(glenjofe@gmail.com)

Distributed under the Boost Software License, Version 1.0.
(http://www.boost.org/LICENSE_1_0.txt)
////

# Delimited Iterators, <boost/io/ostream_joiner.hpp>
:toc:
:toc-title:
:idprefix:

## Description

The header `<boost/io/ostream_joiner.hpp>` provides the class template
`boost::io::ostream_joiner` which is an output iterator that writes objects to
a `std::basic_ostream` separated by a delimiter. It is an implementation of
the Library Fundamentals TS `std::ostream_joiner` which supports {cpp}03 and
higher.

## Example

The following program writes the contents of a vector to standard output, with
each element separated by a comma.

```
#include <boost/io/ostream_joiner.hpp>
#include <algorithm>
#include <iostream>
#include <vector>

int main()
{
    std::vector<int> v;
    v.push_back(2);
    v.push_back(4);
    v.push_back(6);
    v.push_back(8);
    std::copy(v.begin(), v.end(), boost::make_ostream_joiner(std::cout, ','));
}
```

## Reference

### Header Synopsis

```
namespace boost {
namespace io {

template<class Delim, class Char = char,
    class Traits = std::char_traits<Char> >
class ostream_joiner {
public:
    typedef Char char_type;
    typedef Traits traits_type;
    typedef std::basic_ostream<Char, Traits> ostream_type;
    typedef std::output_iterator_tag iterator_category;
    typedef void value_type;
    typedef void difference_type;
    typedef void pointer;
    typedef void reference;

    ostream_joiner(ostream_type& output, const Delim& delim);
    ostream_joiner(ostream_type& output, Delim&& delim);

    template<class T>
    ostream_joiner& operator=(const T& value);

    ostream_joiner& operator*() noexcept;
    ostream_joiner& operator++() noexcept;
    ostream_joiner& operator++(int) noexcept;
};

template<class Char, class Traits, class Delim>
ostream_joiner<std::decay_t<Delim>, Char, Traits>
make_ostream_joiner(std::basic_ostream<Char, Traits>& output, Delim&& delim);

} // io
} // boost
```

### Constructors

```
ostream_joiner(ostream_type& output, const Delim& delim);
```

[.specification]
EFfects:: Initializes the stored reference to the stream with
`std::addressof(output)` and the stored delimiter with `delim`.

```
ostream_joiner(ostream_type& output, Delim&& delim);
```

[.specification]
EFfects:: Initializes the stored reference to the stream with
`std::addressof(output)` and the stored delimiter with `std::move(delim)`.

### Member functions

```
template<class T>
ostream_joiner& operator=(const T& value);
```

[.specification]
Effects:: If the is the first call to this member function, write the stored
delimiter to the stored stream reference. Writes `value` to the stored stream
reference.
Returns:: `*this`.

```
ostream_joiner& operator*() noexcept;
```
```
ostream_joiner& operator++() noexcept;
```
```
ostream_joiner& operator++(int) noexcept;
```

[.specification]
Returns:: `*this`.

### Free functions

```
template<class Char, class Traits, class Delim>
ostream_joiner<decay_t<Delim>, Char, Traits>
make_ostream_joiner(std::basic_ostream<Char, Traits>& output, Delim&& delim);
```

[.specification]
Returns:: `ostream_joiner<std::decay_t<Delim>, Char, Traits>(output,
std::forward<Delim>(delim))`.

## Acknowledgments

Glen Fernandes implemented `ostream_joiner` and `make_ostream_joiner`.