1*36ac495dSmrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2*36ac495dSmrg<!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 Stylesheets Vsnapshot" /><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. 3*36ac495dSmrg Input and Output 4*36ac495dSmrg 5*36ac495dSmrg</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. 6*36ac495dSmrg Standard Contents 7*36ac495dSmrg </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. 8*36ac495dSmrg Input and Output 9*36ac495dSmrg <a id="id-1.3.4.11.1.1.1" class="indexterm"></a> 10*36ac495dSmrg</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*36ac495dSmrg only include the headers you really need. Many people simply include 12*36ac495dSmrg <code class="filename"><iostream></code> when they don't 13*36ac495dSmrg need to -- and that can <span class="emphasis"><em>penalize your runtime as well.</em></span> 14*36ac495dSmrg Here are some tips on which header to use 15*36ac495dSmrg for which situations, starting with the simplest. 16*36ac495dSmrg </p><p><span class="emphasis"><em><code class="filename"><iosfwd></code></em></span> 17*36ac495dSmrg should be included whenever you simply need the <span class="emphasis"><em>name</em></span> 18*36ac495dSmrg of an I/O-related class, such as "<code class="classname">ofstream</code>" or 19*36ac495dSmrg "<code class="classname">basic_streambuf</code>". 20*36ac495dSmrg Like the name implies, these are forward declarations. 21*36ac495dSmrg (A word to all you fellow old school programmers: 22*36ac495dSmrg trying to forward declare classes like "<code class="code">class istream;</code>" 23*36ac495dSmrg won't work. 24*36ac495dSmrg Look in the <code class="filename"><iosfwd></code> header 25*36ac495dSmrg if you'd like to know why.) For example, 26*36ac495dSmrg </p><pre class="programlisting"> 27*36ac495dSmrg #include <iosfwd> 28*36ac495dSmrg 29*36ac495dSmrg class MyClass 30*36ac495dSmrg { 31*36ac495dSmrg .... 32*36ac495dSmrg std::ifstream& input_file; 33*36ac495dSmrg }; 34*36ac495dSmrg 35*36ac495dSmrg extern std::ostream& operator<< (std::ostream&, MyClass&); 36*36ac495dSmrg </pre><p><span class="emphasis"><em><code class="filename"><ios></code></em></span> 37*36ac495dSmrg declares the base classes for the entire I/O stream hierarchy, 38*36ac495dSmrg <code class="classname">std::ios_base</code> and <code class="classname">std::basic_ios<charT></code>, 39*36ac495dSmrg the counting types <span class="type">std::streamoff</span> and <span class="type">std::streamsize</span>, 40*36ac495dSmrg the file positioning type <span class="type">std::fpos</span>, 41*36ac495dSmrg and the various manipulators like <code class="function">std::hex</code>, 42*36ac495dSmrg <code class="function">std::fixed</code>, <code class="function">std::noshowbase</code>, 43*36ac495dSmrg and so forth. 44*36ac495dSmrg </p><p>The <code class="classname">ios_base</code> class is what holds the format 45*36ac495dSmrg flags, the state flags, and the functions which change them 46*36ac495dSmrg (<code class="function">setf()</code>, <code class="function">width()</code>, 47*36ac495dSmrg <code class="function">precision()</code>, etc). 48*36ac495dSmrg You can also store extra data and register callback functions 49*36ac495dSmrg through <code class="classname">ios_base</code>, but that has been historically 50*36ac495dSmrg underused. Anything 51*36ac495dSmrg which doesn't depend on the type of characters stored is consolidated 52*36ac495dSmrg here. 53*36ac495dSmrg </p><p>The class template <code class="classname">basic_ios</code> is the highest 54*36ac495dSmrg class template in the 55*36ac495dSmrg hierarchy; it is the first one depending on the character type, and 56*36ac495dSmrg holds all general state associated with that type: the pointer to the 57*36ac495dSmrg polymorphic stream buffer, the facet information, etc. 58*36ac495dSmrg </p><p><span class="emphasis"><em><code class="filename"><streambuf></code></em></span> 59*36ac495dSmrg declares the class template <code class="classname">basic_streambuf</code>, and 60*36ac495dSmrg two standard instantiations, <span class="type">streambuf</span> and 61*36ac495dSmrg <span class="type">wstreambuf</span>. If you need to work with the vastly useful and 62*36ac495dSmrg capable stream buffer classes, e.g., to create a new form of storage 63*36ac495dSmrg transport, this header is the one to include. 64*36ac495dSmrg </p><p><span class="emphasis"><em><code class="filename"><istream></code></em></span> 65*36ac495dSmrg and <span class="emphasis"><em><code class="filename"><ostream></code></em></span> 66*36ac495dSmrg are the headers to include when you are using the overloaded 67*36ac495dSmrg <code class="code">>></code> and <code class="code"><<</code> operators, 68*36ac495dSmrg or any of the other abstract stream formatting functions. 69*36ac495dSmrg For example, 70*36ac495dSmrg </p><pre class="programlisting"> 71*36ac495dSmrg #include <istream> 72*36ac495dSmrg 73*36ac495dSmrg std::ostream& operator<< (std::ostream& os, MyClass& c) 74*36ac495dSmrg { 75*36ac495dSmrg return os << c.data1() << c.data2(); 76*36ac495dSmrg } 77*36ac495dSmrg </pre><p>The <span class="type">std::istream</span> and <span class="type">std::ostream</span> classes 78*36ac495dSmrg are the abstract parents of 79*36ac495dSmrg the various concrete implementations. If you are only using the 80*36ac495dSmrg interfaces, then you only need to use the appropriate interface header. 81*36ac495dSmrg </p><p><span class="emphasis"><em><code class="filename"><iomanip></code></em></span> 82*36ac495dSmrg provides "extractors and inserters that alter information maintained by 83*36ac495dSmrg class <code class="classname">ios_base</code> and its derived classes," 84*36ac495dSmrg such as <code class="function">std::setprecision</code> and 85*36ac495dSmrg <code class="function">std::setw</code>. If you need 86*36ac495dSmrg to write expressions like <code class="code">os << setw(3);</code> or 87*36ac495dSmrg <code class="code">is >> setbase(8);</code>, you must include 88*36ac495dSmrg <code class="filename"><iomanip></code>. 89*36ac495dSmrg </p><p><span class="emphasis"><em><code class="filename"><sstream></code></em></span> 90*36ac495dSmrg and <span class="emphasis"><em><code class="filename"><fstream></code></em></span> 91*36ac495dSmrg declare the six stringstream and fstream classes. As they are the 92*36ac495dSmrg standard concrete descendants of <span class="type">istream</span> and <span class="type">ostream</span>, 93*36ac495dSmrg you will already know about them. 94*36ac495dSmrg </p><p>Finally, <span class="emphasis"><em><code class="filename"><iostream></code></em></span> 95*36ac495dSmrg provides the eight standard global objects 96*36ac495dSmrg (<code class="code">cin</code>, <code class="code">cout</code>, etc). To do this correctly, this 97*36ac495dSmrg header also provides the contents of the 98*36ac495dSmrg <code class="filename"><istream></code> and 99*36ac495dSmrg <code class="filename"><ostream></code> 100*36ac495dSmrg headers, but nothing else. The contents of this header look like: 101*36ac495dSmrg </p><pre class="programlisting"> 102*36ac495dSmrg #include <ostream> 103*36ac495dSmrg #include <istream> 104*36ac495dSmrg 105*36ac495dSmrg namespace std 106*36ac495dSmrg { 107*36ac495dSmrg extern istream cin; 108*36ac495dSmrg extern ostream cout; 109*36ac495dSmrg .... 110*36ac495dSmrg 111*36ac495dSmrg // this is explained below 112*36ac495dSmrg <span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name 113*36ac495dSmrg } 114*36ac495dSmrg </pre><p>Now, the runtime penalty mentioned previously: the global objects 115*36ac495dSmrg must be initialized before any of your own code uses them; this is 116*36ac495dSmrg guaranteed by the standard. Like any other global object, they must 117*36ac495dSmrg be initialized once and only once. This is typically done with a 118*36ac495dSmrg construct like the one above, and the nested class 119*36ac495dSmrg <code class="classname">ios_base::Init</code> is 120*36ac495dSmrg specified in the standard for just this reason. 121*36ac495dSmrg </p><p>How does it work? Because the header is included before any of your 122*36ac495dSmrg code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of 123*36ac495dSmrg your objects. (Global objects are built in the order in which they 124*36ac495dSmrg are declared, and destroyed in reverse order.) The first time the 125*36ac495dSmrg constructor runs, the eight stream objects are set up. 126*36ac495dSmrg </p><p>The <code class="code">static</code> keyword means that each object file compiled 127*36ac495dSmrg from a source file containing 128*36ac495dSmrg <code class="filename"><iostream></code> will have its own 129*36ac495dSmrg private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order 130*36ac495dSmrg of construction across object files (it's one of those pesky NP complete 131*36ac495dSmrg problems that make life so interesting), so one copy in each object 132*36ac495dSmrg file means that the stream objects are guaranteed to be set up before 133*36ac495dSmrg any of your code which uses them could run, thereby meeting the 134*36ac495dSmrg requirements of the standard. 135*36ac495dSmrg </p><p>The penalty, of course, is that after the first copy of 136*36ac495dSmrg <span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wasted 137*36ac495dSmrg processor time. The time spent is merely for an increment-and-test 138*36ac495dSmrg inside a function call, but over several dozen or hundreds of object 139*36ac495dSmrg files, that time can add up. (It's not in a tight loop, either.) 140*36ac495dSmrg </p><p>The lesson? Only include 141*36ac495dSmrg <code class="filename"><iostream></code> when you need 142*36ac495dSmrg to use one of 143*36ac495dSmrg the standard objects in that source file; you'll pay less startup 144*36ac495dSmrg time. Only include the header files you need to in general; your 145*36ac495dSmrg compile times will go down when there's less parsing work to do. 146*36ac495dSmrg </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>