Three groups of member functions and one group of global functions overload this "insertion operator" (<<) applied to ostream objects:
- The first group of member functions are arithmetic inserters. These write a numerical or boolean value formatting it as a sequence of characters.
- The streambuf version copies as many characters as possible from the stream buffer object used as right-hand parameter, either until an error happens or until there are no more characters to copy.
- Those in the last group of member functions have a pointer to a function as parameter. These are designed to be used with manipulator functions.
Manipulator functions are functions specifically designed to be easily used with this operator.
- The global functions overload the operator when the parameter is either a character or a c-string, and, as expected they insert either one character or a sequence of characters to the output stream.
See the description of the parameters for more details on how each group of functions work.
Because these functions are operator overloading functions, the usual way in which they are called is:
Where strm is the identifier of a ostream object and value is an object of any type supported as right parameter. It is also possible to call a succession of insertion operations as:
which is the same as performing successive insertions on the same object strm.
The standard manipulators which have an effect when used on ostream objects are:
|boolalpha||Alphanumerical bool values (manipulator function)|
|dec||Use decimal base (manipulator function)|
|endl||Insert newline and flush (manipulator function)|
|ends||Insert null character (manipulator function)|
|fixed||Use fixed-point notation (manipulator function)|
|flush||Flush stream buffer (manipulator function)|
|hex||Use hexadecimal base (manipulator function)|
|internal||Adjust field by inserting characters at an internal position (manipulator function)|
|left||Adjust output to the left (manipulator function)|
|noboolalpha||No alphanumerical bool values (manipulator function)|
|noshowbase||Do not show numerical base prefixes (manipulator function)|
|noshowpoint||Do not show decimal point (manipulator function)|
|noshowpos||Do not show positive signs (manipulator function)|
|nounitbuf||Do not force flushes after insertions (manipulator function)|
|nouppercase||Do not generate upper case letters (manipulator function)|
|oct||Use octal base (manipulator function)|
|right||Adjust output to the right (manipulator function)|
|scientific||Use scientific notation (manipulator function)|
|showbase||Show numerical base prefixes (manipulator function)|
|showpoint||Show decimal point (manipulator function)|
|showpos||Show positive signs (manipulator function)|
|unitbuf||Flush buffer after insertions (manipulator function)|
|uppercase||Generate upper-case letters (manipulator function)|
Other manipulators may be applied, but have no effect on standard ostream objects.
- Inserts a representation of the value of the val parameter as a sequence of human-readable characters. The specific way in which the data is formatted depends on the manipulators previously inserted on the stream and on its associated locale.
- Inserts characters from sb and writes them to the output sequence until the End-Of-File is reached (in which case this last character is not extracted).
- Calls pf(*this), which generally is a manipulator function.
- A single character is inserted.
Inserts a sequence characters coming from a c-string, i.e. s is a pointer to the first character of the sequence to be inserted. Insertion ends when the next character is either a valid whitespace or the terminating null character of the c-string, or if the End-Of-File is reached.
After a call to this version of the insertion operation, the value of the field width is automatically reset to zero.
- stream object on which the action is performed. This is the first parameter of the global functions, and represents the object to the left of the operator, i.e. the object on which the extraction operation is performed.
Return ValueThe object itself (*this).
Errors are signaled by modifying the internal state flags:
|failbit||When used with a streambuf object as parameter, failbit is set on if no characters could be extracted from it.|
|badbit||An error other than the above happened.|
(see ios_base::iostate for more info on these)
Additionaly, in any of these cases, if the appropriate flag has been set with member function ios::exceptions, an exception of type ios_base::failure is thrown.
If some error happens during the output operation, the stream's badbit flag is set, and if the appropriate flag has been set with ios::exceptions, an exception is thrown.
The source demonstrates the use of some of the overloaded operator<< functions shown above using the ostream standard object cout.
Basic template member declarations( basic_ostream<charT,traits> )
Basic template global functions
|ostream::put||Put character (public member function)|
|istream::operator>>||Extract formatted data (public member function)|