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