.\" ident @(#)basic_ostream.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH basic_ostream 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2basic_ostream\fP, \f2ostream\fP, \f2wostream\fP \ - Assists in formatting and writing output to sequences controlled by a stream buffer. .SH SYNOPSIS .br #include .br template > .br class basic_ostream .br : virtual public basic_ios .SH DESCRIPTION The class basic_ostream defines member functions that assist in formatting and writing output to sequences controlled by a stream buffer. Two groups of member functions share common properties: the formatted output functions (or insertors) and the unformatted output functions. Both groups of functions insert characters by calling basic_streambuf member functions. They both begin by constructing an object of class basic_ostream::sentry and, if this object is in good state after construction, the function tries to perform the requested output. The \f2sentry\fP object performs exception-safe initialization, such as controlling the status of the stream or locking it in a multithread environment. Some formatted output functions generate the requested output by converting a value from some scalar to text form and inserting the converted text in the output sequence. The conversion behavior is directly depend on the locale object being imbued in the stream. .SH INTERFACE .br template > .br class basic_ostream .br :virtual public basic_ios { .br .br public: .br .RE .RS 1 typedef traits traits_type; .br typedef charT char_type; .br typedef typename traits::int_type int_type; .br typedef typename traits::pos_type pos_type; .br typedef typename traits::off_type off_type; .RE .RS 0 .RE .RS 1 typedef basic_ostream ostream_type; .br typedef basic_ios ios_type; .RE .RS 0 .RE .RS 1 explicit basic_ostream(basic_streambuf .RE .RS 24 *sb); .RE .RS 1 virtual ~basic_ostream(); .RE .RS 0 .br class sentry { .RE .RS 18 .RE .RS 1 public: .RE .RS 0 .RE .RS 4 explicit sentry(basic_ostream&); .RE .RS 5 ~sentry(); .RE .RS 4 operator bool (); .RE .RS 0 .RE .RS 2 }; .RE .RS 0 .RE .RS 1 ostream_type& operator<<(ostream_type& .RE .RS 26 (*pf)(ostream_type&)); .RE .RS 1 ostream_type& operator<<(ios_base& (*pf)(ios_base&)); .br ostream_type& operator<<(ios_type& (*pf)(ios_type&)); .RE .RS 4 .RE .RS 1 ostream_type& operator<<(bool n); .br ostream_type& operator<<(short n); .br ostream_type& operator<<(unsigned short n); .br ostream_type& operator<<(int n); .br ostream_type& operator<<(unsigned int n); .br ostream_type& operator<<(long n); .br ostream_type& operator<<(unsigned long n); .br ostream_type& operator<<(float f); .br ostream_type& operator<<(double f); .br ostream_type& operator<<(long double f); .RE .RS 0 .RE .RS 1 ostream_type& operator<<(const void *p); .RE .RS 5 .RE .RS 1 ostream_type& .RE .RS 9 operator<<(basic_streambuf &sb); .RE .RS 1 ostream_type& .RE .RS 9 operator<<(basic_streambuf *sb); .RE .RS 0 .RE .RS 1 ostream_type& put(char_type c); .br ostream_type& write(const char_type *s, streamsize n); .RE .RS 0 .RE .RS 1 ostream_type& flush(); .br .br pos_type tellp(); .br ostream_type& seekp(pos_type ); .br ostream_type& seekp(off_type , ios_base::seekdir ); .br .RE .RS 0 protected: .br .RE .RS 1 basic_ostream(); .RE .RS 0 .br }; .br .br .br //global character inserter functions .br .br template .br basic_ostream& .br operator<<(basic_ostream&, charT); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, char); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, char); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, signed char); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, unsigned char); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, const charT*); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, const char*); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, const char*); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, const signed char*); .br .br template .br basic_ostream& .br operator<<(basic_ostream&, .RE .RS 10 const unsigned char*); .RE .RS 0 .br template .br basic_ostream& .br endl(basic_ostream& os); .br .br template .br basic_ostream& .br ends(basic_ostream& os); .br .br template .br basic_ostream& .br flush(basic_ostream& os); .SH TYPES .br char_type .RE .RS 3 The type \f2char_type\fP is a synonym for the template parameter \f2charT\fP. .RE .br int_type .RE .RS 3 The type \f2int_type\fP is a synonym of type \f2traits::in_type\fP. .RE .br ios_type .RE .RS 3 The type \f2ios_type\fP is a synonym for \f2basic_ios\fP. .RE .br off_type .RE .RS 3 The type \f2off_type\fP is a synonym of type \f2traits::off_type\fP. .RE .br ostream .RE .RS 3 The type \f2ostream\fP is an instantiation of class \f2basic_ostream\fP on type \f2char\fP: \f2typedef basic_ostream ostream;\fP .RE .br ostream_type .RE .RS 3 The type \f2ostream_type\fP is a synonym for \f2basic_ostream\fP. .RE .br pos_type .RE .RS 3 The type \f2pos_type\fP is a synonym of type \f2traits::pos_type\fP. .RE .br traits_type .RE .RS 3 The type \f2traits_type\fP is a synonym for the template parameter \f2traits\fP. .RE .br wostream .RE .RS 3 The type \f2wostream\fP is an instantiation of class \f2basic_ostream\fP on type \f2wchar_t\fP: \f2typedef basic_ostream wostream;\fP .RE .SH CONSTRUCTORS .br explicit basic_ostream(basic_streambuf* sb); .RE .RS 3 Constructs an object of class \f2basic_ostream\fP, assigning initial values to the base class by calling \f2basic_ios::init(sb)\fP. .RE .SH DESTRUCTORS .br virtual ~basic_ostream(); .RE .RS 3 Destroys an object of class \f2basic_ostream\fP. .RE .SH SENTRY CLASSES .br explicit sentry(basic_ostream&); .RE .RS 3 Prepares for formatted or unformatted output. If the \f2basic_ios\fP member function \f2tie()\fP is not a null pointer, the function synchronizes the output sequence with any associated stream. If after any preparation is completed, the \f2basic_ios\fP member function \f2good()\fP is \f2true\fP, the sentry conversion function operator \f2bool()\fP returns \f2true\fP. Otherwise it returns \f2false\fP. In a multithread environment the sentry object constructor is responsible for locking the stream and the stream buffer associated with the stream. .RE .br ~sentry(); .RE .RS 3 Destroys an object of class \f2sentry\fP. If the \f2ios_base\fP member function \f2flags() & unitbuf == true\fP, then flushes the buffer. In a multithread environment the sentry object destructor is responsible for unlocking the stream and the stream buffer associated with the stream. .RE .br operator bool(); .RE .RS 3 If after any preparation is completed, the \f2ios_base\fP member function \f2good()\fP is \f2true\fP, the sentry conversion function operator \f2bool()\fP returns \f2true\fP, else it returns \f2false\fP. .RE .SH INSERTORS .br ostream_type& .br operator<<(ostream_type& (*pf) (ostream_type&)); .RE .RS 3 Calls \f2pf(*this)\fP, then returns \f2*this\fP. See, for example, the function signature \f2endl(basic_ostream&)\fP. .RE .br ostream_type& .br operator<<(ios_type& (*pf) (ios_type&)); .RE .RS 3 Calls \f2pf(*this)\fP, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(ios_base& (*pf) (ios_base&)); .RE .RS 3 Calls \f2pf(*this)\fP, then returns \f2*this\fP. See, for example, the function signature \f2dec(ios_base&)\fP. .RE .br ostream_type& .br operator<<(bool n); .RE .RS 3 Converts the boolean value \f2n\fP and outputs it into the \f2basic_ostream\fP object's buffer. If the \f2ios_base\fP member function \f2flag() & ios_base::boolalpha\fP is \f2false\fP it tries to write an integer value, which must be \f20\fP or \f21\fP. If the \f2boolalpha\fP flag is \f2true\fP, it writes characters according to the locale function \f2numpunct<>::truename()\fP or \f2numpunct<>::falsename()\fP. .RE .br ostream_type& .br operator<<(short n); .RE .RS 3 Converts the \f2signed short\fP integer \f2n\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(unsigned short n); .RE .RS 3 Converts the \f2unsigned short\fP integer \f2n\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(int n); .RE .RS 3 Converts the\f2 signed integer n\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(unsigned int n); .RE .RS 3 Converts the \f2unsigned integer n\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(long n); .RE .RS 3 Converts the \f2signed long\fP integer \f2n\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(unsigned long n); .RE .RS 3 Converts the un\f2signed long\fP integer n, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(float f); .RE .RS 3 Converts the \f2float f\fP and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(double f); .RE .RS 3 Converts the \f2double f\fP and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(long double f); .RE .RS 3 Converts the \f2long double f\fP and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(void *p); .RE .RS 3 Converts the \f2pointer p\fP, and outputs it into the stream buffer, then returns \f2*this\fP. .RE .br ostream_type& .br operator<<(basic_streambuf *sb); .RE .RS 3 If \f2sb\fP is null calls the \f2basic_ios\fP member function \f2setstate(badbit)\fP. Otherwise gets characters from \f2sb\fP and inserts them into the stream buffer until any of the following occurs: .RS .5i .HP .5i - An end-of-file on the input sequence. .HP .5i - A failure when inserting in the output sequence .HP .5i - An exception while getting a character from \f2sb\fP .RE If the function inserts no characters or if it stopped because an exception was thrown while extracting a character, it calls the \f2basic_ios\fP member function \f2setstate(failbit)\fP. If an exception was thrown while extracting a character, it is rethrown. .RE .br ostream_type& .br operator<<(basic_streambuf& sb); .RE .RS 3 Gets characters from \f2sb\fP and inserts them into the stream buffer until any of the following occurs: .RS .5i .HP .5i - An end-of-file on the input sequence. .HP .5i - A failure when inserting in the output sequence .HP .5i - An exception while getting a character from \f2sb\fP .RE If the function inserts no characters or if it stopped because an exception was thrown while extracting a character, it calls the \f2basic_ios\fP member function \f2setstate(failbit)\fP. If an exception was thrown while extracting a character it is rethrown. .RE .SH UNFORMATTED FUNCTIONS .br ostream_type& .br flush(); .RE .RS 3 If \f2rdbuf()\fP is not a null pointer, calls \f2rdbuf()->pubsync()\fP and returns \f2*this\fP. If that function returns \f2-1\fP, calls \f2setstate(badbit)\fP. .RE .br ostream_type& .br put(char_type c); .RE .RS 3 Inserts the character\f2 c\fP. If the operation fails, calls the \f2basic_ios\fP member function\f2 setstate(badbit)\fP. .RE .br ostream_type& .br seekp(pos_type pos); .RE .RS 3 If the \f2basic_ios\fP member function \f2fail()\fP returns \f2false\fP, executes \f2rdbuf()->pubseekpos(pos)\fP, which positions the current pointer of the output sequence at the position designated by \f2pos\fP. .RE .br ostream_type& .br seekp(off_type off, ios_base::seekdir dir); .RE .RS 3 If the \f2basic_ios\fP member function \f2fail()\fP returns \f2false\fP, executes \f2rdbuf()->pubseekpos(off,dir)\fP, which positions the current pointer of the output sequence at the position designated by \f2off\fP and \f2dir\fP. .RE .br pos_type .br tellp(); .RE .RS 3 If the \f2basic_ios\fP member function \f2fail()\fP returns \f2true\fP, \f2tellp()\fP returns \f2pos_type(off_type(-1))\fP to indicate failure. Otherwise it returns the current position of the output sequence by calling \f2rdbuf()-> pubseekoff(0,cur, out)\fP. .RE .br ostream_type& .br write(const char_type* s, streamsize n); .RE .RS 3 Obtains characters to insert from successive locations of an array whose first element is designated by \f2s\fP. Characters are inserted until either of the following occurs: .RS .5i .HP .5i - \f2n\fP characters are inserted .HP .5i - Inserting in the output sequence fails .RE In the second case the function calls the \f2basic_ios\fP member function \f2setstate(badbit)\fP. The function returns \f2*this\fP. .RE .SH NON-MEMBER FUNCTIONS .br template .br basic_ostream& .br endl(basic_ostream& os); .RE .RS 3 Outputs a \f2newline\fP character and flushes the buffer, then returns \f2os\fP. .RE .br template .br basic_ostream& .br ends(basic_ostream& os); .RE .RS 3 Inserts a null character into the output sequence, then returns \f2os\fP. .RE .br template .br basic_ostream& .br flush(basic_ostream& os); .RE .RS 3 Flushes the buffer, then returns \f2os\fP. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, charT c); .RE .RS 3 Outputs the character \f2c\fP of type \f2charT\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2charT\fP. Padding is not ignored. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, char c); .RE .RS 3 Outputs the character \f2c\fP of type \f2char\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2charT\fP. Conversion from characters of type \f2char\fP to characters of type \f2charT\fP is performed by the \f2basic_ios\fP member function \f2widen\fP. Padding is not ignored. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, char c); .RE .RS 3 Outputs the character \f2c\fP of type \f2char\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2char\fP. Padding is not ignored. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, .RE .RS 10 const charT* s); .RE .RS 3 Outputs the null-terminated-byte-string \f2s\fP of type \f2charT*\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2charT\fP. .RE .RE .RS 0 template .br basic_ostream& .br operator<<(basic_ostream& os, .RE .RS 10 const char* s); .RE .RS 3 Outputs the null-terminated-byte-string \f2s\fP of type \f2char*\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2charT\fP. Conversion from characters of type \f2char\fP to characters of type \f2charT\fP is performed by the \f2basic_ios\fP member function \f2widen\fP. .RE .RE .RS 0 template .br basic_ostream& .br operator<<(basic_ostream& os, const char* s); .RE .RS 3 Outputs the null-terminated-byte-string \f2s\fP of type \f2char*\fP into the \f2basic_ostream\fP object's buffer. Both the stream and the stream buffer are instantiated on type \f2char\fP. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, .RE .RS 10 unsigned char c); .RE .RS 3 Returns \f2os << (char)c\fP. .RE .RE .RS 0 template .br basic_ostream& .br operator<<(basic_ostream& os, signed char c); .RE .RS 3 Returns \f2os << (char)c\fP. .RE .br template .br basic_ostream& .br operator<<(basic_ostream& os, .RE .RS 10 unsigned char* c); .RE .RS 3 Returns \f2os << (char*)c\fP. .RE .RE .RS 0 template .br basic_ostream& .br operator<<(basic_ostream& os, .RE .RS 10 signed char* c); .RE .RS 3 Returns \f2os << (char*)c\fP. .RE .SH FORMATTING The formatting is done through member functions or manipulators. Manipulators Member Functions \f2showpos\fP \f2setf(ios_base::showpos)\fP \f2noshowpos\fP \f2unsetf(ios_base::showpos)\fP \f2showbase\fP \f2setf(ios_base::showbase)\fP \f2noshowbase\fP \f2unsetf(ios_base::showbase)\fP \f2uppercase\fP \f2setf(ios_base::uppercase)\fP \f2nouppercase\fP \f2unsetf(ios_base::uppercase)\fP \f2showpoint\fP \f2setf(ios_base::showpoint)\fP \f2noshowpoint\fP \f2unsetf(ios_base::showpoint)\fP \f2boolalpha\fP \f2setf(ios_base::boolalpha)\fP \f2noboolalpha\fP \f2unsetf(ios_base::boolalpha) \fP \f2unitbuf\fP \f2setf(ios_base::unitbuf)\fP \f2nounitbuf\fP \f2unsetf(ios_base::unitbuf)\fP \f2internal\fP \f2setf(ios_base::internal, ios_base::adjustfield)\fP \f2left\fP \f2setf(ios_base::left, ios_base::adjustfield)\fP \f2right\fP \f2setf(ios_base::right, ios_base::adjustfield)\fP \f2dec\fP \f2setf(ios_base::dec, ios_base::basefield)\fP \f2hex\fP \f2setf(ios_base::hex, ios_base::basefield) \fP \f2oct\fP \f2setf(ios_base::oct, ios_base::basefield)\fP \f2fixed\fP \f2setf(ios_base::fixed, ios_base::floatfield)\fP \f2scientific\fP \f2setf(ios_base::scientific, ios_base::floatfield)\fP \f2resetiosflags (ios_base::fmtflags flag)\fP \f2setf(0,flag)\fP \f2setiosflags (ios_base::fmtflags flag)\fP \f2setf(flag)\fP \f2setbase(int base) \fP see above \f2setfill(char_type c)\fP \f2fill(c)\fP \f2setprecision(int n)\fP \f2precision(n) \fP \f2setw(int n)\fP \f2width(n)\fP .SH DESCRIPTION .HP 10 \f2showpos\fP\f2 \fPGenerates a + sign in non-negative generated numeric output. .HP 0 .HP 11 \f2showbase\fP\f2 \fPGenerates a prefix indicating the numeric base of generated integer output .HP 0 .HP 12 \f2uppercase\fP\f2 \fPReplaces certain lowercase letters with their uppercase equivalents in generated output .HP 0 .HP 12 \f2showpoint\fP\f2 \fPGenerates a decimal-point character unconditionally in generated floating-point output .HP 0 .HP 12 \f2boolalpha\fP\f2 \fPInserts and extracts bool type in alphabetic format .HP 0 .HP 10 \f2unitbuf\fP\f2 \fPFlushes output after each output operation .HP 0 .HP 11 \f2internal\fP\f2 \fPAdds fill characters at a designated internal point in certain generated output. If no such point is designated, it's identical to \f2right\fP. .HP 0 .HP 7 \f2left\fP\f2 \fPAdds fill characters on the right (final positions) of certain generated output .HP 0 .HP 8 \f2right\fP\f2 \fPAdds fill characters on the left (initial positions) of certain generated output .HP 0 .HP 6 \f2dec\fP\f2 \fPConverts integer input or generates integer output in decimal base .HP 0 .HP 6 \f2hex\fP\f2 \fPConverts integer input or generates integer output in hexadecimal base .HP 0 .HP 6 \f2oct\fP\f2 \fPConverts integer input or generates integer output in octal base .HP 0 .HP 8 \f2fixed\fP\f2 \fPGenerates floating-point output in fixed-point notation .HP 0 .HP 13 \f2scientific\fP\f2 \fPGenerates floating-point output in scientific notation .HP 0 \f2resetiosflags .HP 25 (ios_base::fmtflags flag)\fP Resets the \f2fmtflags\fP field \f2flag\fP .HP 0 \f2setiosflags .HP 25 (ios_base::fmtflags flag)\fP Sets up the flag \f2flag\fP .HP 0 .HP 20 \f2setbase(int base)\fP\f2 \fPConverts integer input or generates integer output in base \f2base\fP. The parameter \f2base\fP can be 8, 10 or 16. .HP 0 .HP 23 \f2setfill(char_type c)\fP\f2 \fPSets the character used to pad (fill) an output conversion to the specified field width .HP 0 .HP 22 \f2setprecision(int n)\fP\f2 \fPSets the precision (number of digits after the decimal point) to generate on certain output conversions .HP 0 .HP 14 \f2setw(int n)\fP\f2 \fPSets the field with (number of characters) to generate on certain output conversions .HP 0 .SH EXAMPLE .RE .RS 0 // .br // stdlib/examples/manual/ostream1.cpp .br // .br #include .br #include .br #include .br #include .br .br void main ( ) .br { .RE .RS 2 using namespace std; .RE .RS 0 .RE .RS 2 float f= 3.14159; .br int i= 22; .br const char* s= "Randy is the king of stdlib"; .RE .RS 0 .RE .RS 3 // create a read/write stringbuf object on tiny char .br // and attach it to an istringstream object .RE .RS 2 istringstream in( ios_base::in | ios_base::out ); .RE .RS 6 .RE .RS 3 // tie the ostream object to the istringstream object .RE .RS 2 ostream out(in.rdbuf()); .RE .RS 0 .RE .RS 2 out << "test beginning !" << endl; .RE .RS 0 .RE .RS 3 // output i in hexadecimal .RE .RS 2 out << hex << i < .br #include .br #include .br .br void main ( ) .br { .RE .RS 2 using namespace std; .RE .RS 0 .RE .RS 2 float f= 3.14159; .br const wchar_t* s= L"Kenavo !"; .RE .RS 0 .RE .RS 3 // create a read/write stringbuf object on wide char .br // and attach it to an wistringstream object .RE .RS 2 wistringstream in( ios_base::in | ios_base::out ); .RE .RS 6 .RE .RS 3 // tie the wostream object to the wistringstream object .RE .RS 2 wostream out(in.rdbuf()); .RE .RS 0 .RE .RS 2 out << L"test beginning !" << endl; .RE .RS 0 .RE .RS 3 // output f in scientific format .RE .RS 2 out << scientific << f <