Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards


Class template basic_formatting_ostream

boost::log::basic_formatting_ostream — Stream for log records formatting.


// In header: <boost/log/utility/formatting_ostream.hpp>

template<typename CharT, typename TraitsT, typename AllocatorT> 
class basic_formatting_ostream {
  // types
  typedef CharT                                        char_type;       // Character type. 
  typedef TraitsT                                      traits_type;     // Character traits. 
  typedef AllocatorT                                   allocator_type;  // Memory allocator. 
  typedef unspecified                                  streambuf_type;  // Stream buffer type. 
  typedef streambuf_type::string_type                  string_type;     // Target string type. 
  typedef std::basic_ostream< char_type, traits_type > ostream_type;    // Stream type. 
  typedef ostream_type::pos_type                       pos_type;        // Stream position type. 
  typedef ostream_type::off_type                       off_type;        // Stream offset type. 
  typedef ostream_type::int_type                       int_type;        // Integer type for characters. 
  typedef ostream_type::failure                        failure;       
  typedef ostream_type::fmtflags                       fmtflags;      
  typedef ostream_type::iostate                        iostate;       
  typedef ostream_type::openmode                       openmode;      
  typedef ostream_type::seekdir                        seekdir;       
  typedef ostream_type::Init                           Init;          
  typedef ostream_type::event                          event;         
  typedef ostream_type::event_callback                 event_callback;

  // member classes/structs/unions

  class sentry : public sentry {
    // construct/copy/destruct
    explicit sentry(basic_formatting_ostream &);
    sentry(sentry const &) = delete;
    sentry & operator=(sentry const &) = delete;

    // public member functions
    explicit operator bool() const;
    bool operator!() const;

  // construct/copy/destruct
  explicit basic_formatting_ostream(string_type &);
  basic_formatting_ostream(basic_formatting_ostream const &) = delete;
  basic_formatting_ostream & 
  operator=(basic_formatting_ostream const &) = delete;

  // public member functions
  void attach(string_type &);
  void detach();
  string_type const & str() const;
  ostream_type & stream();
  ostream_type const & stream() const;
  fmtflags flags() const;
  fmtflags flags(fmtflags);
  fmtflags setf(fmtflags);
  fmtflags setf(fmtflags, fmtflags);
  void unsetf(fmtflags);
  std::streamsize precision() const;
  std::streamsize precision(std::streamsize);
  std::streamsize width() const;
  std::streamsize width(std::streamsize);
  std::locale getloc() const;
  std::locale imbue(std::locale const &);
  long & iword(int);
  void *& pword(int);
  void register_callback(event_callback, int);
  explicit operator bool() const;
  bool operator!() const;
  iostate rdstate() const;
  void clear(iostate = goodbit);
  void setstate(iostate);
  bool good() const;
  bool eof() const;
  bool fail() const;
  bool bad() const;
  iostate exceptions() const;
  void exceptions(iostate);
  ostream_type * tie() const;
  ostream_type * tie(ostream_type *);
  streambuf_type * rdbuf() const;
  basic_formatting_ostream & 
  copyfmt(std::basic_ios< char_type, traits_type > &);
  basic_formatting_ostream & copyfmt(basic_formatting_ostream &);
  char_type fill() const;
  char_type fill(char_type);
  char narrow(char_type, char) const;
  char_type widen(char) const;
  basic_formatting_ostream & flush();
  pos_type tellp();
  basic_formatting_ostream & seekp(pos_type);
  basic_formatting_ostream & seekp(off_type, std::ios_base::seekdir);
  basic_formatting_ostream & put(char_type);
  template<typename OtherCharT> unspecified put(OtherCharT);
  basic_formatting_ostream & write(const char_type *, std::streamsize);
  template<typename OtherCharT> 
    unspecified write(const OtherCharT *, std::streamsize);
  basic_formatting_ostream & operator<<(ios_base_manip);
  basic_formatting_ostream & operator<<(basic_ios_manip);
  basic_formatting_ostream & operator<<(stream_manip);
  basic_formatting_ostream & operator<<(char);
  basic_formatting_ostream & operator<<(const char *);
  basic_formatting_ostream & operator<<(wchar_t);
  basic_formatting_ostream & operator<<(const wchar_t *);
  basic_formatting_ostream & operator<<(char16_t);
  basic_formatting_ostream & operator<<(const char16_t *);
  basic_formatting_ostream & operator<<(char32_t);
  basic_formatting_ostream & operator<<(const char32_t *);
  basic_formatting_ostream & operator<<(bool);
  basic_formatting_ostream & operator<<(signed char);
  basic_formatting_ostream & operator<<(unsigned char);
  basic_formatting_ostream & operator<<(short);
  basic_formatting_ostream & operator<<(unsigned short);
  basic_formatting_ostream & operator<<(int);
  basic_formatting_ostream & operator<<(unsigned int);
  basic_formatting_ostream & operator<<(long);
  basic_formatting_ostream & operator<<(unsigned long);
  basic_formatting_ostream & operator<<(long long);
  basic_formatting_ostream & operator<<(unsigned long long);
  basic_formatting_ostream & operator<<(float);
  basic_formatting_ostream & operator<<(double);
  basic_formatting_ostream & operator<<(long double);
  basic_formatting_ostream & 
  operator<<(std::basic_streambuf< char_type, traits_type > *);

