An Enhanced ostream_iterator

A Clash of Design Principles?

The constructors of stlsoft::ostream_iterator break an important guideline of consistency between overloads and default arguments. The guideline requires that overloads should behave as if they were implemented as one constructor with a number of default arguments. Additional arguments, which refine the behavior/state requested of the function, are stacked on the end.

Guideline - An overload that provides additional parameters should not change the sequence of parameters with respect to the overridden method.

However, the third overloaded constructor of stlsoft::ostream_iterator specifies its refinement in the middle of the arguments. This is a consequence of applying the Principle of Least Surprise: A user will expect to specify a prefix before a suffix. Doing it the other way would result in client code such as the following:

std::cout << "Header Files:" << std::endl;
std::copy(headers.begin(), headers.end()
    , stlsoft::ostream_iterator<srchseq_t::value_type>(std::cout
                          , "\n","\t"));

This is actually a conflict between levels of discoverability. When viewing the class (template) in isolation, a second overload of (..., suffix, prefix) is probably more discoverable. But when viewed in action, the overload of (..., prefix, suffix) is definitely more discoverable. Given that, I feel that the result is worth transgressing the guideline and have opted for the latter. But it's an equivocal point, to be sure. You may see it differently.

Defining Stream Insertion Operators

You may wonder why this code works as well as it does, specifically why recls::stl:: basic_search_sequence<>::value_type is compatible with ostream_iterator. The reason is that ostream_iterator can work with any type for which a stream insertion operator is defined.

One way we could have implemented this would be as shown in Listing Six. Note that recls::stl::basic_search_sequence<>::value_type is actually the class template recls::stl::basic_search_sequence_value_type<>, whose name is another win for succinctness. (Thankfully, you never need to specify it in client code.)

Listing Six: Stream Insertion Operators

namespace recls::stl
{ 
 std::basic_ostream<char>&
  operator <<(std::basic_ostream<char>&           stm
       , basic_search_sequence_value_type<char, . . .>& v)
 { 
  return stm << v.get_path();
 } 
 std::basic_ostream<wchar_t>&
  operator <<(std::basic_ostream<wchar_t>&           stm
       , basic_search_sequence_value_type<wchar_t, . . .>& v)
 { 
  return stm << v.get_path();
 } 
} // namespace recls::stl

However, there are three problems with this code. First, we've got two functions doing much the same thing. Second, we've had to explicitly choose the traits type that will be supported with basic_search_sequence_value_type. Third, we've assumed that the stream will be derived from std::basic_ostream. A better alternative, which addresses all three problems, is to define the operator as a function template, as shown next. (I separated the return from the insertion, just in case someone wrote an inserter and forgot to provide the expected return type: a mutable [non-const] reference to the stream.)

template<typename S, typename C, typename T>
S& operator <<(S& s, basic_search_sequence_value_type<C, T> const& v)
{ 
 s << v.get_path();
 return s;
} 

This can handle any traits type with which basic_search_sequence may be specialized and works with any stream type that can insert specializations of std::basic_string (the default string type of the recls/STL mapping). And with one additional little flourish—a string access shim, of course—we can make it compatible with any stream type that understands C-style strings.

template<typename S, typename C, typename T>
S& operator <<(S& s, basic_search_sequence_value_type<C, T> const& v)
{ 
 s << stlsoft::c_str_ptr(v.get_path()));
 return s;
} 

Now you can stream to std::cout or even, should you so wish, to an instance of MFC's CArchive!

Implement generic insertion operators.

Summary

We've examined the std::ostream_iterator component and shown how, with relatively little effort, we can enhance its design to support the principles of Composition, Diversity, and Modularity. And, although we've willingly (but advisedly) transgressed an important C++ design principle, the component also supports the Principle of Least Surprise.

Matthew Wilson is a software development consultant for Synesis Software, and creator of the STLSoft libraries. Matthew can be contacted via http://www.synesis.com.au/. This article was excerpted from his book Extended STL, Volume 1 (ISBN 0321305507). Copyright (c) 2007 Addison Wesley Professional. All rights reserved.