## Class template basic_formatting_ostream

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

## Synopsis

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

    template<typename CharT, typename TraitsT, typename AllocatorT>
    class basic_formatting_ostream {
    public:
      // 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:
        // construct/copy/destruct
        explicit sentry(basic_formatting_ostream &);
        sentry(sentry const &);
        sentry & operator=(sentry const &);

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

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

      // 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<<(const void *);
      basic_formatting_ostream &
      operator<<(std::basic_streambuf< char_type, traits_type > *);

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

      // private member functions
      void init_stream();
      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;
    };

## Description

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.

   Postconditions: | `!*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.

   Parameters:

   `str` | The string buffer to attach.

   Postconditions: | `!*this == false`

3.     basic_formatting_ostream(basic_formatting_ostream const & that);

   Copy constructor (closed)

4.     basic_formatting_ostream & operator=(basic_formatting_ostream const & that);

   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.

   Parameters:

   `str` | 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;

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

4.     ostream_type & stream();

   Returns: | Reference to the wrapped stream

5.     ostream_type const & stream() const;

   Returns: | 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<<(const void * value);

74.     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` private member functions

1.     void init_stream();

2.     basic_formatting_ostream &
       formatted_write(const char_type * p, std::streamsize size);

3.     template<typename OtherCharT>
         basic_formatting_ostream &
         formatted_write(const OtherCharT * p, std::streamsize size);

4.     void aligned_write(const char_type * p, std::streamsize size);

5.     template<typename OtherCharT>
         void aligned_write(const OtherCharT * p, std::streamsize size);