Correctly reload operator << in Boost.Log

Question

The Boost.Log documentation says that

Note

The library uses the basic_formatting_ostream stream basic_formatting_ostream to format records, so when setting the formatting for attribute values, operator<< rules should use basic_formatting_ostream instead of std::ostream .

However, in all the documentation, all I see is operator << overloading on std::ostream , not basic_formatting_ostream in the sample code. For example, see Overloading for the severity_level custom type here .

According to my tests, overloads on std::ostream and basic_formatting_ostream worked fine. So, I wonder what are the benefits of overloading on one, and not on the other.

Answer 1

There is no problem with overloading only operator << (std::ostream&, ...) , since formatting_ostream has

 template< typename CharT, typename TraitsT, typename AllocatorT, typename T > inline basic_formatting_ostream< CharT, TraitsT, AllocatorT >& operator<< (basic_formatting_ostream< CharT, TraitsT, AllocatorT >& strm, T const& value) { strm.stream() << value; return strm; } 

where stream() returns std::ostream& . If you overload operator << using first the arg formatting_ostream , it can only be used with boost::log , if you reboot to std::ostream& , then it can be used to boost::log and to the other terminal.

Quote from the header file:

  * This stream wrapper is used by the library for log record formatting. It implements the standard string stream interface * with a few differences: * * \li It does not derive from standard types <tt>std::basic_ostream</tt>, <tt>std::basic_ios</tt> and <tt>std::ios_base</tt>, * although it tries to implement their interfaces closely. There are a few small differences, mostly regarding <tt>rdbuf</tt> * and <tt>str</tt> signatures, as well as the supported insertion operator overloads. The actual wrapped stream can be accessed * through the <tt>stream</tt> methods. * \li By default, \c bool values are formatted using alphabetical representation rather than numeric. * \li The stream supports writing strings of character types different from the stream character type. The stream will perform * character code conversion as needed using the imbued locale. * \li The stream operates on an external string object rather than on the embedded one. The string can be attached or detached * from the stream dynamically. * * Although <tt>basic_formatting_ostream</tt> does not derive from <tt>std::basic_ostream</tt>, users are not required to add * special overloads of \c operator<< for it since the stream will by default reuse the operators for <tt>std::basic_ostream</tt>. * However, one can define special overloads of \c operator<< for <tt>basic_formatting_ostream</tt> if a certain type needs * special formatting when output to log. 

Answer 2

If you overload only operator<<(std::ostream) , it will work for each stream, including its basic_formatting_ostream . If you overload only operator<<(basic_formatting_ostream) , it will only work for output to this type of stream.

However, you may want to overload as , for example, if you want to provide other or more information to the log (for example, the address of an object).