  // public static functions
  static int xalloc();
  static bool sync_with_stdio(bool = true);

  // protected member functions
  void init_stream();

  // private member functions
  basic_formatting_ostream & 
  formatted_write(const char_type *, std::streamsize);
  template<typename OtherCharT> 
    basic_formatting_ostream & 
    formatted_write(const OtherCharT *, std::streamsize);
  void aligned_write(const char_type *, std::streamsize);
  template<typename OtherCharT> 
    void aligned_write(const OtherCharT *, std::streamsize);

  // public data members
  static constexpr fmtflags boolalpha;
  static constexpr fmtflags dec;
  static constexpr fmtflags fixed;
  static constexpr fmtflags hex;
  static constexpr fmtflags internal;
  static constexpr fmtflags left;
  static constexpr fmtflags oct;
  static constexpr fmtflags right;
  static constexpr fmtflags scientific;
  static constexpr fmtflags showbase;
  static constexpr fmtflags showpoint;
  static constexpr fmtflags skipws;
  static constexpr fmtflags unitbuf;
  static constexpr fmtflags uppercase;
  static constexpr fmtflags adjustfield;
  static constexpr fmtflags basefield;
  static constexpr fmtflags floatfield;
  static constexpr iostate badbit;
  static constexpr iostate eofbit;
  static constexpr iostate failbit;
  static constexpr iostate goodbit;
  static constexpr openmode app;
  static constexpr openmode ate;
  static constexpr openmode binary;
  static constexpr openmode in;
  static constexpr openmode out;
  static constexpr openmode trunc;
  static constexpr seekdir beg;
  static constexpr seekdir cur;
  static constexpr seekdir end;
  static constexpr event erase_event;
  static constexpr event imbue_event;
  static constexpr event copyfmt_event;


Stream wrapper for log records formatting.

This stream wrapper is used by the library for log record formatting. It implements the standard string stream interface with a few differences:

  • It does not derive from standard types std::basic_ostream, std::basic_ios and std::ios_base, although it tries to implement their interfaces closely. There are a few small differences, mostly regarding rdbuf and str signatures, as well as the supported insertion operator overloads. The actual wrapped stream can be accessed through the stream methods.

  • By default, bool values are formatted using alphabetical representation rather than numeric.

  • 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.

  • 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 basic_formatting_ostream does not derive from std::basic_ostream, users are not required to add special overloads of operator<< for it since the stream will by default reuse the operators for std::basic_ostream. However, one can define special overloads of operator<< for basic_formatting_ostream if a certain type needs special formatting when output to log.

basic_formatting_ostream public construct/copy/destruct

  1. basic_formatting_ostream();

    Default constructor. Creates an empty record that is equivalent to the invalid record handle. The stream capability is not available after construction.


    !*this == true

  2. explicit basic_formatting_ostream(string_type & str);

    Initializing constructor. Attaches the string to the constructed stream. The string will be used to store the formatted characters.



    The string buffer to attach.


    !*this == false

  3. basic_formatting_ostream(basic_formatting_ostream const & that) = delete;
    Copy constructor (closed)
  4. basic_formatting_ostream & 
    operator=(basic_formatting_ostream const & that) = delete;
    Assignment (closed)
  5. ~basic_formatting_ostream();

    Destructor. Destroys the record, releases any sinks and attribute values that were involved in processing this record.

basic_formatting_ostream public member functions

  1. void attach(string_type & str);

    Attaches the stream to the string. The string will be used to store the formatted characters.



    The string buffer to attach.

  2. void detach();

    Detaches the stream from the string. Any buffered data is flushed to the string.

  3. string_type const & str() const;


    Reference to the attached string. The string must be attached before calling this method.

  4. ostream_type & stream();


