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"><html xmlns=
"http://www.w3.org/1999/xhtml"><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" /><title>Chapter
13. Input and Output
</title><meta name=
"generator" content=
"DocBook XSL-NS Stylesheets V1.78.1" /><meta name=
"keywords" content=
"ISO C++, library" /><meta name=
"keywords" content=
"ISO C++, runtime, library" /><link rel=
"home" href=
"../index.html" title=
"The GNU C++ Library" /><link rel=
"up" href=
"std_contents.html" title=
"Part II. Standard Contents" /><link rel=
"prev" href=
"numerics_and_c.html" title=
"Interacting with C" /><link rel=
"next" href=
"streambufs.html" title=
"Stream Buffers" /></head><body><div class=
"navheader"><table width=
"100%" summary=
"Navigation header"><tr><th colspan=
"3" align=
"center">Chapter
13.
5 </th></tr><tr><td width=
"20%" align=
"left"><a accesskey=
"p" href=
"numerics_and_c.html">Prev
</a> </td><th width=
"60%" align=
"center">Part II.
7 </th><td width=
"20%" align=
"right"> <a accesskey=
"n" href=
"streambufs.html">Next
</a></td></tr></table><hr /></div><div class=
"chapter"><div class=
"titlepage"><div><div><h2 class=
"title"><a id=
"std.io"></a>Chapter
13.
9 <a id=
"idm270864037312" class=
"indexterm"></a>
10 </h2></div></div></div><div class=
"toc"><p><strong>Table of Contents
</strong></p><dl class=
"toc"><dt><span class=
"section"><a href=
"io.html#std.io.objects">Iostream Objects
</a></span></dt><dt><span class=
"section"><a href=
"streambufs.html">Stream Buffers
</a></span></dt><dd><dl><dt><span class=
"section"><a href=
"streambufs.html#io.streambuf.derived">Derived streambuf Classes
</a></span></dt><dt><span class=
"section"><a href=
"streambufs.html#io.streambuf.buffering">Buffering
</a></span></dt></dl></dd><dt><span class=
"section"><a href=
"stringstreams.html">Memory Based Streams
</a></span></dt><dd><dl><dt><span class=
"section"><a href=
"stringstreams.html#std.io.memstreams.compat">Compatibility With strstream
</a></span></dt></dl></dd><dt><span class=
"section"><a href=
"fstreams.html">File Based Streams
</a></span></dt><dd><dl><dt><span class=
"section"><a href=
"fstreams.html#std.io.filestreams.copying_a_file">Copying a File
</a></span></dt><dt><span class=
"section"><a href=
"fstreams.html#std.io.filestreams.binary">Binary Input and Output
</a></span></dt></dl></dd><dt><span class=
"section"><a href=
"io_and_c.html">Interacting with C
</a></span></dt><dd><dl><dt><span class=
"section"><a href=
"io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors
</a></span></dt><dt><span class=
"section"><a href=
"io_and_c.html#std.io.c.sync">Performance
</a></span></dt></dl></dd></dl></div><div class=
"section"><div class=
"titlepage"><div><div><h2 class=
"title" style=
"clear: both"><a id=
"std.io.objects"></a>Iostream Objects
</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to
11 only include the headers you really need. Many people simply include
12 <code class=
"filename"><iostream
></code> when they don't
13 need to -- and that can
<span class=
"emphasis"><em>penalize your runtime as well.
</em></span>
14 Here are some tips on which header to use
15 for which situations, starting with the simplest.
16 </p><p><span class=
"emphasis"><em><code class=
"filename"><iosfwd
></code></em></span>
17 should be included whenever you simply need the
<span class=
"emphasis"><em>name
</em></span>
18 of an I/O-related class, such as
"<code class="classname
">ofstream</code>" or
19 "<code class="classname
">basic_streambuf</code>".
20 Like the name implies, these are forward declarations.
21 (A word to all you fellow old school programmers:
22 trying to forward declare classes like
"<code class="code
">class istream;</code>"
24 Look in the
<code class=
"filename"><iosfwd
></code> header
25 if you'd like to know why.) For example,
26 </p><pre class=
"programlisting">
27 #include
<iosfwd
>
32 std::ifstream
& input_file;
35 extern std::ostream
& operator
<< (std::ostream
&, MyClass
&);
36 </pre><p><span class=
"emphasis"><em><code class=
"filename"><ios
></code></em></span>
37 declares the base classes for the entire I/O stream hierarchy,
38 <code class=
"classname">std::ios_base
</code> and
<code class=
"classname">std::basic_ios
<charT
></code>,
39 the counting types
<span class=
"type">std::streamoff
</span> and
<span class=
"type">std::streamsize
</span>,
40 the file positioning type
<span class=
"type">std::fpos
</span>,
41 and the various manipulators like
<code class=
"function">std::hex
</code>,
42 <code class=
"function">std::fixed
</code>,
<code class=
"function">std::noshowbase
</code>,
44 </p><p>The
<code class=
"classname">ios_base
</code> class is what holds the format
45 flags, the state flags, and the functions which change them
46 (
<code class=
"function">setf()
</code>,
<code class=
"function">width()
</code>,
47 <code class=
"function">precision()
</code>, etc).
48 You can also store extra data and register callback functions
49 through
<code class=
"classname">ios_base
</code>, but that has been historically
51 which doesn't depend on the type of characters stored is consolidated
53 </p><p>The class template
<code class=
"classname">basic_ios
</code> is the highest
55 hierarchy; it is the first one depending on the character type, and
56 holds all general state associated with that type: the pointer to the
57 polymorphic stream buffer, the facet information, etc.
58 </p><p><span class=
"emphasis"><em><code class=
"filename"><streambuf
></code></em></span>
59 declares the class template
<code class=
"classname">basic_streambuf
</code>, and
60 two standard instantiations,
<span class=
"type">streambuf
</span> and
61 <span class=
"type">wstreambuf
</span>. If you need to work with the vastly useful and
62 capable stream buffer classes, e.g., to create a new form of storage
63 transport, this header is the one to include.
64 </p><p><span class=
"emphasis"><em><code class=
"filename"><istream
></code></em></span>
65 and
<span class=
"emphasis"><em><code class=
"filename"><ostream
></code></em></span>
66 are the headers to include when you are using the overloaded
67 <code class=
"code">>></code> and
<code class=
"code"><<</code> operators,
68 or any of the other abstract stream formatting functions.
70 </p><pre class=
"programlisting">
71 #include
<istream
>
73 std::ostream
& operator
<< (std::ostream
& os, MyClass
& c)
75 return os
<< c.data1()
<< c.data2();
77 </pre><p>The
<span class=
"type">std::istream
</span> and
<span class=
"type">std::ostream
</span> classes
78 are the abstract parents of
79 the various concrete implementations. If you are only using the
80 interfaces, then you only need to use the appropriate interface header.
81 </p><p><span class=
"emphasis"><em><code class=
"filename"><iomanip
></code></em></span>
82 provides
"extractors and inserters that alter information maintained by
83 class <code class="classname
">ios_base</code> and its derived classes,"
84 such as
<code class=
"function">std::setprecision
</code> and
85 <code class=
"function">std::setw
</code>. If you need
86 to write expressions like
<code class=
"code">os
<< setw(
3);
</code> or
87 <code class=
"code">is
>> setbase(
8);
</code>, you must include
88 <code class=
"filename"><iomanip
></code>.
89 </p><p><span class=
"emphasis"><em><code class=
"filename"><sstream
></code></em></span>
90 and
<span class=
"emphasis"><em><code class=
"filename"><fstream
></code></em></span>
91 declare the six stringstream and fstream classes. As they are the
92 standard concrete descendants of
<span class=
"type">istream
</span> and
<span class=
"type">ostream
</span>,
93 you will already know about them.
94 </p><p>Finally,
<span class=
"emphasis"><em><code class=
"filename"><iostream
></code></em></span>
95 provides the eight standard global objects
96 (
<code class=
"code">cin
</code>,
<code class=
"code">cout
</code>, etc). To do this correctly, this
97 header also provides the contents of the
98 <code class=
"filename"><istream
></code> and
99 <code class=
"filename"><ostream
></code>
100 headers, but nothing else. The contents of this header look like:
101 </p><pre class=
"programlisting">
102 #include
<ostream
>
103 #include
<istream
>
111 // this is explained below
112 <span class=
"emphasis"><em>static ios_base::Init __foo;
</em></span> // not its real name
114 </pre><p>Now, the runtime penalty mentioned previously: the global objects
115 must be initialized before any of your own code uses them; this is
116 guaranteed by the standard. Like any other global object, they must
117 be initialized once and only once. This is typically done with a
118 construct like the one above, and the nested class
119 <code class=
"classname">ios_base::Init
</code> is
120 specified in the standard for just this reason.
121 </p><p>How does it work? Because the header is included before any of your
122 code, the
<span class=
"emphasis"><em>__foo
</em></span> object is constructed before any of
123 your objects. (Global objects are built in the order in which they
124 are declared, and destroyed in reverse order.) The first time the
125 constructor runs, the eight stream objects are set up.
126 </p><p>The
<code class=
"code">static
</code> keyword means that each object file compiled
127 from a source file containing
128 <code class=
"filename"><iostream
></code> will have its own
129 private copy of
<span class=
"emphasis"><em>__foo
</em></span>. There is no specified order
130 of construction across object files (it's one of those pesky NP complete
131 problems that make life so interesting), so one copy in each object
132 file means that the stream objects are guaranteed to be set up before
133 any of your code which uses them could run, thereby meeting the
134 requirements of the standard.
135 </p><p>The penalty, of course, is that after the first copy of
136 <span class=
"emphasis"><em>__foo
</em></span> is constructed, all the others are just wasted
137 processor time. The time spent is merely for an increment-and-test
138 inside a function call, but over several dozen or hundreds of object
139 files, that time can add up. (It's not in a tight loop, either.)
140 </p><p>The lesson? Only include
141 <code class=
"filename"><iostream
></code> when you need
143 the standard objects in that source file; you'll pay less startup
144 time. Only include the header files you need to in general; your
145 compile times will go down when there's less parsing work to do.
146 </p></div></div><div class=
"navfooter"><hr /><table width=
"100%" summary=
"Navigation footer"><tr><td width=
"40%" align=
"left"><a accesskey=
"p" href=
"numerics_and_c.html">Prev
</a> </td><td width=
"20%" align=
"center"><a accesskey=
"u" href=
"std_contents.html">Up
</a></td><td width=
"40%" align=
"right"> <a accesskey=
"n" href=
"streambufs.html">Next
</a></td></tr><tr><td width=
"40%" align=
"left" valign=
"top">Interacting with C
</td><td width=
"20%" align=
"center"><a accesskey=
"h" href=
"../index.html">Home
</a></td><td width=
"40%" align=
"right" valign=
"top"> Stream Buffers
</td></tr></table></div></body></html>