N4257
Revision of N4066
2014-11-04
Mike Spertus, Symantec
mike_spertus@symantec.com
Nathan Wilson
nwilson20@gmail.com

Delimited iterators (Rev. 4)

It is extremely tempting to use ostream_iterator to, say, print a vector like: vector<int> v = {1, 4, 6}; cout << "("; copy(v.begin(), v.end(), ostream_iterator<int>(cout, ", ")); cout << ")"; // Oops! Prints (1, 4, 6, )

The problem is that the “delimiter” in the ostream_iterator constructor call is better described as a suffix than a delimiter.

Proposal

We propose a new ostream_joiner class that acts like ostream_iterator except that the delimiter is only placed between output elements: vector<int> v = {1, 4, 6}; cout << "("; copy(v.begin(), v.end(), std::make_ostream_joiner(cout, ", ")); cout << ")"; // Prints (1, 4, 6) as desired

Discussion

In the LEWG discussion of this proposal, a delimiter style such as prefix, infix, and suffix was presented.

• Since ostream_iterator already achieves a suffix delimiter style, the authors have removed this support in favour of the infix style defined in the class. We have also changed the use of const char* as the delimiter for basic_string<charT, traits>.

In the LEWG discussion of N3581 in Issaquah, it was pointed out that the interactions of this proposal were unexpectedly subtle, so the authors wish to discuss the design decisions in more detail.

• As pointed out in LEWG, output iterators can be defined as having void value type (§24.4.1p1), so the type being iterated need not be specified. It is apparently included in ostream_iterator for stylistic reasons only. Since brevity is of the essence in most uses of convenience classes such as this, we choose to omit the value type from ostream_joiner.
• Since we are changing template parameters, we reject Option 1 from N3581(add functionality to ostream_iterator instead of creating a new class) and create a new class instead.
• Since ostream_joiner is necessarily stateful and iterators are CopyConstructible and CopyAssignable, (§24.2.2p2), we need to consider what happens when ostream_joiners are copied. According to §24.2.4p2, “Assignment through the same value of the iterator happens only once.” (Emphasis in the original). At Issaquah, this was interpreted as meaning that writing to one copy of an output iterator invalidates writing through the original output iterator. This conveniently means that the ostream_joiner can store whether we are outputting the first element as a member, without the need for undesirable shared state (although it is not prohibited).
• Another possible variant would be to have a separate prefix, infix, and suffix to the list. copy(v.begin(), v.end(), std::ostream_joiner(cout, {"(", ", ", ")"})); On the one hand, this may be gilding the lily. On the other hand, most of the uses we have run into would leverage this and those that don't could use the simpler notation, and it obviates the need for the annoying delimiter_style enum.
• We provide a make_ostream_joiner function to simplify the deduction of template parameters as suggested by LEWG.
• If Template parameter deduction for constructors is eventually adopted, we will be able to dispense with the make_ prefix for notation that will be more concise without sacrificing clarity:copy(v.begin(), v.end(), std::ostream_joiner(cout, ", "));

Implementation

Wording

//24.6, stream iterators:
template <class T, class charT = char, class traits = char_traits<charT>,
    class Distance = ptrdiff_t>
class istream_iterator;
template <class T, class charT, class traits, class Distance>
  bool operator==(const istream_iterator&;t'T,charT,traits,Distance>& x,
          const istream_iterator<T,charT,traits,Distance>& y);
template <class T, class charT, class traits, class Distance>
  bool operator!=(const istream_iterator<T,charT,traits,Distance>& x,
          const istream_iterator<T,charT,traits,Distance>& y);
          
template <class charT = char, class traits = char_traits<charT> >
    class ostream_iterator;
template <class DelimT, class charT = char, class traits = char_traits<charT> >
    class ostream_joiner;
template <class charT, class traits, class DelimT>
  ostream_joiner<decay_t<DelimT>, charT, traits> make_ostream_joiner(basic_ostream<charT, traits>& os, DelimT&& delimiter);
template<class charT, class traits = char_traits<charT> >
class istreambuf_iterator;

24.6.x     Class template ostream_joiner                        [ostream.joiner]

ostream_joiner writes (using operator<<) successive elements onto the output stream from which it was constructed. The delimiter that it was constructed with is written to the stream between every two Ts that are written. It is not possible to get a value out of the output iterator. Its only use is as an output iterator in situations like

while (first != last)
  *result++ = *first++;

ostream_joiner is defined as 
namespace std {
  template <class DelimT, class charT = char, class traits = char_traits<charT> >
  class ostream_joiner {
  public:
    typedef charT char_type;
    typedef traits traits_type;
    typedef basic_ostream<charT,traits> ostream_type;
    typedef output_iterator_tag iterator_category;
    typedef void value_type;
    typedef void difference_type;
    typedef void pointer;
    typedef void reference;

    ostream_joiner(ostream_type& s, DelimT&& delimiter);
    ostream_joiner(ostream_type& s, const DelimT& delimiter);
    template<typename T>
    ostream_joiner<DelimT, charT,traits>& operator=(const T& value);
    ostream_joiner<DelimT, charT,traits>& operator*();
    ostream_joiner<DelimT, charT,traits>& operator++();
    ostream_joiner<DelimT, charT,traits>& operator++(int);
  private:
    basic_ostream<charT,traits>* out_stream; // exposition only
    DelimT delim; // exposition only
    bool first_element; // exposition only
  };
}

24.6.x.1     ostream_joiner constructor              [ostream.joiner.cons]

ostream_joiner(ostream_type& s, const DelimT& delimiter);

Effects: Initializes out_stream with &s, delim with delimiter, and first_element with true.

ostream_joiner(ostream_type& s, DelimT&& delimiter);

Effects: Initializes out_stream with &s, delim with move(delimiter), and first_element with true.

24.6.x.2     ostream_joiner operations              [ostream.joiner.ops]

template<typename T> ostream_joiner<DelimT, charT, traits>& operator=(const T& value);

Effects:

if (!first_element)
   *out_stream << delim;
first_element = false;
*out_stream << value;
return (*this);

ostream_joiner<DelimT, charT, traits>& operator*();

Returns: *this

ostream_joiner<DelimT, charT, traits>& operator++();
ostream_joiner<DelimT, charT, traits>& operator++(int);

Returns: *this

24.6.x.3     ostream_joiner creation function              [ostream.joiner.creation]

template <class charT, class traits, class DelimT>
  ostream_joiner<decay_t<DelimT>, charT, traits> make_ostream_joiner(basic_ostream<charT, traits>& os, DelimT&& delimiter);
    
Returns: ostream_joiner<decay_t<DelimT>, charT, traits>(os, forward<DelimT>(delimiter));