.\" ident @(#)cout.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH cout 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2cout\fP

\ - Controls output to a stream buffer associated with the object \f2stdout\fP declared in \f2<cstdio>\fP.



.SH  SYNOPSIS


.br
#include <iostream>
.br
extern ostream cout;
.br
ostream cout;



.SH  DESCRIPTION


The object \f2cout\fP controls output to a stream buffer associated with the object \f2stdout\fP declared in \f2<cstdio>\fP. By default the standard C and C++ streams are synchronized, but performance improvement can be achieved by using the \f2ios_base\fP member function \f2synch_with_stdio\fP to desynchronize them.

After the object \f2cin\fP is initialized, \f2cin.tie()\fP returns \f2&cout\fP, which implies that \f2cin\fP and \f2cout\fP are synchronized.



.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
  

\f2endl\fP

\f2ends\fP

\f2flush\fP
	
\f2flush( )\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




.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 21
\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

.HP 7
\f2endl\fP\f2   \fPInserts a newline character into the output sequence and flush the output buffer. 
.HP 0

.HP 7
\f2ends\fP\f2   \fPInserts a null character into the output sequence. 
.HP 0

.HP 8
\f2flush\fP\f2   \fPFlush the output buffer. 
.HP 0


.SH  DEFAULT VALUES



.br
precision()            6
.br
width()                0
.br
fill()                 the space character
.br
flags()                skipws | dec
.br
getloc()               locale::locale()



.SH  EXAMPLE



.br
//
.br
// cout example #1
.br
//
.br
#include<iostream>
.br
#include<iomanip>
.br

.br
void main ( )
.br
{
.RE
.RS 1
using namespace std;
.RE
.RS 0

.RE
.RS 1
int i;
.br
float f;
.RE
.RS 2

.br
// read an integer and a float from stdin
.RE
.RS 1
cin >> i >> f;
.RE
.RS 2
// output the integer and goes at the line
.RE
.RS 1
cout << i << endl;
.RE
.RS 0

.RE
.RS 2
// output the float and goes at the line
.RE
.RS 1
cout << f << endl;   
.RE
.RS 0

.RE
.RS 2
// output i in hexa
.RE
.RS 1
cout << hex << i << endl;
.RE
.RS 0

.RE
.RS 2
// output i in octal and then in decimal
.RE
.RS 1
cout << oct << i << dec << i << endl;  
.RE
.RS 0

.RE
.RS 2
// output i preceded by its sign
.RE
.RS 1
cout << showpos << i << endl;
.RE
.RS 0

.RE
.RS 2
// output i in hexa
.RE
.RS 1
cout << setbase(16) << i << endl;
.RE
.RS 0

.RE
.RS 2
// output i in dec and pad to the left with character
.br
// @ until a width of 20
.br
// if you input 45 it outputs 45@@@@@@@@@@@@@@@@@@ 
.RE
.RS 1
cout << setfill('@') << setw(20) << left << dec << i;
.br
cout << endl;
.RE
.RS 0

.RE
.RS 2
// output the same result as the code just above
.br
// but uses member functions rather than manipulators
.RE
.RS 1
cout.fill('@');
.br
cout.width(20);
.br
cout.setf(ios_base::left, ios_base::adjustfield);
.br
cout.setf(ios_base::dec, ios_base::basefield);
.br
cout << i << endl; 
.RE
.RS 0

.RE
.RS 2
// outputs f in scientific notation with
.br
// a precision of 10 digits
.RE
.RS 1
cout << scientific << setprecision(10) << f << endl;
.RE
.RS 0

.RE
.RS 2
// change the precision to 6 digits
.br
// equivalents to cout << setprecision(6);
.RE
.RS 1
cout.precision(6);
.RE
.RS 0

.RE
.RS 2
// output f and goes back to fixed notation
.RE
.RS 1
cout << f << fixed << endl;
.RE
.RS 0

.br
}
.br
//
.br
// cout example #2
.br
//
.br
#include <iostream>
.br

.br
void main ( )
.br
{
.RE
.RS 1
using namespace std;
.RE
.RS 0

.RE
.RS 1
char p[50];
.RE
.RS 0

.RE
.RS 1
cin.getline(p,50);
.RE
.RS 0

.RE
.RS 1
cout << p;   
.RE
.RS 0
}
.br
//
.br
// cout example #3
.br
//
.br
#include <iostream>
.br
#include <fstream>
.br

.br
void main ( )
.br
{
.RE
.RS 1
using namespace std;
.RE
.RS 0

.RE
.RS 2
// open the file "file_name.txt"
.br
// for reading
.RE
.RS 1
ifstream in("file_name.txt");
.RE
.RS 2

.br
// output the all file to stdout
.RE
.RS 1
if ( in ) 
.RE
.RS 3
cout << in.rdbuf(); 
.RE
.RS 1
else
.RE
.RS 4
{ 
.RE
.RS 5
cout << "Error while opening the file";  
.br
cout << endl;
.RE
.RS 4
}
.RE
.RS 0
}



.SH  WARNINGS


Keep in mind that the manipulator \f2endl\fP flushes the stream buffer. Therefore it is recommended to use `\\n' if your only intent is to go at the line. It greatly improves performance when C and C++ streams are not synchronized.

If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP.



.SH  SEE ALSO


basic_ostream(3C++), basic_iostream(3C++), basic_filebuf(3C++), cin(3C++), cerr(3C++), clog(3C++), wcin(3C++), wcout(3C++), wcerr(3C++), wclog(3C++), iomanip(3C++)

Working Paper for Draft Proposed International Standard for Information Systems--Programming Language C++, Section 27.3.1 



.SH  STANDARDS CONFORMANCE


ANSI X3J16/ISO WG21 Joint C++ Committee