aboutsummaryrefslogtreecommitdiffstats
path: root/gcc-4.9/libstdc++-v3/doc/html/manual/io.html
diff options
context:
space:
mode:
Diffstat (limited to 'gcc-4.9/libstdc++-v3/doc/html/manual/io.html')
-rw-r--r--gcc-4.9/libstdc++-v3/doc/html/manual/io.html112
1 files changed, 69 insertions, 43 deletions
diff --git a/gcc-4.9/libstdc++-v3/doc/html/manual/io.html b/gcc-4.9/libstdc++-v3/doc/html/manual/io.html
index ae9e8b8e1..42cb03466 100644
--- a/gcc-4.9/libstdc++-v3/doc/html/manual/io.html
+++ b/gcc-4.9/libstdc++-v3/doc/html/manual/io.html
@@ -6,19 +6,23 @@
Standard Contents
</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. 
Input and Output
- <a id="idm234602610848" class="indexterm"></a>
+ <a id="idm269891032720" class="indexterm"></a>
</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
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
+ <code class="filename">&lt;iostream&gt;</code> 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><p><span class="emphasis"><em><code class="filename">&lt;iosfwd&gt;</code></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 "<code class="classname">ofstream</code>" or
+ "<code class="classname">basic_streambuf</code>".
+ Like the name implies, these are forward declarations.
+ (A word to all you fellow old school programmers:
+ trying to forward declare classes like "<code class="code">class istream;</code>"
+ won't work.
+ Look in the <code class="filename">&lt;iosfwd&gt;</code> header
+ if you'd like to know why.) For example,
</p><pre class="programlisting">
#include &lt;iosfwd&gt;
@@ -29,29 +33,39 @@
};
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
+ </pre><p><span class="emphasis"><em><code class="filename">&lt;ios&gt;</code></em></span>
+ declares the base classes for the entire I/O stream hierarchy,
+ <code class="classname">std::ios_base</code> and <code class="classname">std::basic_ios&lt;charT&gt;</code>,
+ the counting types <span class="type">std::streamoff</span> and <span class="type">std::streamsize</span>,
+ the file positioning type <span class="type">std::fpos</span>,
+ and the various manipulators like <code class="function">std::hex</code>,
+ <code class="function">std::fixed</code>, <code class="function">std::noshowbase</code>,
+ and so forth.
+ </p><p>The <code class="classname">ios_base</code> class is what holds the format
+ flags, the state flags, and the functions which change them
+ (<code class="function">setf()</code>, <code class="function">width()</code>,
+ <code class="function">precision()</code>, etc).
+ You can also store extra data and register callback functions
+ through <code class="classname">ios_base</code>, 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
+ </p><p>The class template <code class="classname">basic_ios</code> is the highest
+ class template 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
+ </p><p><span class="emphasis"><em><code class="filename">&lt;streambuf&gt;</code></em></span>
+ declares the class template <code class="classname">basic_streambuf</code>, and
+ two standard instantiations, <span class="type">streambuf</span> and
+ <span class="type">wstreambuf</span>. 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.
+ </p><p><span class="emphasis"><em><code class="filename">&lt;istream&gt;</code></em></span>
+ and <span class="emphasis"><em><code class="filename">&lt;ostream&gt;</code></em></span>
+ are the headers to include when you are using the overloaded
+ <code class="code">&gt;&gt;</code> and <code class="code">&lt;&lt;</code> operators,
+ or any of the other abstract stream formatting functions.
For example,
</p><pre class="programlisting">
#include &lt;istream&gt;
@@ -60,22 +74,30 @@
{
return os &lt;&lt; c.data1() &lt;&lt; c.data2();
}
- </pre><p>The std::istream and std::ostream classes are the abstract parents of
+ </pre><p>The <span class="type">std::istream</span> and <span class="type">std::ostream</span> 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
+ </p><p><span class="emphasis"><em><code class="filename">&lt;iomanip&gt;</code></em></span>
+ provides "extractors and inserters that alter information maintained by
+ class <code class="classname">ios_base</code> and its derived classes,"
+ such as <code class="function">std::setprecision</code> and
+ <code class="function">std::setw</code>. 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>
+ <code class="code">is &gt;&gt; setbase(8);</code>, you must include
+ <code class="filename">&lt;iomanip&gt;</code>.
+ </p><p><span class="emphasis"><em><code class="filename">&lt;sstream&gt;</code></em></span>
+ and <span class="emphasis"><em><code class="filename">&lt;fstream&gt;</code></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
+ standard concrete descendants of <span class="type">istream</span> and <span class="type">ostream</span>,
+ you will already know about them.
+ </p><p>Finally, <span class="emphasis"><em><code class="filename">&lt;iostream&gt;</code></em></span>
+ provides the eight standard global objects
+ (<code class="code">cin</code>, <code class="code">cout</code>, etc). To do this correctly, this
+ header also provides the contents of the
+ <code class="filename">&lt;istream&gt;</code> and
+ <code class="filename">&lt;ostream&gt;</code>
+ headers, but nothing else. The contents of this header look like:
</p><pre class="programlisting">
#include &lt;ostream&gt;
#include &lt;istream&gt;
@@ -93,7 +115,8 @@
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
+ construct like the one above, and the nested class
+ <code class="classname">ios_base::Init</code> 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
@@ -101,9 +124,10 @@
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
+ from a source file containing
+ <code class="filename">&lt;iostream&gt;</code> 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
+ of construction across object files (it's one of those pesky NP complete
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
@@ -113,7 +137,9 @@
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
+ </p><p>The lesson? Only include
+ <code class="filename">&lt;iostream&gt;</code> 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.