1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 24. Iostream Objects</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="io.html" title="Part XI. Input and Output" /><link rel="next" href="bk01pt11ch25.html" title="Chapter 25. Stream Buffers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 24. Iostream Objects</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch25.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.objects"></a>Chapter 24. Iostream Objects</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to
4 only include the headers you really need. Many people simply include
5 <iostream> when they don't need to -- and that can <span class="emphasis"><em>penalize
6 your runtime as well.</em></span> Here are some tips on which header to use
7 for which situations, starting with the simplest.
8 </p><p><span class="emphasis"><em><iosfwd></em></span> should be included whenever you simply
9 need the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as
10 "ofstream" or "basic_streambuf". Like the name
11 implies, these are forward declarations. (A word to all you fellow
12 old school programmers: trying to forward declare classes like
13 "class istream;" won't work. Look in the iosfwd header if
14 you'd like to know why.) For example,
15 </p><pre class="programlisting">
16 #include <iosfwd>
21 std::ifstream& input_file;
24 extern std::ostream& operator<< (std::ostream&, MyClass&);
25 </pre><p><span class="emphasis"><em><ios></em></span> declares the base classes for the entire
26 I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
27 counting types std::streamoff and std::streamsize, the file
28 positioning type std::fpos, and the various manipulators like
29 std::hex, std::fixed, std::noshowbase, and so forth.
30 </p><p>The ios_base class is what holds the format flags, the state flags,
31 and the functions which change them (setf(), width(), precision(),
32 etc). You can also store extra data and register callback functions
33 through ios_base, but that has been historically underused. Anything
34 which doesn't depend on the type of characters stored is consolidated
36 </p><p>The template class basic_ios is the highest template class in the
37 hierarchy; it is the first one depending on the character type, and
38 holds all general state associated with that type: the pointer to the
39 polymorphic stream buffer, the facet information, etc.
40 </p><p><span class="emphasis"><em><streambuf></em></span> declares the template class
41 basic_streambuf, and two standard instantiations, streambuf and
42 wstreambuf. If you need to work with the vastly useful and capable
43 stream buffer classes, e.g., to create a new form of storage
44 transport, this header is the one to include.
45 </p><p><span class="emphasis"><em><istream></em></span>/<span class="emphasis"><em><ostream></em></span> are
46 the headers to include when you are using the >>/<<
47 interface, or any of the other abstract stream formatting functions.
49 </p><pre class="programlisting">
50 #include <istream>
52 std::ostream& operator<< (std::ostream& os, MyClass& c)
54 return os << c.data1() << c.data2();
56 </pre><p>The std::istream and std::ostream classes are the abstract parents of
57 the various concrete implementations. If you are only using the
58 interfaces, then you only need to use the appropriate interface header.
59 </p><p><span class="emphasis"><em><iomanip></em></span> provides "extractors and inserters
60 that alter information maintained by class ios_base and its derived
61 classes," such as std::setprecision and std::setw. If you need
62 to write expressions like <code class="code">os << setw(3);</code> or
63 <code class="code">is >> setbase(8);</code>, you must include <iomanip>.
64 </p><p><span class="emphasis"><em><sstream></em></span>/<span class="emphasis"><em><fstream></em></span>
65 declare the six stringstream and fstream classes. As they are the
66 standard concrete descendants of istream and ostream, you will already
68 </p><p>Finally, <span class="emphasis"><em><iostream></em></span> provides the eight standard
69 global objects (cin, cout, etc). To do this correctly, this header
70 also provides the contents of the <istream> and <ostream>
71 headers, but nothing else. The contents of this header look like
72 </p><pre class="programlisting">
73 #include <ostream>
74 #include <istream>
82 // this is explained below
83 <span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name
85 </pre><p>Now, the runtime penalty mentioned previously: the global objects
86 must be initialized before any of your own code uses them; this is
87 guaranteed by the standard. Like any other global object, they must
88 be initialized once and only once. This is typically done with a
89 construct like the one above, and the nested class ios_base::Init is
90 specified in the standard for just this reason.
91 </p><p>How does it work? Because the header is included before any of your
92 code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of
93 your objects. (Global objects are built in the order in which they
94 are declared, and destroyed in reverse order.) The first time the
95 constructor runs, the eight stream objects are set up.
96 </p><p>The <code class="code">static</code> keyword means that each object file compiled
97 from a source file containing <iostream> will have its own
98 private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order
99 of construction across object files (it's one of those pesky NP
100 problems that make life so interesting), so one copy in each object
101 file means that the stream objects are guaranteed to be set up before
102 any of your code which uses them could run, thereby meeting the
103 requirements of the standard.
104 </p><p>The penalty, of course, is that after the first copy of
105 <span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wasted
106 processor time. The time spent is merely for an increment-and-test
107 inside a function call, but over several dozen or hundreds of object
108 files, that time can add up. (It's not in a tight loop, either.)
109 </p><p>The lesson? Only include <iostream> when you need to use one of
110 the standard objects in that source file; you'll pay less startup
111 time. Only include the header files you need to in general; your
112 compile times will go down when there's less parsing work to do.
113 </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch25.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part XI. Input and Output </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 25. Stream Buffers</td></tr></table></div></body></html>