libstdc++-v3/doc/html/manual/io.html

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