summaryrefslogtreecommitdiff
path: root/libstdc++-v3/doc/html/manual/io.html
diff options
context:
space:
mode:
authorupstream source tree <ports@midipix.org>2015-03-15 20:14:05 -0400
committerupstream source tree <ports@midipix.org>2015-03-15 20:14:05 -0400
commit554fd8c5195424bdbcabf5de30fdc183aba391bd (patch)
tree976dc5ab7fddf506dadce60ae936f43f58787092 /libstdc++-v3/doc/html/manual/io.html
downloadcbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.bz2
cbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.xz
obtained gcc-4.6.4.tar.bz2 from upstream website;upstream
verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository.
Diffstat (limited to 'libstdc++-v3/doc/html/manual/io.html')
-rw-r--r--libstdc++-v3/doc/html/manual/io.html121
1 files changed, 121 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/html/manual/io.html b/libstdc++-v3/doc/html/manual/io.html
new file mode 100644
index 000000000..01ef0ff23
--- /dev/null
+++ b/libstdc++-v3/doc/html/manual/io.html
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Chapter 13.  Input and Output</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; "/><link rel="home" href="../spine.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><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. 
+ Input and Output
+
+</th></tr><tr><td align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. 
+ Standard Contents
+ </th><td 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 id="std.io"/>Chapter 13. 
+ Input and Output
+ <a id="id480471" class="indexterm"/>
+</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></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"><a id="std.io.objects"/>Iostream Objects</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to
+ only include the headers you really need. Many people simply include
+ &lt;iostream&gt; when they don't need to -- and that can <span class="emphasis"><em>penalize
+ your runtime as well.</em></span> Here are some tips on which header to use
+ for which situations, starting with the simplest.
+ </p><p><span class="emphasis"><em>&lt;iosfwd&gt;</em></span> should be included whenever you simply
+ need the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as
+ "ofstream" or "basic_streambuf". Like the name
+ implies, these are forward declarations. (A word to all you fellow
+ old school programmers: trying to forward declare classes like
+ "class istream;" won't work. Look in the iosfwd header if
+ you'd like to know why.) For example,
+ </p><pre class="programlisting">
+ #include &lt;iosfwd&gt;
+
+ class MyClass
+ {
+ ....
+ std::ifstream&amp; input_file;
+ };
+
+ extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
+ </pre><p><span class="emphasis"><em>&lt;ios&gt;</em></span> declares the base classes for the entire
+ I/O stream hierarchy, std::ios_base and std::basic_ios&lt;charT&gt;, the
+ counting types std::streamoff and std::streamsize, the file
+ positioning type std::fpos, and the various manipulators like
+ std::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 functions
+ through ios_base, but that has been historically underused. Anything
+ which doesn't depend on the type of characters stored is consolidated
+ here.
+ </p><p>The template class basic_ios is the highest template class in the
+ hierarchy; it is the first one depending on the character type, and
+ holds all general state associated with that type: the pointer to the
+ polymorphic stream buffer, the facet information, etc.
+ </p><p><span class="emphasis"><em>&lt;streambuf&gt;</em></span> declares the template class
+ basic_streambuf, and two standard instantiations, streambuf and
+ wstreambuf. If you need to work with the vastly useful and capable
+ stream buffer classes, e.g., to create a new form of storage
+ transport, this header is the one to include.
+ </p><p><span class="emphasis"><em>&lt;istream&gt;</em></span>/<span class="emphasis"><em>&lt;ostream&gt;</em></span> are
+ the headers to include when you are using the &gt;&gt;/&lt;&lt;
+ interface, or any of the other abstract stream formatting functions.
+ For example,
+ </p><pre class="programlisting">
+ #include &lt;istream&gt;
+
+ std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
+ {
+ return os &lt;&lt; c.data1() &lt;&lt; c.data2();
+ }
+ </pre><p>The std::istream and std::ostream classes are the abstract parents of
+ the various concrete implementations. If you are only using the
+ interfaces, then you only need to use the appropriate interface header.
+ </p><p><span class="emphasis"><em>&lt;iomanip&gt;</em></span> provides "extractors and inserters
+ that alter information maintained by class ios_base and its derived
+ classes," such as std::setprecision and std::setw. If you need
+ to write expressions like <code class="code">os &lt;&lt; setw(3);</code> or
+ <code class="code">is &gt;&gt; setbase(8);</code>, you must include &lt;iomanip&gt;.
+ </p><p><span class="emphasis"><em>&lt;sstream&gt;</em></span>/<span class="emphasis"><em>&lt;fstream&gt;</em></span>
+ declare the six stringstream and fstream classes. As they are the
+ standard concrete descendants of istream and ostream, you will already
+ know about them.
+ </p><p>Finally, <span class="emphasis"><em>&lt;iostream&gt;</em></span> provides the eight standard
+ global objects (cin, cout, etc). To do this correctly, this header
+ also provides the contents of the &lt;istream&gt; and &lt;ostream&gt;
+ headers, but nothing else. The contents of this header look like
+ </p><pre class="programlisting">
+ #include &lt;ostream&gt;
+ #include &lt;istream&gt;
+
+ 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 objects
+ must be initialized before any of your own code uses them; this is
+ guaranteed by the standard. Like any other global object, they must
+ be initialized once and only once. This is typically done with a
+ construct like the one above, and the nested class ios_base::Init is
+ specified in the standard for just this reason.
+ </p><p>How does it work? Because the header is included before any of your
+ code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of
+ your objects. (Global objects are built in the order in which they
+ are declared, and destroyed in reverse order.) The first time the
+ constructor runs, the eight stream objects are set up.
+ </p><p>The <code class="code">static</code> keyword means that each object file compiled
+ from a source file containing &lt;iostream&gt; will have its own
+ private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order
+ of construction across object files (it's one of those pesky NP
+ problems that make life so interesting), so one copy in each object
+ file means that the stream objects are guaranteed to be set up before
+ any of your code which uses them could run, thereby meeting the
+ requirements 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 wasted
+ processor time. The time spent is merely for an increment-and-test
+ inside a function call, but over several dozen or hundreds of object
+ files, that time can add up. (It's not in a tight loop, either.)
+ </p><p>The lesson? Only include &lt;iostream&gt; when you need to use one of
+ the standard objects in that source file; you'll pay less startup
+ time. Only include the header files you need to in general; your
+ compile times will go down when there's less parsing work to do.
+ </p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><td align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr><tr><td align="left" valign="top">Interacting with C </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Stream Buffers</td></tr></table></div></body></html>