<?xml version="1.0" encoding="UTF-8" standalone="no"?><!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 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="streambufs.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="streambufs.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 toonly include the headers you really need. Many people simply include<iostream> when they don't need to -- and that can <span class="emphasis"><em>penalizeyour runtime as well.</em></span> Here are some tips on which header to usefor which situations, starting with the simplest.</p><p><span class="emphasis"><em><iosfwd></em></span> should be included whenever you simplyneed the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as"ofstream" or "basic_streambuf". Like the nameimplies, these are forward declarations. (A word to all you fellowold school programmers: trying to forward declare classes like"class istream;" won't work. Look in the iosfwd header ifyou'd like to know why.) For example,</p><pre class="programlisting">#include <iosfwd>class MyClass{....std::ifstream& input_file;};extern std::ostream& operator<< (std::ostream&, MyClass&);</pre><p><span class="emphasis"><em><ios></em></span> declares the base classes for the entireI/O stream hierarchy, std::ios_base and std::basic_ios<charT>, thecounting types std::streamoff and std::streamsize, the filepositioning type std::fpos, and the various manipulators likestd::hex, std::fixed, std::noshowbase, and so forth.</p><p>The ios_base class is what holds the format flags, the state flags,and the functions which change them (setf(), width(), precision(),etc). You can also store extra data and register callback functionsthrough ios_base, but that has been historically underused. Anythingwhich doesn't depend on the type of characters stored is consolidatedhere.</p><p>The template class basic_ios is the highest template class in thehierarchy; it is the first one depending on the character type, andholds all general state associated with that type: the pointer to thepolymorphic stream buffer, the facet information, etc.</p><p><span class="emphasis"><em><streambuf></em></span> declares the template classbasic_streambuf, and two standard instantiations, streambuf andwstreambuf. If you need to work with the vastly useful and capablestream buffer classes, e.g., to create a new form of storagetransport, this header is the one to include.</p><p><span class="emphasis"><em><istream></em></span>/<span class="emphasis"><em><ostream></em></span> arethe headers to include when you are using the >>/<<interface, or any of the other abstract stream formatting functions.For example,</p><pre class="programlisting">#include <istream>std::ostream& operator<< (std::ostream& os, MyClass& c){return os << c.data1() << c.data2();}</pre><p>The std::istream and std::ostream classes are the abstract parents ofthe various concrete implementations. If you are only using theinterfaces, then you only need to use the appropriate interface header.</p><p><span class="emphasis"><em><iomanip></em></span> provides "extractors and insertersthat alter information maintained by class ios_base and its derivedclasses," such as std::setprecision and std::setw. If you needto write expressions like <code class="code">os << setw(3);</code> or<code class="code">is >> setbase(8);</code>, you must include <iomanip>.</p><p><span class="emphasis"><em><sstream></em></span>/<span class="emphasis"><em><fstream></em></span>declare the six stringstream and fstream classes. As they are thestandard concrete descendants of istream and ostream, you will alreadyknow about them.</p><p>Finally, <span class="emphasis"><em><iostream></em></span> provides the eight standardglobal objects (cin, cout, etc). To do this correctly, this headeralso provides the contents of the <istream> and <ostream>headers, but nothing else. The contents of this header look like</p><pre class="programlisting">#include <ostream>#include <istream>namespace std{extern istream cin;extern ostream cout;....// this is explained below<span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name}</pre><p>Now, the runtime penalty mentioned previously: the global objectsmust be initialized before any of your own code uses them; this isguaranteed by the standard. Like any other global object, they mustbe initialized once and only once. This is typically done with aconstruct like the one above, and the nested class ios_base::Init isspecified in the standard for just this reason.</p><p>How does it work? Because the header is included before any of yourcode, the <span class="emphasis"><em>__foo</em></span> object is constructed before any ofyour objects. (Global objects are built in the order in which theyare declared, and destroyed in reverse order.) The first time theconstructor runs, the eight stream objects are set up.</p><p>The <code class="code">static</code> keyword means that each object file compiledfrom a source file containing <iostream> will have its ownprivate copy of <span class="emphasis"><em>__foo</em></span>. There is no specified orderof construction across object files (it's one of those pesky NPproblems that make life so interesting), so one copy in each objectfile means that the stream objects are guaranteed to be set up beforeany of your code which uses them could run, thereby meeting therequirements of the standard.</p><p>The penalty, of course, is that after the first copy of<span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wastedprocessor time. The time spent is merely for an increment-and-testinside a function call, but over several dozen or hundreds of objectfiles, that time can add up. (It's not in a tight loop, either.)</p><p>The lesson? Only include <iostream> when you need to use one ofthe standard objects in that source file; you'll pay less startuptime. Only include the header files you need to in general; yourcompile times will go down when there's less parsing work to do.</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="streambufs.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>