    Reference to the wrapped stream

  5. ostream_type const & stream() const;


    Reference to the wrapped stream

  6. fmtflags flags() const;
  7. fmtflags flags(fmtflags f);
  8. fmtflags setf(fmtflags f);
  9. fmtflags setf(fmtflags f, fmtflags mask);
  10. void unsetf(fmtflags f);
  11. std::streamsize precision() const;
  12. std::streamsize precision(std::streamsize p);
  13. std::streamsize width() const;
  14. std::streamsize width(std::streamsize w);
  15. std::locale getloc() const;
  16. std::locale imbue(std::locale const & loc);
  17. long & iword(int index);
  18. void *& pword(int index);
  19. void register_callback(event_callback fn, int index);
  20. explicit operator bool() const;
  21. bool operator!() const;
  22. iostate rdstate() const;
  23. void clear(iostate state = goodbit);
  24. void setstate(iostate state);
  25. bool good() const;
  26. bool eof() const;
  27. bool fail() const;
  28. bool bad() const;
  29. iostate exceptions() const;
  30. void exceptions(iostate s);
  31. ostream_type * tie() const;
  32. ostream_type * tie(ostream_type * strm);
  33. streambuf_type * rdbuf() const;
  34. basic_formatting_ostream & 
    copyfmt(std::basic_ios< char_type, traits_type > & rhs);
  35. basic_formatting_ostream & copyfmt(basic_formatting_ostream & rhs);
  36. char_type fill() const;
  37. char_type fill(char_type ch);
  38. char narrow(char_type ch, char def) const;
  39. char_type widen(char ch) const;
  40. basic_formatting_ostream & flush();
  41. pos_type tellp();
  42. basic_formatting_ostream & seekp(pos_type pos);
  43. basic_formatting_ostream & seekp(off_type off, std::ios_base::seekdir dir);
  44. basic_formatting_ostream & put(char_type c);
  45. template<typename OtherCharT> unspecified put(OtherCharT c);
  46. basic_formatting_ostream & write(const char_type * p, std::streamsize size);
  47. template<typename OtherCharT> 
      unspecified write(const OtherCharT * p, std::streamsize size);
  48. basic_formatting_ostream & operator<<(ios_base_manip manip);
  49. basic_formatting_ostream & operator<<(basic_ios_manip manip);
  50. basic_formatting_ostream & operator<<(stream_manip manip);
  51. basic_formatting_ostream & operator<<(char c);
  52. basic_formatting_ostream & operator<<(const char * p);
  53. basic_formatting_ostream & operator<<(wchar_t c);
  54. basic_formatting_ostream & operator<<(const wchar_t * p);
  55. basic_formatting_ostream & operator<<(char16_t c);
  56. basic_formatting_ostream & operator<<(const char16_t * p);
  57. basic_formatting_ostream & operator<<(char32_t c);
  58. basic_formatting_ostream & operator<<(const char32_t * p);
  59. basic_formatting_ostream & operator<<(bool value);
  60. basic_formatting_ostream & operator<<(signed char value);
  61. basic_formatting_ostream & operator<<(unsigned char value);
  62. basic_formatting_ostream & operator<<(short value);
  63. basic_formatting_ostream & operator<<(unsigned short value);
  64. basic_formatting_ostream & operator<<(int value);
  65. basic_formatting_ostream & operator<<(unsigned int value);
  66. basic_formatting_ostream & operator<<(long value);
  67. basic_formatting_ostream & operator<<(unsigned long value);
  68. basic_formatting_ostream & operator<<(long long value);
  69. basic_formatting_ostream & operator<<(unsigned long long value);
  70. basic_formatting_ostream & operator<<(float value);
  71. basic_formatting_ostream & operator<<(double value);
  72. basic_formatting_ostream & operator<<(long double value);
  73. basic_formatting_ostream & 
    operator<<(std::basic_streambuf< char_type, traits_type > * buf);

basic_formatting_ostream public static functions

  1. static int xalloc();
  2. static bool sync_with_stdio(bool sync = true);

basic_formatting_ostream protected member functions

  1. void init_stream();

basic_formatting_ostream private member functions

  1. basic_formatting_ostream & 
    formatted_write(const char_type * p, std::streamsize size);
  2. template<typename OtherCharT> 
      basic_formatting_ostream & 
      formatted_write(const OtherCharT * p, std::streamsize size);
  3. void aligned_write(const char_type * p, std::streamsize size);
  4. template<typename OtherCharT> 
      void aligned_write(const OtherCharT * p, std::streamsize size);