Skip to content

R
riscv-gcc-1
Commit 46abada0 by Benjamin Kosnik Committed by Benjamin Kosnik
Options

*: Populate with regenerated files. 


2008-02-11  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html/*: Populate with regenerated files.

From-SVN: r132251
parent 620039ad
Showing with 3486 additions and 0 deletions
libstdc++-v3/ChangeLog
2008-02-11 Benjamin Kosnik <bkoz@redhat.com> 2008-02-11 Benjamin Kosnik <bkoz@redhat.com>
* doc/html/*: Populate with regenerated files.
2008-02-11 Benjamin Kosnik <bkoz@redhat.com>
* doc/html/*: Remove all but contents of ext/pb_ds. * doc/html/*: Remove all but contents of ext/pb_ds.
* doc/html/index.html: New. * doc/html/index.html: New.
* doc/html/README: New. * doc/html/README: New.
......
libstdc++-v3/doc/html/api.html 0 → 100644
<?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>API and Source Level Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk02.html" title="" /><link rel="prev" href="bk02.html" title="" /><link rel="next" href="bk03.html" title="" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">API and Source Level Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk02.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="bk03.html">Next</a></td></tr></table><hr /></div><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="api"></a>API and Source Level Documentation</h2></div><div><p class="copyright">Copyright ©
2008
<a class="ulink" href="http://fsf.org" target="_top">FSF
</a>
</p></div><div><div class="legalnotice"><a id="id330876"></a><p>
<a class="ulink" href="17_intro/license.html" target="_top">License
</a>
</p></div></div></div><hr /></div><p>
The GNU C++ library sources have been specially formatted so that with the
proper invocation of another tool (Doxygen), a set of HTML pages
are generated from the sources files themselves. The resultant
documentation is referred to as Source Level Documentation, and is
useful for examining the signatures of public member functions for
the library classes, finding out what is in a particular include
file, looking at inheritance diagrams, etc.
</p><p>
The source-level documentation for the most recent releases can be
viewed online:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<a class="ulink" href="libstdc++-html-USERS-3.4/index.html" target="_top">for the 3.4 release
</a>
</p></li><li><p>
<a class="ulink" href="libstdc++-html-USERS-4.1/index.html" target="_top">for the 4.1 release
</a>
</p></li><li><p>
<a class="ulink" href="libstdc++-html-USERS-4.2/index.html" target="_top">for the 4.2 release
</a>
</p></li><li><p>
<a class="ulink" href="latest-doxygen/index.html" target="_top">"the latest collection"
</a>
(For the main development tree; see the date on the first page.)
</p></li></ul></div><p>
This generated HTML collection, as above, is also available for download in the libstdc++ snapshots directory at
<code class="literal">&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/&gt;</code>.
You will almost certainly need to use one of the
<a class="ulink" href="http://gcc.gnu.org/mirrors.html" target="_top">mirror sites</a> to download
the tarball. After unpacking, simply load libstdc++-html-*/index.html
into a browser.
</p><p>
Documentation for older releases is available for download only, not
online viewing.
</p><p>
In addition, an initial set of man pages are also available in the
same place as the HTML collections. Start with C++Intro(3).
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="spine.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
libstdc++-v3/doc/html/bk02.html 0 → 100644
<?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></title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library Documentation" /><link rel="prev" href="manual/backwards.html" title="Backwards Compatibility" /><link rel="next" href="api.html" title="API and Source Level Documentation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="book" lang="en" xml:lang="en"><div class="titlepage"><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="article"><a href="api.html">API and Source Level Documentation</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Backwards Compatibility </td><td width="20%" align="center"><a accesskey="h" href="spine.html">Home</a></td><td width="40%" align="right" valign="top"> API and Source Level Documentation</td></tr></table></div></body></html>
libstdc++-v3/doc/html/bk03.html 0 → 100644
<?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></title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library Documentation" /><link rel="prev" href="api.html" title="API and Source Level Documentation" /><link rel="next" href="faq.html" title="Frequently Asked Questions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr></table><hr /></div><div class="book" lang="en" xml:lang="en"><div class="titlepage"><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="article"><a href="faq.html">Frequently Asked Questions</a></span></dt></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">API and Source Level Documentation </td><td width="20%" align="center"><a accesskey="h" href="spine.html">Home</a></td><td width="40%" align="right" valign="top"> Frequently Asked Questions</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/algorithms.html 0 → 100644
<?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>Part IX. Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt08ch19s02.html" title="One Past the End" /><link rel="next" href="bk01pt09pr02.html" title="" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part IX. Algorithms</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt08ch19s02.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt09pr02.html">Next</a></td></tr></table><hr /></div><div class="part" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="manual.algorithms"></a>Part IX. Algorithms</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="bk01pt09pr02.html"></a></span></dt><dt><span class="chapter"><a href="bk01pt09ch20.html">20. Mutating</a></span></dt><dd><dl><dt><span class="sect1"><a href="bk01pt09ch20.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt09ch20.html#algorithms.swap.specializations">Specializations</a></span></dt></dl></dd></dl></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt08ch19s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt09pr02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">One Past the End </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/appendix_contributing.html 0 → 100644
<?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>Appendix A. Contributing</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt12ch40s03.html" title="Use" /><link rel="next" href="bk01apas02.html" title="Directory Layout and Source Conventions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. Contributing</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch40s03.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas02.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.contrib"></a>Appendix A. Contributing</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="sect2"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="sect2"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="sect2"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="sect2"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01apas02.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="sect1"><a href="bk01apas03.html">Coding Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01apas03.html#coding_style.bad_identifiers">Bad Itentifiers</a></span></dt><dt><span class="sect2"><a href="bk01apas03.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01apas04.html">Documentation Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01apas04.html#doc_style.doxygen">Doxygen</a></span></dt><dt><span class="sect2"><a href="bk01apas04.html#doc_style.docbook">Docbook</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01apas05.html">Design Notes</a></span></dt></dl></div><p>
The GNU C++ Library follows an open development model. Active
contributors are assigned maintainer-ship responsibility, and given
write access to the source repository. First time contributors
should follow this procedure:
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.list"></a>Contributor Checklist</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="list.reading"></a>Reading</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
Get and read the relevant sections of the C++ language
specification. Copies of the full ISO 14882 standard are
available on line via the ISO mirror site for committee
members. Non-members, or those who have not paid for the
privilege of sitting on the committee and sustained their
two meeting commitment for voting rights, may get a copy of
the standard from their respective national standards
organization. In the USA, this national standards
organization is ANSI and their web-site is right
<a class="ulink" href="http://www.ansi.org" target="_top">here.</a>
(And if you've already registered with them, clicking this link will take you to directly to the place where you can
<a class="ulink" href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003" target="_top">buy the standard on-line.)</a>
</p></li><li><p>
The library working group bugs, and known defects, can
be obtained here:
<a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/" target="_top">http://www.open-std.org/jtc1/sc22/wg21 </a>
</p></li><li><p>
The newsgroup dedicated to standardization issues is
comp.std.c++: this FAQ for this group is quite useful and
can be
found <a class="ulink" href="http://www.jamesd.demon.co.uk/csc/faq.html" target="_top">
here </a>.
</p></li><li><p>
Peruse
the <a class="ulink" href="http://www.gnu.org/prep/standards_toc.html" target="_top">GNU
Coding Standards</a>, and chuckle when you hit the part
about “<span class="quote">Using Languages Other Than C</span>”.
</p></li><li><p>
Be familiar with the extensions that preceded these
general GNU rules. These style issues for libstdc++ can be
found <a class="link" href="bk01apas03.html" title="Coding Style">here</a>.
</p></li><li><p>
And last but certainly not least, read the
library-specific information
found <a class="link" href="appendix_porting.html" title="Appendix B. Porting and Maintenance"> here</a>.
</p></li></ul></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="list.copyright"></a>Assignment</h3></div></div></div><p>
Small changes can be accepted without a copyright assignment form on
file. New code and additions to the library need completed copyright
assignment form on file at the FSF. Note: your employer may be required
to fill out appropriate disclaimer forms as well.
</p><p>
Historically, the libstdc++ assignment form added the following
question:
</p><p>
“<span class="quote">
Which Belgian comic book character is better, Tintin or Asterix, and
why?
</span>”
</p><p>
While not strictly necessary, humoring the maintainers and answering
this question would be appreciated.
</p><p>
For more information about getting a copyright assignment, please see
<a class="ulink" href="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html" target="_top">Legal
Matters</a>.
</p><p>
Please contact Benjamin Kosnik at
<code class="email">&lt;<a class="email" href="mailto:bkoz+assign@redhat.com">bkoz+assign@redhat.com</a>&gt;</code> if you are confused
about the assignment or have general licensing questions. When
requesting an assignment form from
<code class="email">&lt;<a class="email" href="mailto:mailto:assign@gnu.org">mailto:assign@gnu.org</a>&gt;</code>, please cc the libstdc++
maintainer above so that progress can be monitored.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="list.getting"></a>Getting Sources</h3></div></div></div><p>
<a class="ulink" href="http://gcc.gnu.org/svnwrite.html" target="_top">Getting write access
(look for "Write after approval")</a>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="list.patches"></a>Submitting Patches</h3></div></div></div><p>
Every patch must have several pieces of information before it can be
properly evaluated. Ideally (and to ensure the fastest possible
response from the maintainers) it would have all of these pieces:
</p><div class="itemizedlist"><ul type="disc"><li><p>
A description of the bug and how your patch fixes this
bug. For new features a description of the feature and your
implementation.
</p></li><li><p>
A ChangeLog entry as plain text; see the various
ChangeLog files for format and content. If using you are
using emacs as your editor, simply position the insertion
point at the beginning of your change and hit CX-4a to bring
up the appropriate ChangeLog entry. See--magic! Similar
functionality also exists for vi.
</p></li><li><p>
A testsuite submission or sample program that will
easily and simply show the existing error or test new
functionality.
</p></li><li><p>
The patch itself. If you are accessing the SVN
repository use <span class="command"><strong>svn update; svn diff NEW</strong></span>;
else, use <span class="command"><strong>diff -cp OLD NEW</strong></span> ... If your
version of diff does not support these options, then get the
latest version of GNU
diff. The <a class="ulink" href="http://gcc.gnu.org/wiki/SvnTricks" target="_top">SVN
Tricks</a> wiki page has information on customising the
output of <code class="code">svn diff</code>.
</p></li><li><p>
When you have all these pieces, bundle them up in a
mail message and send it to libstdc++@gcc.gnu.org. All
patches and related discussion should be sent to the
libstdc++ mailing list.
</p></li></ul></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch40s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Use </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Directory Layout and Source Conventions</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/appendix_free.html 0 → 100644
<?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>Appendix C. Free Software Needs Free Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="backwards.html" title="Backwards Compatibility" /><link rel="next" href="bk01apd.html" title="Appendix D. GNU General Public License" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix C. Free Software Needs Free Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="backwards.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01apd.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.free"></a>Appendix C. Free Software Needs Free Documentation</h2></div></div></div><p>
The biggest deficiency in free operating systems is not in the
software--it is the lack of good free manuals that we can include in
these systems. Many of our most important programs do not come with
full manuals. Documentation is an essential part of any software
package; when an important free software package does not come with a
free manual, that is a major gap. We have many such gaps today.
</p><p>
Once upon a time, many years ago, I thought I would learn Perl. I got
a copy of a free manual, but I found it hard to read. When I asked
Perl users about alternatives, they told me that there were better
introductory manuals--but those were not free.
</p><p>
Why was this? The authors of the good manuals had written them for
O'Reilly Associates, which published them with restrictive terms--no
copying, no modification, source files not available--which exclude
them from the free software community.
</p><p>
That wasn't the first time this sort of thing has happened, and (to
our community's great loss) it was far from the last. Proprietary
manual publishers have enticed a great many authors to restrict their
manuals since then. Many times I have heard a GNU user eagerly tell
me about a manual that he is writing, with which he expects to help
the GNU project--and then had my hopes dashed, as he proceeded to
explain that he had signed a contract with a publisher that would
restrict it so that we cannot use it.
</p><p>
Given that writing good English is a rare skill among programmers, we
can ill afford to lose manuals this way.
</p><p>
Free documentation, like free software, is a matter of freedom,
not price. The problem with these manuals was not that O'Reilly
Associates charged a price for printed copies--that in itself is fine.
(The Free Software Foundation <a class="ulink" href="http://www.gnu.org/doc/doc.html" target="_top">sells printed copies</a> of
free GNU manuals, too.) But GNU manuals are available in source code
form, while these manuals are available only on paper. GNU manuals
come with permission to copy and modify; the Perl manuals do not.
These restrictions are the problems.
</p><p>
The criterion for a free manual is pretty much the same as for free
software: it is a matter of giving all users certain freedoms.
Redistribution (including commercial redistribution) must be
permitted, so that the manual can accompany every copy of the program,
on-line or on paper. Permission for modification is crucial too.
</p><p>
As a general rule, I don't believe that it is essential for people to
have permission to modify all sorts of articles and books. The issues
for writings are not necessarily the same as those for software. For
example, I don't think you or I are obliged to give permission to
modify articles like this one, which describe our actions and our
views.
</p><p>
But there is a particular reason why the freedom to modify is crucial
for documentation for free software. When people exercise their right
to modify the software, and add or change its features, if they are
conscientious they will change the manual too--so they can provide
accurate and usable documentation with the modified program. A manual
which forbids programmers to be conscientious and finish the job, or
more precisely requires them to write a new manual from scratch if
they change the program, does not fill our community's needs.
</p><p>
While a blanket prohibition on modification is unacceptable, some
kinds of limits on the method of modification pose no problem. For
example, requirements to preserve the original author's copyright
notice, the distribution terms, or the list of authors, are ok. It is
also no problem to require modified versions to include notice that
they were modified, even to have entire sections that may not be
deleted or changed, as long as these sections deal with nontechnical
topics. (Some GNU manuals have them.)
</p><p>
These kinds of restrictions are not a problem because, as a practical
matter, they don't stop the conscientious programmer from adapting the
manual to fit the modified program. In other words, they don't block
the free software community from making full use of the manual.
</p><p>
However, it must be possible to modify all the <span class="emphasis"><em>technical</em></span>
content of the manual, and then distribute the result in all the usual
media, through all the usual channels; otherwise, the restrictions do
block the community, the manual is not free, and so we need another
manual.
</p><p>
Unfortunately, it is often hard to find someone to write another
manual when a proprietary manual exists. The obstacle is that many
users think that a proprietary manual is good enough--so they don't
see the need to write a free manual. They do not see that the free
operating system has a gap that needs filling.
</p><p>
Why do users think that proprietary manuals are good enough? Some
have not considered the issue. I hope this article will do something
to change that.
</p><p>
Other users consider proprietary manuals acceptable for the same
reason so many people consider proprietary software acceptable: they
judge in purely practical terms, not using freedom as a criterion.
These people are entitled to their opinions, but since those opinions
spring from values which do not include freedom, they are no guide for
those of us who do value freedom.
</p><p>
Please spread the word about this issue. We continue to lose manuals
to proprietary publishing. If we spread the word that proprietary
manuals are not sufficient, perhaps the next person who wants to help
GNU by writing documentation will realize, before it is too late, that
he must above all make it free.
</p><p>
We can also encourage commercial publishers to sell free, copylefted
manuals instead of proprietary ones. One way you can help this is to
check the distribution terms of a manual before you buy it, and
prefer copylefted manuals to non-copylefted ones.
</p><p>
[Note: We now maintain a <a class="ulink" href="http://www.fsf.org/licensing/doc/other-free-books.html" target="_top">web page
that lists free books available from other publishers</a>].
</p><p>Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA</p><p>Verbatim copying and distribution of this entire article are
permitted worldwide, without royalty, in any medium, provided this
notice is preserved.</p><p>Report any problems or suggestions to <code class="email">&lt;<a class="email" href="mailto:webmaster@fsf.org">webmaster@fsf.org</a>&gt;</code>.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backwards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apd.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Backwards Compatibility </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix D. GNU General Public License</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/auto_ptr.html 0 → 100644
<?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>auto_ptr</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; auto_ptr&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt04ch11.html" title="Chapter 11. Memory" /><link rel="prev" href="bk01pt04ch11.html" title="Chapter 11. Memory" /><link rel="next" href="shared_ptr.html" title="shared_ptr" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">auto_ptr</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt04ch11.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Memory</th><td width="20%" align="right"> <a accesskey="n" href="shared_ptr.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.util.memory.auto_ptr"></a>auto_ptr</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="auto_ptr.limitations"></a>Limitations</h3></div></div></div><p>Explaining all of the fun and delicious things that can
happen with misuse of the <code class="classname">auto_ptr</code> class
template (called <acronym class="acronym">AP</acronym> here) would take some
time. Suffice it to say that the use of <acronym class="acronym">AP</acronym>
safely in the presence of copying has some subtleties.
</p><p>
The AP class is a really
nifty idea for a smart pointer, but it is one of the dumbest of
all the smart pointers -- and that's fine.
</p><p>
AP is not meant to be a supersmart solution to all resource
leaks everywhere. Neither is it meant to be an effective form
of garbage collection (although it can help, a little bit).
And it can <span class="emphasis"><em>not</em></span>be used for arrays!
</p><p>
<acronym class="acronym">AP</acronym> is meant to prevent nasty leaks in the
presence of exceptions. That's <span class="emphasis"><em>all</em></span>. This
code is AP-friendly:
</p><pre class="programlisting">
// Not a recommend naming scheme, but good for web-based FAQs.
typedef std::auto_ptr&lt;MyClass&gt; APMC;
extern function_taking_MyClass_pointer (MyClass*);
extern some_throwable_function ();
void func (int data)
{
APMC ap (new MyClass(data));
some_throwable_function(); // this will throw an exception
function_taking_MyClass_pointer (ap.get());
}
</pre><p>When an exception gets thrown, the instance of MyClass that's
been created on the heap will be <code class="function">delete</code>'d as the stack is
unwound past <code class="function">func()</code>.
</p><p>Changing that code as follows is not <acronym class="acronym">AP</acronym>-friendly:
</p><pre class="programlisting">
APMC ap (new MyClass[22]);
</pre><p>You will get the same problems as you would without the use
of <acronym class="acronym">AP</acronym>:
</p><pre class="programlisting">
char* array = new char[10]; // array new...
...
delete array; // ...but single-object delete
</pre><p>
AP cannot tell whether the pointer you've passed at creation points
to one or many things. If it points to many things, you are about
to die. AP is trivial to write, however, so you could write your
own <code class="code">auto_array_ptr</code> for that situation (in fact, this has
been done many times; check the mailing lists, Usenet, Boost, etc).
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="auto_ptr.using"></a>Use in Containers</h3></div></div></div><p>
</p><p>All of the <a class="ulink" href="../23_containers/howto.html" target="_top">containers</a>
described in the standard library require their contained types
to have, among other things, a copy constructor like this:
</p><pre class="programlisting">
struct My_Type
{
My_Type (My_Type const&amp;);
};
</pre><p>
Note the const keyword; the object being copied shouldn't change.
The template class <code class="code">auto_ptr</code> (called AP here) does not
meet this requirement. Creating a new AP by copying an existing
one transfers ownership of the pointed-to object, which means that
the AP being copied must change, which in turn means that the
copy ctors of AP do not take const objects.
</p><p>
The resulting rule is simple: <span class="emphasis"><em>Never ever use a
container of auto_ptr objects</em></span>. The standard says that
“<span class="quote">undefined</span>” behavior is the result, but it is
guaranteed to be messy.
</p><p>
To prevent you from doing this to yourself, the
<a class="ulink" href="../19_diagnostics/howto.html#3" target="_top">concept checks</a> built
in to this implementation will issue an error if you try to
compile code like this:
</p><pre class="programlisting">
#include &lt;vector&gt;
#include &lt;memory&gt;
void f()
{
std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int;
}
</pre><p>
Should you try this with the checks enabled, you will see an error.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt04ch11.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt04ch11.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="shared_ptr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Memory </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> shared_ptr</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01apas02.html 0 → 100644
<?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>Directory Layout and Source Conventions</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="next" href="bk01apas03.html" title="Coding Style" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Directory Layout and Source Conventions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.organization"></a>Directory Layout and Source Conventions</h2></div></div></div><p>
The unpacked source directory of libstdc++ contains the files
needed to create the GNU C++ Library.
</p><div class="literallayout"><p><br />
It has subdirectories:<br />
<br />
  doc<br />
    Files in HTML and text format that document usage, quirks of the<br />
    implementation, and contributor checklists.<br />
<br />
  include<br />
    All header files for the C++ library are within this directory,<br />
    modulo specific runtime-related files that are in the libsupc++<br />
    directory.<br />
<br />
    include/std<br />
      Files meant to be found by #include &lt;name&gt; directives in<br />
      standard-conforming user programs.  <br />
<br />
    include/c<br />
      Headers intended to directly include standard C headers. <br />
      [NB: this can be enabled via --enable-cheaders=c]<br />
<br />
    include/c_global <br />
      Headers intended to include standard C headers in<br />
      the global namespace, and put select names into the std::<br />
      namespace.  [NB: this is the default, and is the same as<br />
      --enable-cheaders=c_global]<br />
<br />
    include/c_std <br />
      Headers intended to include standard C headers<br />
      already in namespace std, and put select names into the std::<br />
      namespace.  [NB: this is the same as --enable-cheaders=c_std]<br />
<br />
    include/bits<br />
      Files included by standard headers and by other files in<br />
      the bits directory. <br />
<br />
    include/backward<br />
      Headers provided for backward compatibility, such as &lt;iostream.h&gt;.<br />
      They are not used in this library.<br />
<br />
    include/ext<br />
      Headers that define extensions to the standard library.  No<br />
      standard header refers to any of them.<br />
<br />
  scripts<br />
    Scripts that are used during the configure, build, make, or test<br />
    process.<br />
<br />
  src<br />
    Files that are used in constructing the library, but are not<br />
    installed.<br />
<br />
  testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]<br />
    Test programs are here, and may be used to begin to exercise the <br />
    library.  Support for "make check" and "make check-install" is<br />
    complete, and runs through all the subdirectories here when this<br />
    command is issued from the build directory.  Please note that<br />
    "make check" requires DejaGNU 1.4 or later to be installed.  Please<br />
    note that "make check-script" calls the script mkcheck, which<br />
    requires bash, and which may need the paths to bash adjusted to<br />
    work properly, as /bin/bash is assumed.<br />
<br />
Other subdirectories contain variant versions of certain files<br />
that are meant to be copied or linked by the configure script.<br />
Currently these are:<br />
<br />
  config/abi<br />
  config/cpu<br />
  config/io<br />
  config/locale<br />
  config/os<br />
<br />
In addition, two subdirectories are convenience libraries:<br />
<br />
  libmath<br />
    Support routines needed for C++ math. Only needed if the<br />
    underlying "C" implementation is non-existent, in particular<br />
    required or optimal long double, long long, and C99 functionality.<br />
<br />
  libsupc++<br />
    Contains the runtime library for C++, including exception<br />
    handling and memory allocation and deallocation, RTTI, terminate<br />
    handlers, etc.<br />
<br />
Note that glibc also has a bits/ subdirectory.  We will either<br />
need to be careful not to collide with names in its bits/<br />
directory; or rename bits to (e.g.) cppbits/.<br />
<br />
In files throughout the system, lines marked with an "XXX" indicate<br />
a bug or incompletely-implemented feature.  Lines marked "XXX MT"<br />
indicate a place that may require attention for multi-thread safety.<br />
  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. Contributing </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Coding Style</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01apd.html 0 → 100644
<?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>Appendix D. GNU General Public License</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="appendix_free.html" title="Appendix C. Free Software Needs Free Documentation" /><link rel="next" href="bk01apds02.html" title="TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix D. GNU General Public License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01apds02.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.gpl-2.0"></a>GNU General Public License</h1></div><div><p class="releaseinfo">Version 2, June 1991</p></div><div><p class="copyright">Copyright © 1989, 1991 Free Software Foundation, Inc.</p></div><div><div class="legalnotice"><a id="gpl-legalnotice"></a><p>
</p><div class="address"><p>Free Software Foundation, Inc. <br />
  <span class="street">51 Franklin Street, Fifth Floor</span>, <br />
  <span class="city">Boston</span>, <span class="state">MA</span> <span class="postcode">02110-1301</span><br />
  <span class="country">USA</span><br />
</p></div><p>
</p><p>Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</p></div></div><div><p class="pubdate">Version 2, June 1991</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="bk01apd.html#gpl-1">Preamble</a></span></dt><dt><span class="section"><a href="bk01apds02.html">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</a></span></dt><dd><dl><dt><span class="section"><a href="bk01apds02.html#gpl-2-0">Section 0</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-1">Section 1</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-2">Section 2</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-3">Section 3</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-4">Section 4</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-5">Section 5</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-6">Section 6</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-7">Section 7</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-8">Section 8</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-9">Section 9</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-10">Section 10</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-11">NO WARRANTY Section 11</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-12">Section 12</a></span></dt></dl></dd><dt><span class="section"><a href="bk01apds03.html">How to Apply These Terms to Your New Programs</a></span></dt></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gpl-1"></a>Preamble</h2></div></div></div><p>The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change
free software - to make sure the software is free for all its users.
This General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit
to using it. (Some other Free Software Foundation software is covered
by the GNU Library General Public License instead.) You can apply it
to your programs, too.</p><p>When we speak of free software, we are referring to freedom, not price.
Our General Public Licenses are designed to make sure that you have the
freedom to distribute copies of free software (and charge for this
service if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.</p><p>To protect your rights, we need to make restrictions that forbid anyone
to deny you these rights or to ask you to surrender the rights. These
restrictions translate to certain responsibilities for you if you distribute
copies of the software, or if you modify it.</p><p>For example, if you distribute copies of such a program, whether gratis or
for a fee, you must give the recipients all the rights that you have. You
must make sure that they, too, receive or can get the source code. And you
must show them these terms so they know their rights.</p><p>We protect your rights with two steps:
</p><div class="orderedlist"><ol type="1"><li><p>copyright the software, and</p></li><li><p>offer you this license which gives you legal permission to copy,
distribute and/or modify the software.</p></li></ol></div><p>
</p><p>Also, for each author's protection and ours, we want to make certain that
everyone understands that there is no warranty for this free software. If
the software is modified by someone else and passed on, we want its
recipients to know that what they have is not the original, so that any
problems introduced by others will not reflect on the original authors'
reputations.</p><p>Finally, any free program is threatened constantly by software patents.
We wish to avoid the danger that redistributors of a free program will
individually obtain patent licenses, in effect making the program
proprietary. To prevent this, we have made it clear that any patent must be
licensed for everyone's free use or not licensed at all.</p><p>The precise terms and conditions for copying, distribution and modification
follow.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apds02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix C. Free Software Needs Free Documentation </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01apds03.html 0 → 100644
<?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>How to Apply These Terms to Your New Programs</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01apd.html" title="Appendix D. GNU General Public License" /><link rel="prev" href="bk01apds02.html" title="TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION" /><link rel="next" href="bk01ape.html" title="Appendix E. GNU Free Documentation License" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">How to Apply These Terms to Your New Programs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apds02.html">Prev</a> </td><th width="60%" align="center">Appendix D. GNU General Public License</th><td width="20%" align="right"> <a accesskey="n" href="bk01ape.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gpl-3"></a>How to Apply These Terms to Your New Programs</h2></div></div></div><p>If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.</p><p>To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the “<span class="quote">copyright</span>” line and a pointer to where the full notice is found.</p><p>&lt;one line to give the program's name and a brief idea of what it does.&gt;
Copyright (C) &lt;year&gt; &lt;name of author&gt;</p><p>This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.</p><p>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</p><p>Also add information on how to contact you by electronic and paper mail.</p><p>If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:</p><p>Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type “<span class="quote">show w</span>”.
This is free software, and you are welcome to redistribute it
under certain conditions; type “<span class="quote">show c</span>” for details.</p><p>The hypothetical commands “<span class="quote">show w</span>” and “<span class="quote">show c</span>” should
show the appropriate parts of the General Public License. Of course, the commands you
use may be called something other than “<span class="quote">show w</span>” and “<span class="quote">show c</span>”;
they could even be mouse-clicks or menu items--whatever suits your program.</p><p>You should also get your employer (if you work as a programmer) or your
school, if any, to sign a “<span class="quote">copyright disclaimer</span>” for the program, if
necessary. Here is a sample; alter the names:</p><p>Yoyodyne, Inc., hereby disclaims all copyright interest in the program
“<span class="quote">Gnomovision</span>” (which makes passes at compilers) written by James Hacker.</p><p>&lt;signature of Ty Coon&gt;, 1 April 1989
Ty Coon, President of Vice</p><p>This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apds02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01apd.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01ape.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix E. GNU Free Documentation License</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt01ch01.html 0 → 100644
This source diff could not be displayed because it is too large. You can view the blob instead.
libstdc++-v3/doc/html/manual/bk01pt01ch01s02.html 0 → 100644
<?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>License</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt01ch01.html" title="Chapter 1. Status" /><link rel="prev" href="bk01pt01ch01.html" title="Chapter 1. Status" /><link rel="next" href="bk01pt01ch01s03.html" title="Bugs" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch01.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch01s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.status.license"></a>License</h2></div></div></div><p>
There are two licenses affecting GNU libstdc++: one for the code,
and one for the documentation.
</p><p>
There is a license section in the FAQ regarding common <a class="link" href="../faq.html#faq.license" title="License">questions</a>. If you have more
questions, ask the FSF or the <a class="ulink" href="http://gcc.gnu.org/lists.html" target="_top">gcc mailing list</a>.
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.gpl"></a>The Code: GPL</h3></div></div></div><p>
The source code is distributed under the <a class="link" href="bk01apd.html" title="Appendix D. GNU General Public License">GNU General Public License version 2</a>,
with the so-called “<span class="quote">Runtime Exception</span>”
as follows (or see any header or implementation file):
</p><div class="literallayout"><p><br />
      As a special exception, you may use this file as part of a free software<br />
      library without restriction.  Specifically, if other files instantiate<br />
      templates or use macros or inline functions from this file, or you compile<br />
      this file and link it with other files to produce an executable, this<br />
      file does not by itself cause the resulting executable to be covered by<br />
      the GNU General Public License.  This exception does not however<br />
      invalidate any other reasons why the executable file might be covered by<br />
      the GNU General Public License.<br />
    </p></div><p>
Hopefully that text is self-explanatory. If it isn't, you need to speak
to your lawyer, or the Free Software Foundation.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.fdl"></a>The Documentation: GPL, FDL</h3></div></div></div><p>
The documentation shipped with the library and made available over
the web, excluding the pages generated from source comments, are
copyrighted by the Free Software Foundation, and placed under the
<a class="link" href="bk01ape.html" title="Appendix E. GNU Free Documentation License"> GNU Free Documentation
License version 1.2</a>. There are no Front-Cover Texts, no
Back-Cover Texts, and no Invariant Sections.
</p><p>
For documentation generated by doxygen or other automated tools
via processing source code comments and markup, the original source
code license applies to the generated files. Thus, the doxygen
documents are licensed <a class="link" href="bk01apd.html" title="Appendix D. GNU General Public License">GPL</a>.
</p><p>
If you plan on making copies of the documentation, please let us know.
We can probably offer suggestions.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt01ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Status </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Bugs</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt01ch03s03.html 0 → 100644
<?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>Namespaces</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s02.html" title="Headers" /><link rel="next" href="bk01pt01ch03s04.html" title="Macros" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s02.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
</p><div class="itemizedlist"><ul type="disc"><li><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namepaces nested
within <code class="code">namespace std</code>, such as <code class="code">namespace
std::tr1</code>.
</p></li><li><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
function APIs supplemental to those required by the ISO C++ Standard,
but necessary for interoperability.
</p></li><li><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
and <code class="code">__gnu_pbds</code>.
</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
One standard requirement is that the library components are defined
in <code class="code">namespace std::</code>. Thus, in order to use these types or
functions, one must do one of two things:
</p><div class="itemizedlist"><ul type="disc"><li><p>put a kind of <span class="emphasis"><em>using-declaration</em></span> in your source
(either <code class="code">using namespace std;</code> or i.e. <code class="code">using
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
</p></li><li><p>use a <span class="emphasis"><em>fully
qualified name</em></span>for each library symbol
(i.e. <code class="code">std::string</code>, <code class="code">std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
</p></li></ul></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.comp"></a>Using Namespace Composition</h3></div></div></div><p>
Best practice in programming suggests sequestering new data or
functionality in a sanely-named, unique namespace whenever
possible. This is considered an advantage over dumping everything in
the global namespace, as then name look-up can be explicitly enabled or
disabled as above, symbols are consistently mangled without repetitive
naming prefixes or macros, etc.
</p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to
adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called
<span class="emphasis"><em>namespace composition</em></span>. This is what happens if
a <span class="emphasis"><em>using</em></span>-declaration is put into a
namespace-definition: the imported symbol(s) gets imported into the
currently active namespace(s). For example:
</p><pre class="programlisting">
namespace gtk
{
using std::string;
using std::tr1::array;
class Window { ... };
}
</pre><p>
In this example, <code class="code">std::string</code> gets imported into
<code class="code">namespace gtk</code>. The result is that use of
<code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification.
As an added bonus,
<code class="code">std::string</code> does not get imported into
the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
<code class="code">using</code>-declarations can wrapped in macros that
are set based on autoconf-tests to either "" or i.e. <code class="code">using
std::string;</code> (depending on whether the system has
libstdc++ in <code class="code">std::</code> or not). (ideas from
<code class="email">&lt;<a class="email" href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>&gt;</code>, Karl Nelson <code class="email">&lt;<a class="email" href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>&gt;</code>)
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch03s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Macros</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt01ch03s04.html 0 → 100644
<?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>Macros</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s03.html" title="Namespaces" /><link rel="next" href="bk01pt01ch03s05.html" title="Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s03.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.macros"></a>Macros</h2></div></div></div><p>All pre-processor switches and configurations are all gathered
in the file <code class="code">c++config.h</code>, which is generated during
the libstdc++ configuration and build process, and included by
files part of the public libstdc++ API. Most of these macros
should not be used by consumers of libstdc++, and are reserved
for internal implementation use. <span class="emphasis"><em>These macros cannot be
redefined</em></span>. However, a select handful of these macro
control libstdc++ extensions and extra features, or provide
versioning information for the API, and are able to be used.
</p><p>All library macros begin with <code class="code">_GLIBCXX_</code> (except for
versions 3.1.x to 3.3.x, which use <code class="code">_GLIBCPP_</code>).
</p><p>Below is the macro which users may check for library version
information. </p><div class="variablelist"><dl><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>The current version of
libstdc++ in compressed ISO date format, form of an unsigned
long. For details on the value of this particular macro for a
particular release, please consult this <a class="ulink" href="abi.html" target="_top">
document</a>.
</p></dd></dl></div><p>Below are the macros which users may change with #define/#undef or
with -D/-U compiler flags. The default state of the symbol is
listed.</p><p>“<span class="quote">Configurable</span>” (or “<span class="quote">Not configurable</span>”) means
that the symbol is initially chosen (or not) based on
--enable/--disable options at library build and configure time
(documented <a class="link" href="bk01pt01ch02.html#manual.intro.setup.configure" title="Configure">here</a>), with the
various --enable/--disable choices being translated to
#define/#undef).
</p><p> <acronym class="acronym">ABI</acronym> means that changing from the default value may
mean changing the <acronym class="acronym">ABI</acronym> of compiled code. In other words, these
choices control code which has already been compiled (i.e., in a
binary such as libstdc++.a/.so). If you explicitly #define or
#undef these macros, the <span class="emphasis"><em>headers</em></span> may see different code
paths, but the <span class="emphasis"><em>libraries</em></span> which you link against will not.
Experimenting with different values with the expectation of
consistent linkage requires changing the config headers before
building/installing the library.
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">_GLIBCXX_DEPRECATED</code></span></dt><dd><p>
Defined by default. Not configurable. ABI-changing. Turning this off
removes older ARM-style iostreams code, and other anachronisms
from the API. This macro is dependent on the version of the
standard being tracked, and as a result may give different results for
<code class="code">-std=c++98</code> and <code class="code">-std=c++0x</code>. This may
be useful in updating old C++ code which no longer meet the
requirements of the language, or for checking current code
against new language standards.
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_FORCE_NEW</code></span></dt><dd><p>
Undefined by default. When defined, memory allocation and
allocators controlled by libstdc++ call operator new/delete
without caching and pooling. Configurable via
<code class="code">--enable-libstdcxx-allocator</code>. ABI-changing.
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_CONCEPT_CHECKS</code></span></dt><dd><p>
Undefined by default. Configurable via
<code class="code">--enable-concept-checks</code>. When defined, performs
compile-time checking on certain template instantiations to
detect violations of the requirements of the standard. This
is described in more detail <a class="ulink" href="../19_diagnostics/howto.html#3" target="_top">here</a>.
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG</code></span></dt><dd><p>
Undefined by default. When defined, compiles
user code using the <a class="ulink" href="../ext/debug.html#safe" target="_top">libstdc++ debug
mode</a>.
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG_PEDANTIC</code></span></dt><dd><p>
Undefined by default. When defined while
compiling with the <a class="ulink" href="../ext/debug.html#safe" target="_top">libstdc++ debug
mode</a>, makes the debug mode extremely picky by making the use
of libstdc++ extensions and libstdc++-specific behavior into
errors.
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_PARALLEL</code></span></dt><dd><p>Undefined by default. When defined, compiles
user code using the <a class="ulink" href="../ext/parallel_mode.html" target="_top">libstdc++ parallel
mode</a>.
</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch03s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt01ch03s06.html 0 → 100644
<?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>Exception Safety</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s05.html" title="Concurrency" /><link rel="next" href="debug.html" title="Debugging Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Exception Safety</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s05.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.exception_safety"></a>Exception Safety</h2></div></div></div><p></p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Concurrency </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Debugging Support</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch04.html 0 → 100644
<?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 4. Types</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02pr01.html" title="" /><link rel="next" href="bk01pt02ch04s02.html" title="Numeric Properties" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02pr01.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch04s02.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.support.types"></a>Chapter 4. Types</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt02ch04.html#manual.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch04s02.html">Numeric Properties</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch04s03.html">NULL</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.support.types.fundamental"></a>Fundamental Types</h2></div></div></div><p>
C++ has the following builtin types:
</p><div class="itemizedlist"><ul type="disc"><li><p>
char
</p></li><li><p>
signed char
</p></li><li><p>
unsigned char
</p></li><li><p>
signed short
</p></li><li><p>
signed int
</p></li><li><p>
signed long
</p></li><li><p>
unsigned short
</p></li><li><p>
unsigned int
</p></li><li><p>
unsigned long
</p></li><li><p>
bool
</p></li><li><p>
wchar_t
</p></li><li><p>
float
</p></li><li><p>
double
</p></li><li><p>
long double
</p></li></ul></div><p>
These fundamental types are always available, without having to
include a header file. These types are exactly the same in
either C++ or in C.
</p><p>
Specializing parts of the library on these types is prohibited:
instead, use a POD.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02pr01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch04s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Numeric Properties</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html 0 → 100644
<?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>Numeric Properties</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02ch04.html" title="Chapter 4. Types" /><link rel="prev" href="bk01pt02ch04.html" title="Chapter 4. Types" /><link rel="next" href="bk01pt02ch04s03.html" title="NULL" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Numeric Properties</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch04.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Types</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch04s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.support.types.numeric_limits"></a>Numeric Properties</h2></div></div></div><p>
The header <code class="filename">limits</code> defines
traits classes to give access to various implementation
defined-aspects of the fundamental types. The traits classes --
fourteen in total -- are all specializations of the template class
<code class="classname">numeric_limits</code>, documented <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html" target="_top">here</a>
and defined as follows:
</p><pre class="programlisting">
template&lt;typename T&gt;
struct class
{
static const bool is_specialized;
static T max() throw();
static T min() throw();
static const int digits;
static const int digits10;
static const bool is_signed;
static const bool is_integer;
static const bool is_exact;
static const int radix;
static T epsilon() throw();
static T round_error() throw();
static const int min_exponent;
static const int min_exponent10;
static const int max_exponent;
static const int max_exponent10;
static const bool has_infinity;
static const bool has_quiet_NaN;
static const bool has_signaling_NaN;
static const float_denorm_style has_denorm;
static const bool has_denorm_loss;
static T infinity() throw();
static T quiet_NaN() throw();
static T denorm_min() throw();
static const bool is_iec559;
static const bool is_bounded;
static const bool is_modulo;
static const bool traps;
static const bool tinyness_before;
static const float_round_style round_style;
};
</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch04s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Types </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> NULL</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html 0 → 100644
<?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>NULL</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02ch04.html" title="Chapter 4. Types" /><link rel="prev" href="bk01pt02ch04s02.html" title="Numeric Properties" /><link rel="next" href="bk01pt02ch05.html" title="Chapter 5. Dynamic Memory" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">NULL</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch04s02.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Types</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.support.types.null"></a>NULL</h2></div></div></div><p>
The only change that might affect people is the type of
<code class="constant">NULL</code>: while it is required to be a macro,
the definition of that macro is <span class="emphasis"><em>not</em></span> allowed
to be <code class="constant">(void*)0</code>, which is often used in C.
</p><p>
For <span class="command"><strong>g++</strong></span>, <code class="constant">NULL</code> is
</p><pre class="programlisting">#define</pre><p>'d to be
<code class="constant">__null</code>, a magic keyword extension of
<span class="command"><strong>g++</strong></span>.
</p><p>
The biggest problem of #defining <code class="constant">NULL</code> to be
something like “<span class="quote">0L</span>” is that the compiler will view
that as a long integer before it views it as a pointer, so
overloading won't do what you expect. (This is why
<span class="command"><strong>g++</strong></span> has a magic extension, so that
<code class="constant">NULL</code> is always a pointer.)
</p><p>In his book <a class="ulink" href="http://www.awprofessional.com/titles/0-201-92488-9/" target="_top"><span class="emphasis"><em>Effective
C++</em></span></a>, Scott Meyers points out that the best way
to solve this problem is to not overload on pointer-vs-integer
types to begin with. He also offers a way to make your own magic
<code class="constant">NULL</code> that will match pointers before it
matches integers.
</p><p>See
<a class="ulink" href="http://www.awprofessional.com/titles/0-201-31015-5/" target="_top">the
Effective C++ CD example</a>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch04s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Numeric Properties </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Dynamic Memory</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch05.html 0 → 100644
<?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 5. Dynamic Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02ch04s03.html" title="NULL" /><link rel="next" href="bk01pt02ch06.html" title="Chapter 6. Termination" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Dynamic Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch04s03.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch06.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.support.memory"></a>Chapter 5. Dynamic Memory</h2></div></div></div><p>
There are six flavors each of <code class="function">new</code> and
<code class="function">delete</code>, so make certain that you're using the right
ones. Here are quickie descriptions of <code class="function">new</code>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
single object form, throwing a
<code class="classname">bad_alloc</code> on errors; this is what most
people are used to using
</p></li><li><p>
Single object "nothrow" form, returning NULL on errors
</p></li><li><p>
Array <code class="function">new</code>, throwing
<code class="classname">bad_alloc</code> on errors
</p></li><li><p>
Array nothrow <code class="function">new</code>, returning
<code class="constant">NULL</code> on errors
</p></li><li><p>
Placement <code class="function">new</code>, which does nothing (like
it's supposed to)
</p></li><li><p>
Placement array <code class="function">new</code>, which also does
nothing
</p></li></ul></div><p>
They are distinguished by the parameters that you pass to them, like
any other overloaded function. The six flavors of <code class="function">delete</code>
are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (They match up for
completeness' sake.)
</p><p>
Remember that it is perfectly okay to call <code class="function">delete</code> on a
NULL pointer! Nothing happens, by definition. That is not the
same thing as deleting a pointer twice.
</p><p>
By default, if one of the “<span class="quote">throwing <code class="function">new</code>s</span>” can't
allocate the memory requested, it tosses an instance of a
<code class="classname">bad_alloc</code> exception (or, technically, some class derived
from it). You can change this by writing your own function (called a
new-handler) and then registering it with <code class="function">set_new_handler()</code>:
</p><pre class="programlisting">
typedef void (*PFV)(void);
static char* safety;
static PFV old_handler;
void my_new_handler ()
{
delete[] safety;
popup_window ("Dude, you are running low on heap memory. You
should, like, close some windows, or something.
The next time you run out, we're gonna burn!");
set_new_handler (old_handler);
return;
}
int main ()
{
safety = new char[500000];
old_handler = set_new_handler (&amp;my_new_handler);
...
}
</pre><p>
<code class="classname">bad_alloc</code> is derived from the base <code class="classname">exception</code>
class defined in Chapter 19.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch04s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">NULL </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Termination</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch06.html 0 → 100644
<?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 6. Termination</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02ch05.html" title="Chapter 5. Dynamic Memory" /><link rel="next" href="bk01pt02ch06s02.html" title="Verbose Terminate Handler" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Termination</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch05.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch06s02.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.support.termination"></a>Chapter 6. Termination</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt02ch06.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch06s02.html">Verbose Terminate Handler</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="support.termination.handlers"></a>Termination Handlers</h2></div></div></div><p>
Not many changes here to <code class="filename">cstdlib</code>. You should note that the
<code class="function">abort()</code> function does not call the
destructors of automatic nor static objects, so if you're
depending on those to do cleanup, it isn't going to happen.
(The functions registered with <code class="function">atexit()</code>
don't get called either, so you can forget about that
possibility, too.)
</p><p>
The good old <code class="function">exit()</code> function can be a bit
funky, too, until you look closer. Basically, three points to
remember are:
</p><div class="orderedlist"><ol type="1"><li><p>
Static objects are destroyed in reverse order of their creation.
</p></li><li><p>
Functions registered with <code class="function">atexit()</code> are called in
reverse order of registration, once per registration call.
(This isn't actually new.)
</p></li><li><p>
The previous two actions are “<span class="quote">interleaved,</span>” that is,
given this pseudocode:
</p><pre class="programlisting">
extern "C or C++" void f1 (void);
extern "C or C++" void f2 (void);
static Thing obj1;
atexit(f1);
static Thing obj2;
atexit(f2);
</pre><p>
then at a call of <code class="function">exit()</code>,
<code class="varname">f2</code> will be called, then
<code class="varname">obj2</code> will be destroyed, then
<code class="varname">f1</code> will be called, and finally
<code class="varname">obj1</code> will be destroyed. If
<code class="varname">f1</code> or <code class="varname">f2</code> allow an
exception to propagate out of them, Bad Things happen.
</p></li></ol></div><p>
Note also that <code class="function">atexit()</code> is only required to store 32
functions, and the compiler/library might already be using some of
those slots. If you think you may run out, we recommend using
the <code class="function">xatexit</code>/<code class="function">xexit</code> combination from <code class="literal">libiberty</code>, which has no such limit.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch06s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Dynamic Memory </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Verbose Terminate Handler</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02ch06s02.html 0 → 100644
<?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>Verbose Terminate Handler</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02ch06.html" title="Chapter 6. Termination" /><link rel="prev" href="bk01pt02ch06.html" title="Chapter 6. Termination" /><link rel="next" href="diagnostics.html" title="Part III. Diagnostics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Verbose Terminate Handler</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch06.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Termination</th><td width="20%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="support.termination.verbose"></a>Verbose Terminate Handler</h2></div></div></div><p>
If you are having difficulty with uncaught exceptions and want a
little bit of help debugging the causes of the core dumps, you can
make use of a GNU extension, the verbose terminate handler.
</p><pre class="programlisting">
#include &lt;exception&gt;
int main()
{
std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
...
throw <em class="replaceable"><code>anything</code></em>;
}
</pre><p>
The <code class="function">__verbose_terminate_handler</code> function
obtains the name of the current exception, attempts to demangle
it, and prints it to stderr. If the exception is derived from
<code class="classname">exception</code> then the output from
<code class="function">what()</code> will be included.
</p><p>
Any replacement termination function is required to kill the
program without returning; this one calls abort.
</p><p>
For example:
</p><pre class="programlisting">
#include &lt;exception&gt;
#include &lt;stdexcept&gt;
struct argument_error : public std::runtime_error
{
argument_error(const std::string&amp; s): std::runtime_error(s) { }
};
int main(int argc)
{
std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
if (argc &gt; 5)
throw argument_error(“<span class="quote">argc is greater than 5!</span>”);
else
throw argc;
}
</pre><p>
With the verbose terminate handler active, this gives:
</p><pre class="screen">
<code class="computeroutput">
% ./a.out
terminate called after throwing a `int'
Aborted
% ./a.out f f f f f f f f f f f
terminate called after throwing an instance of `argument_error'
what(): argc is greater than 5!
Aborted
</code>
</pre><p>
The 'Aborted' line comes from the call to
<code class="function">abort()</code>, of course.
</p><p>
This is the default termination handler; nothing need be done to
use it. To go back to the previous “<span class="quote">silent death</span>”
method, simply include <code class="filename">exception</code> and
<code class="filename">cstdlib</code>, and call
</p><pre class="programlisting">
std::set_terminate(std::abort);
</pre><p>
After this, all calls to <code class="function">terminate</code> will use
<code class="function">abort</code> as the terminate handler.
</p><p>
Note: the verbose terminate handler will attempt to write to
stderr. If your application closes stderr or redirects it to an
inappropriate location,
<code class="function">__verbose_terminate_handler</code> will behave in
an unspecified manner.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02ch06.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Termination </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part III. Diagnostics</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt02pr01.html 0 → 100644
<?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></title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="support.html" title="Part II. Support" /><link rel="next" href="bk01pt02ch04.html" title="Chapter 4. Types" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch04.html">Next</a></td></tr></table><hr /></div><div class="preface" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id394397"></a></h2></div></div></div><p>
This part deals with the functions called and objects created
automatically during the course of a program's existence.
</p><p>
While we can't reproduce the contents of the Standard here (you
need to get your own copy from your nation's member body; see our
homepage for help), we can mention a couple of changes in what
kind of support a C++ program gets from the Standard Library.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. Support </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Types</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt03ch07.html 0 → 100644
<?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 7. Exceptions</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="diagnostics.html" title="Part III. Diagnostics" /><link rel="prev" href="diagnostics.html" title="Part III. Diagnostics" /><link rel="next" href="bk01pt03ch07s02.html" title="Adding Data to Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><th width="60%" align="center">Part III. Diagnostics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch07s02.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.diagnostics.exceptions"></a>Chapter 7. Exceptions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt03ch07.html#manual.diagnostics.exceptions.hierarchy">Exception Classes</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch07s02.html">Adding Data to Exceptions</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch07s03.html">Cancellation</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.diagnostics.exceptions.hierarchy"></a>Exception Classes</h2></div></div></div><p>
All exception objects are defined in one of the standard header
files: <code class="filename">exception</code>,
<code class="filename">stdexcept</code>, <code class="filename">new</code>, and
<code class="filename">typeinfo</code>.
</p><p>
The base exception object is <code class="classname">exception</code>,
located in <code class="filename">exception</code>. This object has no
<code class="classname">string</code> member.
</p><p>
Derived from this are several classes that may have a
<code class="classname">string</code> member: a full heirarchy can be
found in the <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00233.html" target="_top">source documentation</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="diagnostics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch07s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part III. Diagnostics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Adding Data to Exceptions</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html 0 → 100644
<?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>Adding Data to Exceptions</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt03ch07.html" title="Chapter 7. Exceptions" /><link rel="prev" href="bk01pt03ch07.html" title="Chapter 7. Exceptions" /><link rel="next" href="bk01pt03ch07s03.html" title="Cancellation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Adding Data to Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch07.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Exceptions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch07s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.diagnostics.exceptions.data"></a>Adding Data to Exceptions</h2></div></div></div><p>
The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
place). It's good to remember that you can add your own data to
these exceptions when extending the hierarchy:
</p><pre class="programlisting">
struct My_Exception : public std::runtime_error
{
public:
My_Exception (const string&amp; whatarg)
: std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
int errno_at_time_of_throw() const { return e; }
DBID id_of_thing_that_threw() const { return id; }
protected:
int e;
DBID id; // some user-defined type
};
</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt03ch07.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch07s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Exceptions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Cancellation</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html 0 → 100644
<?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>Cancellation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt03ch07.html" title="Chapter 7. Exceptions" /><link rel="prev" href="bk01pt03ch07s02.html" title="Adding Data to Exceptions" /><link rel="next" href="bk01pt03ch08.html" title="Chapter 8. Concept Checking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Cancellation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch07s02.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Exceptions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch08.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.diagnostics.exceptions.cancellation"></a>Cancellation</h2></div></div></div><p>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch07s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt03ch07.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Adding Data to Exceptions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Concept Checking</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt03ch08.html 0 → 100644
<?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 8. Concept Checking</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="diagnostics.html" title="Part III. Diagnostics" /><link rel="prev" href="bk01pt03ch07s03.html" title="Cancellation" /><link rel="next" href="utilities.html" title="Part IV. Utilities" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Concept Checking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch07s03.html">Prev</a> </td><th width="60%" align="center">Part III. Diagnostics</th><td width="20%" align="right"> <a accesskey="n" href="utilities.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.diagnostics.concept_checking"></a>Chapter 8. Concept Checking</h2></div></div></div><p>
In 1999, SGI added “<span class="quote">concept checkers</span>” to their
implementation of the STL: code which checked the template
parameters of instantiated pieces of the STL, in order to insure
that the parameters being used met the requirements of the
standard. For example, the Standard requires that types passed as
template parameters to <code class="classname">vector</code> be
"Assignable" (which means what you think it means). The
checking was done during compilation, and none of the code was
executed at runtime.
</p><p>
Unfortunately, the size of the compiler files grew significantly
as a result. The checking code itself was cumbersome. And bugs
were found in it on more than one occasion.
</p><p>
The primary author of the checking code, Jeremy Siek, had already
started work on a replacement implementation. The new code has been
formally reviewed and accepted into
<a class="ulink" href="http://www.boost.org/libs/concept_check/concept_check.htm" target="_top">the
Boost libraries</a>, and we are pleased to incorporate it into the
GNU C++ library.
</p><p>
The new version imposes a much smaller space overhead on the generated
object file. The checks are also cleaner and easier to read and
understand.
</p><p>
They are off by default for all versions of GCC.
They can be enabled at configure time with
<a class="ulink" href="../configopts.html" target="_top"><code class="literal">--enable-concept-checks</code></a>.
You can enable them on a per-translation-unit basis with
<code class="literal">-D_GLIBCXX_CONCEPT_CHECKS</code>.
</p><p>
Please note that the upcoming C++ standard has first-class
support for template parameter constraints based on concepts in the core
language. This will obviate the need for the library-simulated concept
checking described above.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch07s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="diagnostics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="utilities.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Cancellation </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part IV. Utilities</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt04ch09.html 0 → 100644
<?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 9. Functors</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="utilities.html" title="Part IV. Utilities" /><link rel="next" href="bk01pt04ch10.html" title="Chapter 10. Pairs" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Functors</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt04ch10.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.util.functors"></a>Chapter 9. Functors</h2></div></div></div><p>If you don't know what functors are, you're not alone. Many people
get slightly the wrong idea. In the interest of not reinventing
the wheel, we will refer you to the introduction to the functor
concept written by SGI as part of their STL, in
<a class="ulink" href="http://www.sgi.com/tech/stl/functors.html" target="_top">their
http://www.sgi.com/tech/stl/functors.html</a>.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt04ch10.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part IV. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Pairs</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt04ch10.html 0 → 100644
<?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 10. Pairs</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="bk01pt04ch09.html" title="Chapter 9. Functors" /><link rel="next" href="bk01pt04ch11.html" title="Chapter 11. Memory" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. Pairs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt04ch09.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt04ch11.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.util.pairs"></a>Chapter 10. Pairs</h2></div></div></div><p>The <code class="code">pair&lt;T1,T2&gt;</code> is a simple and handy way to
carry around a pair of objects. One is of type T1, and another of
type T2; they may be the same type, but you don't get anything
extra if they are. The two members can be accessed directly, as
<code class="code">.first</code> and <code class="code">.second</code>.
</p><p>Construction is simple. The default ctor initializes each member
with its respective default ctor. The other simple ctor,
</p><pre class="programlisting">
pair (const T1&amp; x, const T2&amp; y);
</pre><p>does what you think it does, <code class="code">first</code> getting <code class="code">x</code>
and <code class="code">second</code> getting <code class="code">y</code>.
</p><p>There is a copy constructor, but it requires that your compiler
handle member function templates:
</p><pre class="programlisting">
template &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; p);
</pre><p>The compiler will convert as necessary from U to T1 and from
V to T2 in order to perform the respective initializations.
</p><p>The comparison operators are done for you. Equality
of two <code class="code">pair&lt;T1,T2&gt;</code>s is defined as both <code class="code">first</code>
members comparing equal and both <code class="code">second</code> members comparing
equal; this simply delegates responsibility to the respective
<code class="code">operator==</code> functions (for types like MyClass) or builtin
comparisons (for types like int, char, etc).
</p><p>
The less-than operator is a bit odd the first time you see it. It
is defined as evaluating to:
</p><pre class="programlisting">
x.first &lt; y.first ||
( !(y.first &lt; x.first) &amp;&amp; x.second &lt; y.second )
</pre><p>The other operators are not defined using the <code class="code">rel_ops</code>
functions above, but their semantics are the same.
</p><p>Finally, there is a template function called <code class="function">make_pair</code>
that takes two references-to-const objects and returns an
instance of a pair instantiated on their respective types:
</p><pre class="programlisting">
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt04ch09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt04ch11.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Functors </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. Memory</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt04ch12.html 0 → 100644
<?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 12. Traits</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="shared_ptr.html" title="shared_ptr" /><link rel="next" href="strings.html" title="Part V. Strings" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. Traits</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="shared_ptr.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="strings.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.util.traits"></a>Chapter 12. Traits</h2></div></div></div><p>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="shared_ptr.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="strings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">shared_ptr </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part V. Strings</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13.html 0 → 100644
<?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 13. String Classes</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="strings.html" title="Part V. Strings" /><link rel="prev" href="strings.html" title="Part V. Strings" /><link rel="next" href="bk01pt05ch13s02.html" title="Case Sensivitity" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. String Classes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="strings.html">Prev</a> </td><th width="60%" align="center">Part V. Strings</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt05ch13s02.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.strings.string"></a>Chapter 13. String Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt05ch13.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="sect1"><a href="bk01pt05ch13s02.html">Case Sensivitity</a></span></dt><dt><span class="sect1"><a href="bk01pt05ch13s03.html">Arbitrary Character Types</a></span></dt><dt><span class="sect1"><a href="bk01pt05ch13s04.html">Tokenizing</a></span></dt><dt><span class="sect1"><a href="bk01pt05ch13s05.html">Shrink to Fit</a></span></dt><dt><span class="sect1"><a href="bk01pt05ch13s06.html">CString (MFC)</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.simple"></a>Simple Transformations</h2></div></div></div><p>
Here are Standard, simple, and portable ways to perform common
transformations on a <code class="code">string</code> instance, such as
"convert to all upper case." The word transformations
is especially apt, because the standard template function
<code class="code">transform&lt;&gt;</code> is used.
</p><p>
This code will go through some iterations. Here's a simiple
version:
</p><pre class="programlisting">
#include &lt;string&gt;
#include &lt;algorithm&gt;
#include &lt;cctype&gt; // old &lt;ctype.h&gt;
struct ToLower
{
char operator() (char c) const { return std::tolower(c); }
};
struct ToUpper
{
char operator() (char c) const { return std::toupper(c); }
};
int main()
{
std::string s ("Some Kind Of Initial Input Goes Here");
// Change everything into upper case
std::transform (s.begin(), s.end(), s.begin(), ToUpper());
// Change everything into lower case
std::transform (s.begin(), s.end(), s.begin(), ToLower());
// Change everything back into upper case, but store the
// result in a different string
std::string capital_s;
capital_s.resize(s.size());
std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
}
</pre><p>
<span class="emphasis"><em>Note</em></span> that these calls all
involve the global C locale through the use of the C functions
<code class="code">toupper/tolower</code>. This is absolutely guaranteed to work --
but <span class="emphasis"><em>only</em></span> if the string contains <span class="emphasis"><em>only</em></span> characters
from the basic source character set, and there are <span class="emphasis"><em>only</em></span>
96 of those. Which means that not even all English text can be
represented (certain British spellings, proper names, and so forth).
So, if all your input forevermore consists of only those 96
characters (hahahahahaha), then you're done.
</p><p><span class="emphasis"><em>Note</em></span> that the
<code class="code">ToUpper</code> and <code class="code">ToLower</code> function objects
are needed because <code class="code">toupper</code> and <code class="code">tolower</code>
are overloaded names (declared in <code class="code">&lt;cctype&gt;</code> and
<code class="code">&lt;locale&gt;</code>) so the template-arguments for
<code class="code">transform&lt;&gt;</code> cannot be deduced, as explained in
<a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html" target="_top">this
message</a>.
At minimum, you can write short wrappers like
</p><pre class="programlisting">
char toLower (char c)
{
return std::tolower(c);
} </pre><p>The correct method is to use a facet for a particular locale
and call its conversion functions. These are discussed more in
Chapter 22; the specific part is
<a class="ulink" href="../22_locale/howto.html#7" target="_top">Correct Transformations</a>,
which shows the final version of this code. (Thanks to James Kanze
for assistance and suggestions on all of this.)
</p><p>Another common operation is trimming off excess whitespace. Much
like transformations, this task is trivial with the use of string's
<code class="code">find</code> family. These examples are broken into multiple
statements for readability:
</p><pre class="programlisting">
std::string str (" \t blah blah blah \n ");
// trim leading whitespace
string::size_type notwhite = str.find_first_not_of(" \t\n");
str.erase(0,notwhite);
// trim trailing whitespace
notwhite = str.find_last_not_of(" \t\n");
str.erase(notwhite+1); </pre><p>Obviously, the calls to <code class="code">find</code> could be inserted directly
into the calls to <code class="code">erase</code>, in case your compiler does not
optimize named temporaries out of existence.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="strings.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="strings.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt05ch13s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part V. Strings </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Case Sensivitity</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html 0 → 100644
<?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>Case Sensivitity</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="prev" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="next" href="bk01pt05ch13s03.html" title="Arbitrary Character Types" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Case Sensivitity</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13.html">Prev</a> </td><th width="60%" align="center">Chapter 13. String Classes</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt05ch13s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.case"></a>Case Sensivitity</h2></div></div></div><p>
</p><p>The well-known-and-if-it-isn't-well-known-it-ought-to-be
<a class="ulink" href="http://www.gotw.ca/gotw/" target="_top">Guru of the Week</a>
discussions held on Usenet covered this topic in January of 1998.
Briefly, the challenge was, “<span class="quote">write a 'ci_string' class which
is identical to the standard 'string' class, but is
case-insensitive in the same way as the (common but nonstandard)
C function stricmp()</span>”.
</p><pre class="programlisting">
ci_string s( "AbCdE" );
// case insensitive
assert( s == "abcde" );
assert( s == "ABCDE" );
// still case-preserving, of course
assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre><p>The solution is surprisingly easy. The original answer was
posted on Usenet, and a revised version appears in Herb Sutter's
book <span class="emphasis"><em>Exceptional C++</em></span> and on his website as <a class="ulink" href="http://www.gotw.ca/gotw/029.htm" target="_top">GotW 29</a>.
</p><p>See? Told you it was easy!</p><p>
<span class="emphasis"><em>Added June 2000:</em></span> The May 2000 issue of C++
Report contains a fascinating <a class="ulink" href="http://lafstern.org/matt/col2_new.pdf" target="_top"> article</a> by
Matt Austern (yes, <span class="emphasis"><em>the</em></span> Matt Austern) on why
case-insensitive comparisons are not as easy as they seem, and
why creating a class is the <span class="emphasis"><em>wrong</em></span> way to go
about it in production code. (The GotW answer mentions one of
the principle difficulties; his article mentions more.)
</p><p>Basically, this is "easy" only if you ignore some things,
things which may be too important to your program to ignore. (I chose
to ignore them when originally writing this entry, and am surprised
that nobody ever called me on it...) The GotW question and answer
remain useful instructional tools, however.
</p><p><span class="emphasis"><em>Added September 2000:</em></span> James Kanze provided a link to a
<a class="ulink" href="http://www.unicode.org/unicode/reports/tr21/" target="_top">Unicode
Technical Report discussing case handling</a>, which provides some
very good information.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt05ch13.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt05ch13s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. String Classes </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Arbitrary Character Types</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html 0 → 100644
<?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>Arbitrary Character Types</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="prev" href="bk01pt05ch13s02.html" title="Case Sensivitity" /><link rel="next" href="bk01pt05ch13s04.html" title="Tokenizing" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Arbitrary Character Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13s02.html">Prev</a> </td><th width="60%" align="center">Chapter 13. String Classes</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt05ch13s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.character_types"></a>Arbitrary Character Types</h2></div></div></div><p>
</p><p>The <code class="code">std::basic_string</code> is tantalizingly general, in that
it is parameterized on the type of the characters which it holds.
In theory, you could whip up a Unicode character class and instantiate
<code class="code">std::basic_string&lt;my_unicode_char&gt;</code>, or assuming
that integers are wider than characters on your platform, maybe just
declare variables of type <code class="code">std::basic_string&lt;int&gt;</code>.
</p><p>That's the theory. Remember however that basic_string has additional
type parameters, which take default arguments based on the character
type (called <code class="code">CharT</code> here):
</p><pre class="programlisting">
template &lt;typename CharT,
typename Traits = char_traits&lt;CharT&gt;,
typename Alloc = allocator&lt;CharT&gt; &gt;
class basic_string { .... };</pre><p>Now, <code class="code">allocator&lt;CharT&gt;</code> will probably Do The Right
Thing by default, unless you need to implement your own allocator
for your characters.
</p><p>But <code class="code">char_traits</code> takes more work. The char_traits
template is <span class="emphasis"><em>declared</em></span> but not <span class="emphasis"><em>defined</em></span>.
That means there is only
</p><pre class="programlisting">
template &lt;typename CharT&gt;
struct char_traits
{
static void foo (type1 x, type2 y);
...
};</pre><p>and functions such as char_traits&lt;CharT&gt;::foo() are not
actually defined anywhere for the general case. The C++ standard
permits this, because writing such a definition to fit all possible
CharT's cannot be done.
</p><p>The C++ standard also requires that char_traits be specialized for
instantiations of <code class="code">char</code> and <code class="code">wchar_t</code>, and it
is these template specializations that permit entities like
<code class="code">basic_string&lt;char,char_traits&lt;char&gt;&gt;</code> to work.
</p><p>If you want to use character types other than char and wchar_t,
such as <code class="code">unsigned char</code> and <code class="code">int</code>, you will
need suitable specializations for them. For a time, in earlier
versions of GCC, there was a mostly-correct implementation that
let programmers be lazy but it broke under many situations, so it
was removed. GCC 3.4 introduced a new implementation that mostly
works and can be specialized even for <code class="code">int</code> and other
built-in types.
</p><p>If you want to use your own special character class, then you have
<a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html" target="_top">a lot
of work to do</a>, especially if you with to use i18n features
(facets require traits information but don't have a traits argument).
</p><p>Another example of how to specialize char_traits was given <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html" target="_top">on the
mailing list</a> and at a later date was put into the file <code class="code">
include/ext/pod_char_traits.h</code>. We agree
that the way it's used with basic_string (scroll down to main())
doesn't look nice, but that's because <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html" target="_top">the
nice-looking first attempt</a> turned out to <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html" target="_top">not
be conforming C++</a>, due to the rule that CharT must be a POD.
(See how tricky this is?)
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt05ch13.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt05ch13s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Case Sensivitity </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Tokenizing</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html 0 → 100644
<?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>Tokenizing</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="prev" href="bk01pt05ch13s03.html" title="Arbitrary Character Types" /><link rel="next" href="bk01pt05ch13s05.html" title="Shrink to Fit" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Tokenizing</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13s03.html">Prev</a> </td><th width="60%" align="center">Chapter 13. String Classes</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt05ch13s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.token"></a>Tokenizing</h2></div></div></div><p>
</p><p>The Standard C (and C++) function <code class="code">strtok()</code> leaves a lot to
be desired in terms of user-friendliness. It's unintuitive, it
destroys the character string on which it operates, and it requires
you to handle all the memory problems. But it does let the client
code decide what to use to break the string into pieces; it allows
you to choose the "whitespace," so to speak.
</p><p>A C++ implementation lets us keep the good things and fix those
annoyances. The implementation here is more intuitive (you only
call it once, not in a loop with varying argument), it does not
affect the original string at all, and all the memory allocation
is handled for you.
</p><p>It's called stringtok, and it's a template function. Sources are
as below, in a less-portable form than it could be, to keep this
example simple (for example, see the comments on what kind of
string it will accept).
</p><pre class="programlisting">
#include &lt;string&gt;
template &lt;typename Container&gt;
void
stringtok(Container &amp;container, string const &amp;in,
const char * const delimiters = " \t\n")
{
const string::size_type len = in.length();
string::size_type i = 0;
while (i &lt; len)
{
// Eat leading whitespace
i = in.find_first_not_of(delimiters, i);
if (i == string::npos)
return; // Nothing left but white space
// Find the end of the token
string::size_type j = in.find_first_of(delimiters, i);
// Push token
if (j == string::npos)
{
container.push_back(in.substr(i));
return;
}
else
container.push_back(in.substr(i, j-i));
// Set up for next loop
i = j + 1;
}
}
</pre><p>
The author uses a more general (but less readable) form of it for
parsing command strings and the like. If you compiled and ran this
code using it:
</p><pre class="programlisting">
std::list&lt;string&gt; ls;
stringtok (ls, " this \t is\t\n a test ");
for (std::list&lt;string&gt;const_iterator i = ls.begin();
i != ls.end(); ++i)
{
std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n";
} </pre><p>You would see this as output:
</p><pre class="programlisting">
:this:
:is:
:a:
:test: </pre><p>with all the whitespace removed. The original <code class="code">s</code> is still
available for use, <code class="code">ls</code> will clean up after itself, and
<code class="code">ls.size()</code> will return how many tokens there were.
</p><p>As always, there is a price paid here, in that stringtok is not
as fast as strtok. The other benefits usually outweigh that, however.
<a class="ulink" href="stringtok_std_h.txt" target="_top">Another version of stringtok is given
here</a>, suggested by Chris King and tweaked by Petr Prikryl,
and this one uses the
transformation functions mentioned below. If you are comfortable
with reading the new function names, this version is recommended
as an example.
</p><p><span class="emphasis"><em>Added February 2001:</em></span> Mark Wilden pointed out that the
standard <code class="code">std::getline()</code> function can be used with standard
<a class="ulink" href="../27_io/howto.html" target="_top">istringstreams</a> to perform
tokenizing as well. Build an istringstream from the input text,
and then use std::getline with varying delimiters (the three-argument
signature) to extract tokens into a string.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt05ch13.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt05ch13s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Arbitrary Character Types </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Shrink to Fit</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html 0 → 100644
<?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>Shrink to Fit</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="prev" href="bk01pt05ch13s04.html" title="Tokenizing" /><link rel="next" href="bk01pt05ch13s06.html" title="CString (MFC)" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Shrink to Fit</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13s04.html">Prev</a> </td><th width="60%" align="center">Chapter 13. String Classes</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt05ch13s06.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.shrink"></a>Shrink to Fit</h2></div></div></div><p>
</p><p>From GCC 3.4 calling <code class="code">s.reserve(res)</code> on a
<code class="code">string s</code> with <code class="code">res &lt; s.capacity()</code> will
reduce the string's capacity to <code class="code">std::max(s.size(), res)</code>.
</p><p>This behaviour is suggested, but not required by the standard. Prior
to GCC 3.4 the following alternative can be used instead
</p><pre class="programlisting">
std::string(str.data(), str.size()).swap(str);
</pre><p>This is similar to the idiom for reducing a <code class="code">vector</code>'s
memory usage (see <a class="ulink" href="../faq/index.html#5_9" target="_top">FAQ 5.9</a>) but
the regular copy constructor cannot be used because libstdc++'s
<code class="code">string</code> is Copy-On-Write.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt05ch13.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt05ch13s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Tokenizing </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> CString (MFC)</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html 0 → 100644
<?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>CString (MFC)</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt05ch13.html" title="Chapter 13. String Classes" /><link rel="prev" href="bk01pt05ch13s05.html" title="Shrink to Fit" /><link rel="next" href="localization.html" title="Part VI. Localization" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">CString (MFC)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13s05.html">Prev</a> </td><th width="60%" align="center">Chapter 13. String Classes</th><td width="20%" align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.Cstring"></a>CString (MFC)</h2></div></div></div><p>
</p><p>A common lament seen in various newsgroups deals with the Standard
string class as opposed to the Microsoft Foundation Class called
CString. Often programmers realize that a standard portable
answer is better than a proprietary nonportable one, but in porting
their application from a Win32 platform, they discover that they
are relying on special functions offered by the CString class.
</p><p>Things are not as bad as they seem. In
<a class="ulink" href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html" target="_top">this
message</a>, Joe Buck points out a few very important things:
</p><div class="itemizedlist"><ul type="disc"><li><p>The Standard <code class="code">string</code> supports all the operations
that CString does, with three exceptions.
</p></li><li><p>Two of those exceptions (whitespace trimming and case
conversion) are trivial to implement. In fact, we do so
on this page.
</p></li><li><p>The third is <code class="code">CString::Format</code>, which allows formatting
in the style of <code class="code">sprintf</code>. This deserves some mention:
</p></li></ul></div><p>
The old libg++ library had a function called form(), which did much
the same thing. But for a Standard solution, you should use the
stringstream classes. These are the bridge between the iostream
hierarchy and the string class, and they operate with regular
streams seamlessly because they inherit from the iostream
hierarchy. An quick example:
</p><pre class="programlisting">
#include &lt;iostream&gt;
#include &lt;string&gt;
#include &lt;sstream&gt;
string f (string&amp; incoming) // incoming is "foo N"
{
istringstream incoming_stream(incoming);
string the_word;
int the_number;
incoming_stream &gt;&gt; the_word // extract "foo"
&gt;&gt; the_number; // extract N
ostringstream output_stream;
output_stream &lt;&lt; "The word was " &lt;&lt; the_word
&lt;&lt; " and 3*N was " &lt;&lt; (3*the_number);
return output_stream.str();
} </pre><p>A serious problem with CString is a design bug in its memory
allocation. Specifically, quoting from that same message:
</p><pre class="programlisting">
CString suffers from a common programming error that results in
poor performance. Consider the following code:
CString n_copies_of (const CString&amp; foo, unsigned n)
{
CString tmp;
for (unsigned i = 0; i &lt; n; i++)
tmp += foo;
return tmp;
}
This function is O(n^2), not O(n). The reason is that each +=
causes a reallocation and copy of the existing string. Microsoft
applications are full of this kind of thing (quadratic performance
on tasks that can be done in linear time) -- on the other hand,
we should be thankful, as it's created such a big market for high-end
ix86 hardware. :-)
If you replace CString with string in the above function, the
performance is O(n).
</pre><p>Joe Buck also pointed out some other things to keep in mind when
comparing CString and the Standard string class:
</p><div class="itemizedlist"><ul type="disc"><li><p>CString permits access to its internal representation; coders
who exploited that may have problems moving to <code class="code">string</code>.
</p></li><li><p>Microsoft ships the source to CString (in the files
MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation
bug and rebuild your MFC libraries.
<span class="emphasis"><em><span class="emphasis"><em>Note:</em></span> It looks like the CString shipped
with VC++6.0 has fixed this, although it may in fact have been
one of the VC++ SPs that did it.</em></span>
</p></li><li><p><code class="code">string</code> operations like this have O(n) complexity
<span class="emphasis"><em>if the implementors do it correctly</em></span>. The libstdc++
implementors did it correctly. Other vendors might not.
</p></li><li><p>While parts of the SGI STL are used in libstdc++, their
string class is not. The SGI <code class="code">string</code> is essentially
<code class="code">vector&lt;char&gt;</code> and does not do any reference
counting like libstdc++'s does. (It is O(n), though.)
So if you're thinking about SGI's string or rope classes,
you're now looking at four possibilities: CString, the
libstdc++ string, the SGI string, and the SGI rope, and this
is all before any allocator or traits customizations! (More
choices than you can shake a stick at -- want fries with that?)
</p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt05ch13.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="localization.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Shrink to Fit </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part VI. Localization</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt06ch15.html 0 → 100644
<?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 15. Facets aka Categories</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Part VI. Localization" /><link rel="prev" href="bk01pt06ch14.html" title="Chapter 14. Locales" /><link rel="next" href="codecvt.html" title="codecvt" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 15. Facets aka Categories</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt06ch14.html">Prev</a> </td><th width="60%" align="center">Part VI. Localization</th><td width="20%" align="right"> <a accesskey="n" href="codecvt.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.localization.facet"></a>Chapter 15. Facets aka Categories</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt06ch15.html#manual.localization.facet.ctype">ctype</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt06ch15.html#facet.ctype.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="bk01pt06ch15.html#facet.ctype.future">Future</a></span></dt></dl></dd><dt><span class="sect1"><a href="codecvt.html">codecvt</a></span></dt><dd><dl><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.req">Requirements</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.design">Design</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.use">Use</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.future">Future</a></span></dt></dl></dd><dt><span class="sect1"><a href="messages.html">messages</a></span></dt><dd><dl><dt><span class="sect2"><a href="messages.html#facet.messages.req">Requirements</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.design">Design</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.use">Use</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.future">Future</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.facet.ctype"></a>ctype</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id424267"></a>Specializations</h4></div></div></div><p>
For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements.
</p><p>
The two required specializations are implemented as follows:
</p><p>
<code class="code">
ctype&lt;char&gt;
</code>
</p><p>
This is simple specialization. Implementing this was a piece of cake.
</p><p>
<code class="code">
ctype&lt;wchar_t&gt;
</code>
</p><p>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p><p>
Neither of these two required specializations deals with Unicode
characters.
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
How to deal with the global locale issue?
</p></li><li><p>
How to deal with different types than char, wchar_t? </p></li><li><p>
Overlap between codecvt/ctype: narrow/widen
</p></li><li><p>
Mask typedef in codecvt_base, argument types in codecvt. what
is know about this type?
</p></li><li><p>
Why mask* argument in codecvt?
</p></li><li><p>
Can this be made (more) generic? is there a simple way to
straighten out the configure-time mess that is a by-product of
this class?
</p></li><li><p>
Get the ctype&lt;wchar_t&gt;::mask stuff under control. Need to
make some kind of static table, and not do lookup evertime
somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt;
</p></li><li><p>
Rename abstract base class. See if just smash-overriding is a
better approach. Clarify, add sanity to naming.
</p></li></ul></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id428438"></a><p><span class="title"><i>
The GNU C Library
</i>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling and 7 Locales and Internationalization. </span></p></div><div class="biblioentry"><a id="id406217"></a><p><span class="title"><i>
Correspondence
</i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id406246"></a><p><span class="title"><i>
ISO/IEC 14882:1998 Programming languages - C++
</i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id424106"></a><p><span class="title"><i>
ISO/IEC 9899:1999 Programming languages - C
</i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id424124"></a><p><span class="title"><i>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
</i>. </span><span class="copyright">Copyright © 1999
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid">
<a class="ulink" href="http://www.opennc.org/austin/docreg.html" target="_top">
</a>
. </span></p></div><div class="biblioentry"><a id="id483804"></a><p><span class="title"><i>
The C++ Programming Language, Special Edition
</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername">
Addison Wesley
. </span></span></p></div><div class="biblioentry"><a id="id428016"></a><p><span class="title"><i>
Standard C++ IOStreams and Locales
</i>. </span><span class="subtitle">
Advanced Programmer's Guide and Reference
. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername">
Addison Wesley Longman
. </span></span></p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt06ch14.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="localization.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="codecvt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. Locales </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> codecvt</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt07ch16.html 0 → 100644
<?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 16. Sequences</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="containers.html" title="Part VII. Containers" /><link rel="next" href="bk01pt07ch16s02.html" title="vector" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. Sequences</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="containers.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch16s02.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.containers.sequences"></a>Chapter 16. Sequences</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch16.html#containers.sequences.list">list</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch16.html#sequences.list.size">list::size() is O(n)</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt07ch16s02.html">vector</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch16s02.html#sequences.vector.management">Space Overhead Management</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.sequences.list"></a>list</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sequences.list.size"></a>list::size() is O(n)</h3></div></div></div><p>
Yes it is, and that's okay. This is a decision that we preserved
when we imported SGI's STL implementation. The following is
quoted from <a class="ulink" href="http://www.sgi.com/tech/stl/FAQ.html" target="_top">their FAQ</a>:
</p><div class="blockquote"><blockquote class="blockquote"><p>
The size() member function, for list and slist, takes time
proportional to the number of elements in the list. This was a
deliberate tradeoff. The only way to get a constant-time
size() for linked lists would be to maintain an extra member
variable containing the list's size. This would require taking
extra time to update that variable (it would make splice() a
linear time operation, for example), and it would also make the
list larger. Many list algorithms don't require that extra
word (algorithms that do require it might do better with
vectors than with lists), and, when it is necessary to maintain
an explicit size count, it's something that users can do
themselves.
</p><p>
This choice is permitted by the C++ standard. The standard says
that size() “<span class="quote">should</span>” be constant time, and
“<span class="quote">should</span>” does not mean the same thing as
“<span class="quote">shall</span>”. This is the officially recommended ISO
wording for saying that an implementation is supposed to do
something unless there is a good reason not to.
</p><p>
One implication of linear time size(): you should never write
</p><pre class="programlisting">
if (L.size() == 0)
...
</pre><p>
Instead, you should write
</p><pre class="programlisting">
if (L.empty())
...
</pre></blockquote></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="containers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch16s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VII. Containers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> vector</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt07ch16s02.html 0 → 100644
<?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>vector</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt07ch16.html" title="Chapter 16. Sequences" /><link rel="prev" href="bk01pt07ch16.html" title="Chapter 16. Sequences" /><link rel="next" href="bk01pt07ch17.html" title="Chapter 17. Associative" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">vector</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch16.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Sequences</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch17.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.sequences.vector"></a>vector</h2></div></div></div><p>
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sequences.vector.management"></a>Space Overhead Management</h3></div></div></div><p>
In <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html" target="_top">this
message to the list</a>, Daniel Kostecky announced work on an
alternate form of <code class="code">std::vector</code> that would support
hints on the number of elements to be over-allocated. The design
was also described, along with possible implementation choices.
</p><p>
The first two alpha releases were announced <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html" target="_top">here</a>
and <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html" target="_top">here</a>.
The releases themselves are available at
<a class="ulink" href="http://www.kotelna.sk/dk/sw/caphint/" target="_top">
http://www.kotelna.sk/dk/sw/caphint/</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch16.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt07ch16.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch17.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16. Sequences </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 17. Associative</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt07ch17.html 0 → 100644
<?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 17. Associative</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="bk01pt07ch16s02.html" title="vector" /><link rel="next" href="bk01pt07ch17s02.html" title="bitset" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 17. Associative</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch16s02.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch17s02.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.containers.associative"></a>Chapter 17. Associative</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch17.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect1"><a href="bk01pt07ch17s02.html">bitset</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch17s02.html#associative.bitset.size_variable">Size Variable</a></span></dt><dt><span class="sect2"><a href="bk01pt07ch17s02.html#associative.bitset.type_string">Type String</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.associative.insert_hints"></a>Insertion Hints</h2></div></div></div><p>
Section [23.1.2], Table 69, of the C++ standard lists this
function for all of the associative containers (map, set, etc):
</p><pre class="programlisting">
a.insert(p,t);
</pre><p>
where 'p' is an iterator into the container 'a', and 't' is the
item to insert. The standard says that “<span class="quote"><code class="code">t</code> is
inserted as close as possible to the position just prior to
<code class="code">p</code>.</span>” (Library DR #233 addresses this topic,
referring to <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html" target="_top">N1780</a>.
Since version 4.2 GCC implements the resolution to DR 233, so
that insertions happen as close as possible to the hint. For
earlier releases the hint was only used as described below.
</p><p>
Here we'll describe how the hinting works in the libstdc++
implementation, and what you need to do in order to take
advantage of it. (Insertions can change from logarithmic
complexity to amortized constant time, if the hint is properly
used.) Also, since the current implementation is based on the
SGI STL one, these points may hold true for other library
implementations also, since the HP/SGI code is used in a lot of
places.
</p><p>
In the following text, the phrases <span class="emphasis"><em>greater
than</em></span> and <span class="emphasis"><em>less than</em></span> refer to the
results of the strict weak ordering imposed on the container by
its comparison object, which defaults to (basically)
“<span class="quote">&lt;</span>”. Using those phrases is semantically sloppy,
but I didn't want to get bogged down in syntax. I assume that if
you are intelligent enough to use your own comparison objects,
you are also intelligent enough to assign “<span class="quote">greater</span>”
and “<span class="quote">lesser</span>” their new meanings in the next
paragraph. *grin*
</p><p>
If the <code class="code">hint</code> parameter ('p' above) is equivalent to:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="code">begin()</code>, then the item being inserted should
have a key less than all the other keys in the container.
The item will be inserted at the beginning of the container,
becoming the new entry at <code class="code">begin()</code>.
</p></li><li><p>
<code class="code">end()</code>, then the item being inserted should have
a key greater than all the other keys in the container. The
item will be inserted at the end of the container, becoming
the new entry at <code class="code">end()</code>.
</p></li><li><p>
neither <code class="code">begin()</code> nor <code class="code">end()</code>, then:
Let <code class="code">h</code> be the entry in the container pointed to
by <code class="code">hint</code>, that is, <code class="code">h = *hint</code>. Then
the item being inserted should have a key less than that of
<code class="code">h</code>, and greater than that of the item preceding
<code class="code">h</code>. The new item will be inserted between
<code class="code">h</code> and <code class="code">h</code>'s predecessor.
</p></li></ul></div><p>
For <code class="code">multimap</code> and <code class="code">multiset</code>, the
restrictions are slightly looser: “<span class="quote">greater than</span>”
should be replaced by “<span class="quote">not less than</span>”and “<span class="quote">less
than</span>” should be replaced by “<span class="quote">not greater
than.</span>” (Why not replace greater with
greater-than-or-equal-to? You probably could in your head, but
the mathematicians will tell you that it isn't the same thing.)
</p><p>
If the conditions are not met, then the hint is not used, and the
insertion proceeds as if you had called <code class="code"> a.insert(t)
</code> instead. (<span class="emphasis"><em>Note </em></span> that GCC releases
prior to 3.0.2 had a bug in the case with <code class="code">hint ==
begin()</code> for the <code class="code">map</code> and <code class="code">set</code>
classes. You should not use a hint argument in those releases.)
</p><p>
This behavior goes well with other containers'
<code class="code">insert()</code> functions which take an iterator: if used,
the new item will be inserted before the iterator passed as an
argument, same as the other containers.
</p><p>
<span class="emphasis"><em>Note </em></span> also that the hint in this
implementation is a one-shot. The older insertion-with-hint
routines check the immediately surrounding entries to ensure that
the new item would in fact belong there. If the hint does not
point to the correct place, then no further local searching is
done; the search begins from scratch in logarithmic time.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch16s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch17s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">vector </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> bitset</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt07ch17s02.html 0 → 100644
<?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>bitset</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt07ch17.html" title="Chapter 17. Associative" /><link rel="prev" href="bk01pt07ch17.html" title="Chapter 17. Associative" /><link rel="next" href="bk01pt07ch18.html" title="Chapter 18. Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bitset</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch17.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Associative</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch18.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.associative.bitset"></a>bitset</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="associative.bitset.size_variable"></a>Size Variable</h3></div></div></div><p>
No, you cannot write code of the form
</p><pre class="programlisting">
#include &lt;bitset&gt;
void foo (size_t n)
{
std::bitset&lt;n&gt; bits;
....
}
</pre><p>
because <code class="code">n</code> must be known at compile time. Your
compiler is correct; it is not a bug. That's the way templates
work. (Yes, it <span class="emphasis"><em>is</em></span> a feature.)
</p><p>
There are a couple of ways to handle this kind of thing. Please
consider all of them before passing judgement. They include, in
no particular order:
</p><div class="itemizedlist"><ul type="disc"><li><p>A very large N in <code class="code">bitset&lt;N&gt;</code>.</p></li><li><p>A container&lt;bool&gt;.</p></li><li><p>Extremely weird solutions.</p></li></ul></div><p>
<span class="emphasis"><em>A very large N in
<code class="code">bitset&lt;N&gt;</code>.  </em></span> It has been
pointed out a few times in newsgroups that N bits only takes up
(N/8) bytes on most systems, and division by a factor of eight is
pretty impressive when speaking of memory. Half a megabyte given
over to a bitset (recall that there is zero space overhead for
housekeeping info; it is known at compile time exactly how large
the set is) will hold over four million bits. If you're using
those bits as status flags (e.g.,
“<span class="quote">changed</span>”/“<span class="quote">unchanged</span>” flags), that's a
<span class="emphasis"><em>lot</em></span> of state.
</p><p>
You can then keep track of the “<span class="quote">maximum bit used</span>”
during some testing runs on representative data, make note of how
many of those bits really need to be there, and then reduce N to
a smaller number. Leave some extra space, of course. (If you
plan to write code like the incorrect example above, where the
bitset is a local variable, then you may have to talk your
compiler into allowing that much stack space; there may be zero
space overhead, but it's all allocated inside the object.)
</p><p>
<span class="emphasis"><em>A container&lt;bool&gt;.  </em></span> The
Committee made provision for the space savings possible with that
(N/8) usage previously mentioned, so that you don't have to do
wasteful things like <code class="code">Container&lt;char&gt;</code> or
<code class="code">Container&lt;short int&gt;</code>. Specifically,
<code class="code">vector&lt;bool&gt;</code> is required to be specialized for
that space savings.
</p><p>
The problem is that <code class="code">vector&lt;bool&gt;</code> doesn't
behave like a normal vector anymore. There have been recent
journal articles which discuss the problems (the ones by Herb
Sutter in the May and July/August 1999 issues of C++ Report cover
it well). Future revisions of the ISO C++ Standard will change
the requirement for <code class="code">vector&lt;bool&gt;</code>
specialization. In the meantime, <code class="code">deque&lt;bool&gt;</code>
is recommended (although its behavior is sane, you probably will
not get the space savings, but the allocation scheme is different
than that of vector).
</p><p>
<span class="emphasis"><em>Extremely weird solutions.  </em></span> If
you have access to the compiler and linker at runtime, you can do
something insane, like figuring out just how many bits you need,
then writing a temporary source code file. That file contains an
instantiation of <code class="code">bitset</code> for the required number of
bits, inside some wrapper functions with unchanging signatures.
Have your program then call the compiler on that file using
Position Independent Code, then open the newly-created object
file and load those wrapper functions. You'll have an
instantiation of <code class="code">bitset&lt;N&gt;</code> for the exact
<code class="code">N</code> that you need at the time. Don't forget to delete
the temporary files. (Yes, this <span class="emphasis"><em>can</em></span> be, and
<span class="emphasis"><em>has been</em></span>, done.)
</p><p>
This would be the approach of either a visionary genius or a
raving lunatic, depending on your programming and management
style. Probably the latter.
</p><p>
Which of the above techniques you use, if any, are up to you and
your intended application. Some time/space profiling is
indicated if it really matters (don't just guess). And, if you
manage to do anything along the lines of the third category, the
author would love to hear from you...
</p><p>
Also note that the implementation of bitset used in libstdc++ has
<a class="ulink" href="../ext/sgiexts.html#ch23" target="_top">some extensions</a>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="associative.bitset.type_string"></a>Type String</h3></div></div></div><p>
</p><p>
Bitmasks do not take char* nor const char* arguments in their
constructors. This is something of an accident, but you can read
about the problem: follow the library's “<span class="quote">Links</span>” from
the homepage, and from the C++ information “<span class="quote">defect
reflector</span>” link, select the library issues list. Issue
number 116 describes the problem.
</p><p>
For now you can simply make a temporary string object using the
constructor expression:
</p><pre class="programlisting">
std::bitset&lt;5&gt; b ( std::string(“<span class="quote">10110</span>”) );
</pre><p>
instead of
</p><pre class="programlisting">
std::bitset&lt;5&gt; b ( “<span class="quote">10110</span>” ); // invalid
</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch17.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt07ch17.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch18.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 17. Associative </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 18. Interacting with C</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt07ch18.html 0 → 100644
<?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 18. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="bk01pt07ch17s02.html" title="bitset" /><link rel="next" href="iterators.html" title="Part VIII. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 18. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch17s02.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="iterators.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.containers.c"></a>Chapter 18. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch18.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.c.vs_array"></a>Containers vs. Arrays</h2></div></div></div><p>
You're writing some code and can't decide whether to use builtin
arrays or some kind of container. There are compelling reasons
to use one of the container classes, but you're afraid that
you'll eventually run into difficulties, change everything back
to arrays, and then have to change all the code that uses those
data types to keep up with the change.
</p><p>
If your code makes use of the standard algorithms, this isn't as
scary as it sounds. The algorithms don't know, nor care, about
the kind of “<span class="quote">container</span>” on which they work, since
the algorithms are only given endpoints to work with. For the
container classes, these are iterators (usually
<code class="code">begin()</code> and <code class="code">end()</code>, but not always).
For builtin arrays, these are the address of the first element
and the <a class="ulink" href="../24_iterators/howto.html#2" target="_top">past-the-end</a> element.
</p><p>
Some very simple wrapper functions can hide all of that from the
rest of the code. For example, a pair of functions called
<code class="code">beginof</code> can be written, one that takes an array,
another that takes a vector. The first returns a pointer to the
first element, and the second returns the vector's
<code class="code">begin()</code> iterator.
</p><p>
The functions should be made template functions, and should also
be declared inline. As pointed out in the comments in the code
below, this can lead to <code class="code">beginof</code> being optimized out
of existence, so you pay absolutely nothing in terms of increased
code size or execution time.
</p><p>
The result is that if all your algorithm calls look like
</p><pre class="programlisting">
std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);
</pre><p>
then the type of foo can change from an array of ints to a vector
of ints to a deque of ints and back again, without ever changing
any client code.
</p><p>
This author has a collection of such functions, called
“<span class="quote">*of</span>” because they all extend the builtin
“<span class="quote">sizeof</span>”. It started with some Usenet discussions
on a transparent way to find the length of an array. A
simplified and much-reduced version for easier reading is <a class="ulink" href="wrappers_h.txt" target="_top">given here</a>.
</p><p>
Astute readers will notice two things at once: first, that the
container class is still a <code class="code">vector&lt;T&gt;</code> instead
of a more general <code class="code">Container&lt;T&gt;</code>. This would
mean that three functions for <code class="code">deque</code> would have to be
added, another three for <code class="code">list</code>, and so on. This is
due to problems with getting template resolution correct; I find
it easier just to give the extra three lines and avoid confusion.
</p><p>
Second, the line
</p><pre class="programlisting">
inline unsigned int lengthof (T (&amp;)[sz]) { return sz; }
</pre><p>
looks just weird! Hint: unused parameters can be left nameless.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch17s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">bitset </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part VIII. Iterators</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt08ch19.html 0 → 100644
<?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 19. Predefined</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="iterators.html" title="Part VIII. Iterators" /><link rel="prev" href="iterators.html" title="Part VIII. Iterators" /><link rel="next" href="bk01pt08ch19s02.html" title="One Past the End" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 19. Predefined</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="iterators.html">Prev</a> </td><th width="60%" align="center">Part VIII. Iterators</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt08ch19s02.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.iterators.predefined"></a>Chapter 19. Predefined</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt08ch19.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="sect1"><a href="bk01pt08ch19s02.html">One Past the End</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="iterators.predefined.vs_pointers"></a>Iterators vs. Pointers</h2></div></div></div><p><a class="ulink" href="../faq/index.html#5_1" target="_top">FAQ 5.1</a> points out that iterators
are not implemented as pointers. They are a generalization of
pointers, but they are implemented in libstdc++ as separate classes.
</p><p>Keeping that simple fact in mind as you design your code will
prevent a whole lot of difficult-to-understand bugs.
</p><p>You can think of it the other way 'round, even. Since iterators
are a generalization, that means that <span class="emphasis"><em>pointers</em></span> are
<span class="emphasis"><em>iterators</em></span>, and that pointers can be used whenever an
iterator would be. All those functions in the Algorithms chapter
of the Standard will work just as well on plain arrays and their
pointers.
</p><p>That doesn't mean that when you pass in a pointer, it gets wrapped
into some special delegating iterator-to-pointer class with a layer
of overhead. (If you think that's the case anywhere, you don't
understand templates to begin with...) Oh, no; if you pass
in a pointer, then the compiler will instantiate that template
using T* as a type, and good old high-speed pointer arithmetic as
its operations, so the resulting code will be doing exactly the same
things as it would be doing if you had hand-coded it yourself (for
the 273rd time).
</p><p>How much overhead <span class="emphasis"><em>is</em></span> there when using an iterator class?
Very little. Most of the layering classes contain nothing but
typedefs, and typedefs are "meta-information" that simply
tell the compiler some nicknames; they don't create code. That
information gets passed down through inheritance, so while the
compiler has to do work looking up all the names, your runtime code
does not. (This has been a prime concern from the beginning.)
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="iterators.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="iterators.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt08ch19s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VIII. Iterators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> One Past the End</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html 0 → 100644
<?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>One Past the End</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt08ch19.html" title="Chapter 19. Predefined" /><link rel="prev" href="bk01pt08ch19.html" title="Chapter 19. Predefined" /><link rel="next" href="algorithms.html" title="Part IX. Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">One Past the End</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt08ch19.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Predefined</th><td width="20%" align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="iterators.predefined.end"></a>One Past the End</h2></div></div></div><p>This starts off sounding complicated, but is actually very easy,
especially towards the end. Trust me.
</p><p>Beginners usually have a little trouble understand the whole
'past-the-end' thing, until they remember their early algebra classes
(see, they <span class="emphasis"><em>told</em></span> you that stuff would come in handy!) and
the concept of half-open ranges.
</p><p>First, some history, and a reminder of some of the funkier rules in
C and C++ for builtin arrays. The following rules have always been
true for both languages:
</p><div class="orderedlist"><ol type="1"><li><p>You can point anywhere in the array, <span class="emphasis"><em>or to the first element
past the end of the array</em></span>. A pointer that points to one
past the end of the array is guaranteed to be as unique as a
pointer to somewhere inside the array, so that you can compare
such pointers safely.
</p></li><li><p>You can only dereference a pointer that points into an array.
If your array pointer points outside the array -- even to just
one past the end -- and you dereference it, Bad Things happen.
</p></li><li><p>Strictly speaking, simply pointing anywhere else invokes
undefined behavior. Most programs won't puke until such a
pointer is actually dereferenced, but the standards leave that
up to the platform.
</p></li></ol></div><p>The reason this past-the-end addressing was allowed is to make it
easy to write a loop to go over an entire array, e.g.,
while (*d++ = *s++);.
</p><p>So, when you think of two pointers delimiting an array, don't think
of them as indexing 0 through n-1. Think of them as <span class="emphasis"><em>boundary
markers</em></span>:
</p><pre class="programlisting">
beginning end
| |
| | This is bad. Always having to
| | remember to add or subtract one.
| | Off-by-one bugs very common here.
V V
array of N elements
|---|---|--...--|---|---|
| 0 | 1 | ... |N-2|N-1|
|---|---|--...--|---|---|
^ ^
| |
| | This is good. This is safe. This
| | is guaranteed to work. Just don't
| | dereference 'end'.
beginning end
</pre><p>See? Everything between the boundary markers is part of the array.
Simple.
</p><p>Now think back to your junior-high school algebra course, when you
were learning how to draw graphs. Remember that a graph terminating
with a solid dot meant, "Everything up through this point,"
and a graph terminating with an open dot meant, "Everything up
to, but not including, this point," respectively called closed
and open ranges? Remember how closed ranges were written with
brackets, <span class="emphasis"><em>[a,b]</em></span>, and open ranges were written with parentheses,
<span class="emphasis"><em>(a,b)</em></span>?
</p><p>The boundary markers for arrays describe a <span class="emphasis"><em>half-open range</em></span>,
starting with (and including) the first element, and ending with (but
not including) the last element: <span class="emphasis"><em>[beginning,end)</em></span>. See, I
told you it would be simple in the end.
</p><p>Iterators, and everything working with iterators, follows this same
time-honored tradition. A container's <code class="code">begin()</code> method returns
an iterator referring to the first element, and its <code class="code">end()</code>
method returns a past-the-end iterator, which is guaranteed to be
unique and comparable against any other iterator pointing into the
middle of the container.
</p><p>Container constructors, container methods, and algorithms, all take
pairs of iterators describing a range of values on which to operate.
All of these ranges are half-open ranges, so you pass the beginning
iterator as the starting parameter, and the one-past-the-end iterator
as the finishing parameter.
</p><p>This generalizes very well. You can operate on sub-ranges quite
easily this way; functions accepting a <span class="emphasis"><em>[first,last)</em></span> range
don't know or care whether they are the boundaries of an entire {array,
sequence, container, whatever}, or whether they only enclose a few
elements from the center. This approach also makes zero-length
sequences very simple to recognize: if the two endpoints compare
equal, then the {array, sequence, container, whatever} is empty.
</p><p>Just don't dereference <code class="code">end()</code>.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt08ch19.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt08ch19.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Predefined </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part IX. Algorithms</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt09ch20.html 0 → 100644
<?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 20. Mutating</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="algorithms.html" title="Part IX. Algorithms" /><link rel="prev" href="bk01pt09pr02.html" title="" /><link rel="next" href="numerics.html" title="Part X. Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 20. Mutating</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt09pr02.html">Prev</a> </td><th width="60%" align="center">Part IX. Algorithms</th><td width="20%" align="right"> <a accesskey="n" href="numerics.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.algorithms.mutating"></a>Chapter 20. Mutating</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt09ch20.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt09ch20.html#algorithms.swap.specializations">Specializations</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="algorithms.mutating.swap"></a><code class="function">swap</code></h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="algorithms.swap.specializations"></a>Specializations</h3></div></div></div><p>If you call <code class="code"> std::swap(x,y); </code> where x and y are standard
containers, then the call will automatically be replaced by a call to
<code class="code"> x.swap(y); </code> instead.
</p><p>This allows member functions of each container class to take over, and
containers' swap functions should have O(1) complexity according to
the standard. (And while "should" allows implementations to
behave otherwise and remain compliant, this implementation does in
fact use constant-time swaps.) This should not be surprising, since
for two containers of the same type to swap contents, only some
internal pointers to storage need to be exchanged.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt09pr02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="algorithms.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="numerics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part X. Numerics</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt09pr02.html 0 → 100644
<?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></title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="algorithms.html" title="Part IX. Algorithms" /><link rel="prev" href="algorithms.html" title="Part IX. Algorithms" /><link rel="next" href="bk01pt09ch20.html" title="Chapter 20. Mutating" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="algorithms.html">Prev</a> </td><th width="60%" align="center">Part IX. Algorithms</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt09ch20.html">Next</a></td></tr></table><hr /></div><div class="preface" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id405802"></a></h2></div></div></div><p>
The neatest accomplishment of the algorithms chapter is that all the
work is done via iterators, not containers directly. This means two
important things:
</p><div class="orderedlist"><ol type="1"><li><p>
Anything that behaves like an iterator can be used in one of
these algorithms. Raw pointers make great candidates, thus
built-in arrays are fine containers, as well as your own iterators.
</p></li><li><p>
The algorithms do not (and cannot) affect the container as a
whole; only the things between the two iterator endpoints. If
you pass a range of iterators only enclosing the middle third of
a container, then anything outside that range is inviolate.
</p></li></ol></div><p>
Even strings can be fed through the algorithms here, although the
string class has specialized versions of many of these functions
(for example, <code class="code">string::find()</code>). Most of the examples
on this page will use simple arrays of integers as a playground
for algorithms, just to keep things simple. The use of
<span class="emphasis"><em>N</em></span> as a size in the examples is to keep
things easy to read but probably won't be valid code. You can
use wrappers such as those described in the <a class="ulink" href="../23_containers/howto.html" target="_top">containers chapter</a> to
keep real code readable.
</p><p>
The single thing that trips people up the most is the definition
of <span class="emphasis"><em>range</em></span> used with iterators; the famous
"past-the-end" rule that everybody loves to hate. The
<a class="ulink" href="../24_iterators/howto.html#2" target="_top">iterators
chapter</a> of this document has a complete explanation of
this simple rule that seems to cause so much confusion. Once you
get <span class="emphasis"><em>range</em></span> into your head (it's not that
hard, honest!), then the algorithms are a cakewalk.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="algorithms.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="algorithms.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt09ch20.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part IX. Algorithms </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 20. Mutating</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt10ch21.html 0 → 100644
<?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 21. Complex</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="numerics.html" title="Part X. Numerics" /><link rel="next" href="bk01pt10ch22.html" title="Chapter 22. Generalized Operations" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 21. Complex</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch22.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.numerics.complex"></a>Chapter 21. Complex</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt10ch21.html#numerics.complex.processing">complex Processing</a></span></dt></dl></div><p>
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="numerics.complex.processing"></a>complex Processing</h2></div></div></div><p>
</p><p>Using <code class="code">complex&lt;&gt;</code> becomes even more comple- er, sorry,
<span class="emphasis"><em>complicated</em></span>, with the not-quite-gratuitously-incompatible
addition of complex types to the C language. David Tribble has
compiled a list of C++98 and C99 conflict points; his description of
C's new type versus those of C++ and how to get them playing together
nicely is
<a class="ulink" href="http://david.tribble.com/text/cdiffs.htm#C99-complex" target="_top">here</a>.
</p><p><code class="code">complex&lt;&gt;</code> is intended to be instantiated with a
floating-point type. As long as you meet that and some other basic
requirements, then the resulting instantiation has all of the usual
math operators defined, as well as definitions of <code class="code">op&lt;&lt;</code>
and <code class="code">op&gt;&gt;</code> that work with iostreams: <code class="code">op&lt;&lt;</code>
prints <code class="code">(u,v)</code> and <code class="code">op&gt;&gt;</code> can read <code class="code">u</code>,
<code class="code">(u)</code>, and <code class="code">(u,v)</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch22.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part X. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 22. Generalized Operations</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt10ch22.html 0 → 100644
<?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 22. Generalized Operations</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="bk01pt10ch21.html" title="Chapter 21. Complex" /><link rel="next" href="bk01pt10ch23.html" title="Chapter 23. Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 22. Generalized Operations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch21.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch23.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.numerics.generalized_ops"></a>Chapter 22. Generalized Operations</h2></div></div></div><p>
</p><p>There are four generalized functions in the &lt;numeric&gt; header
that follow the same conventions as those in &lt;algorithm&gt;. Each
of them is overloaded: one signature for common default operations,
and a second for fully general operations. Their names are
self-explanatory to anyone who works with numerics on a regular basis:
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">accumulate</code></p></li><li><p><code class="code">inner_product</code></p></li><li><p><code class="code">partial_sum</code></p></li><li><p><code class="code">adjacent_difference</code></p></li></ul></div><p>Here is a simple example of the two forms of <code class="code">accumulate</code>.
</p><pre class="programlisting">
int ar[50];
int someval = somefunction();
// ...initialize members of ar to something...
int sum = std::accumulate(ar,ar+50,0);
int sum_stuff = std::accumulate(ar,ar+50,someval);
int product = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
</pre><p>The first call adds all the members of the array, using zero as an
initial value for <code class="code">sum</code>. The second does the same, but uses
<code class="code">someval</code> as the starting value (thus, <code class="code">sum_stuff == sum +
someval</code>). The final call uses the second of the two signatures,
and multiplies all the members of the array; here we must obviously
use 1 as a starting value instead of 0.
</p><p>The other three functions have similar dual-signature forms.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch21.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch23.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Complex </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 23. Interacting with C</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt10ch23.html 0 → 100644
<?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 23. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="bk01pt10ch22.html" title="Chapter 22. Generalized Operations" /><link rel="next" href="bk01pt10ch23s02.html" title="C99" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 23. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch22.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch23s02.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.numerics.c"></a>Chapter 23. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt10ch23.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="sect1"><a href="bk01pt10ch23s02.html">C99</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="numerics.c.array"></a>Numerics vs. Arrays</h2></div></div></div><p>One of the major reasons why FORTRAN can chew through numbers so well
is that it is defined to be free of pointer aliasing, an assumption
that C89 is not allowed to make, and neither is C++98. C99 adds a new
keyword, <code class="code">restrict</code>, to apply to individual pointers. The
C++ solution is contained in the library rather than the language
(although many vendors can be expected to add this to their compilers
as an extension).
</p><p>That library solution is a set of two classes, five template classes,
and "a whole bunch" of functions. The classes are required
to be free of pointer aliasing, so compilers can optimize the
daylights out of them the same way that they have been for FORTRAN.
They are collectively called <code class="code">valarray</code>, although strictly
speaking this is only one of the five template classes, and they are
designed to be familiar to people who have worked with the BLAS
libraries before.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch22.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch23s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 22. Generalized Operations </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> C99</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html 0 → 100644
<?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>C99</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt10ch23.html" title="Chapter 23. Interacting with C" /><link rel="prev" href="bk01pt10ch23.html" title="Chapter 23. Interacting with C" /><link rel="next" href="io.html" title="Part XI. Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">C99</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch23.html">Prev</a> </td><th width="60%" align="center">Chapter 23. Interacting with C</th><td width="20%" align="right"> <a accesskey="n" href="io.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="numerics.c.c99"></a>C99</h2></div></div></div><p>In addition to the other topics on this page, we'll note here some
of the C99 features that appear in libstdc++.
</p><p>The C99 features depend on the <code class="code">--enable-c99</code> configure flag.
This flag is already on by default, but it can be disabled by the
user. Also, the configuration machinery will disable it if the
necessary support for C99 (e.g., header files) cannot be found.
</p><p>As of GCC 3.0, C99 support includes classification functions
such as <code class="code">isnormal</code>, <code class="code">isgreater</code>,
<code class="code">isnan</code>, etc.
The functions used for 'long long' support such as <code class="code">strtoll</code>
are supported, as is the <code class="code">lldiv_t</code> typedef. Also supported
are the wide character functions using 'long long', like
<code class="code">wcstoll</code>.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch23.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt10ch23.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="io.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 23. Interacting with C </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part XI. Input and Output</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch24.html 0 → 100644
<?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.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" 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="bk01pt11ch25.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="bk01pt11ch25.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 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 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="bk01pt11ch25.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>
libstdc++-v3/doc/html/manual/bk01pt11ch25.html 0 → 100644
<?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 25. Stream Buffers</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" 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="bk01pt11ch24.html" title="Chapter 24. Iostream Objects" /><link rel="next" href="bk01pt11ch25s02.html" title="Buffering" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 25. Stream Buffers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch24.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch25s02.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.streambufs"></a>Chapter 25. Stream Buffers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch25.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch25s02.html">Buffering</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="io.streambuf.derived"></a>Derived streambuf Classes</h2></div></div></div><p>
</p><p>Creating your own stream buffers for I/O can be remarkably easy.
If you are interested in doing so, we highly recommend two very
excellent books:
<a class="ulink" href="http://www.langer.camelot.de/iostreams.html" target="_top">Standard C++
IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and
<a class="ulink" href="http://www.josuttis.com/libbook/" target="_top">The C++ Standard Library</a>
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
Addison-Wesley, who isn't paying us a cent for saying that, honest.
</p><p>Here is a simple example, io/outbuf1, from the Josuttis text. It
transforms everything sent through it to uppercase. This version
assumes many things about the nature of the character type being
used (for more information, read the books or the newsgroups):
</p><pre class="programlisting">
#include &lt;iostream&gt;
#include &lt;streambuf&gt;
#include &lt;locale&gt;
#include &lt;cstdio&gt;
class outbuf : public std::streambuf
{
protected:
/* central output function
* - print characters in uppercase mode
*/
virtual int_type overflow (int_type c) {
if (c != EOF) {
// convert lowercase to uppercase
c = std::toupper(static_cast&lt;char&gt;(c),getloc());
// and write the character to the standard output
if (putchar(c) == EOF) {
return EOF;
}
}
return c;
}
};
int main()
{
// create special output buffer
outbuf ob;
// initialize output stream with that output buffer
std::ostream out(&amp;ob);
out &lt;&lt; "31 hexadecimal: "
&lt;&lt; std::hex &lt;&lt; 31 &lt;&lt; std::endl;
return 0;
}
</pre><p>Try it yourself! More examples can be found in 3.1.x code, in
<code class="code">include/ext/*_filebuf.h</code>, and on
<a class="ulink" href="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/" target="_top">Dietmar
Kühl's IOStreams page</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch24.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="bk01pt11ch25s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Iostream Objects </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Buffering</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html 0 → 100644
<?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>Buffering</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt11ch25.html" title="Chapter 25. Stream Buffers" /><link rel="prev" href="bk01pt11ch25.html" title="Chapter 25. Stream Buffers" /><link rel="next" href="bk01pt11ch26.html" title="Chapter 26. Memory Based Streams" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Buffering</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch25.html">Prev</a> </td><th width="60%" align="center">Chapter 25. Stream Buffers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch26.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="io.streambuf.buffering"></a>Buffering</h2></div></div></div><p>First, are you sure that you understand buffering? Particularly
the fact that C++ may not, in fact, have anything to do with it?
</p><p>The rules for buffering can be a little odd, but they aren't any
different from those of C. (Maybe that's why they can be a bit
odd.) Many people think that writing a newline to an output
stream automatically flushes the output buffer. This is true only
when the output stream is, in fact, a terminal and not a file
or some other device -- and <span class="emphasis"><em>that</em></span> may not even be true
since C++ says nothing about files nor terminals. All of that is
system-dependent. (The "newline-buffer-flushing only occurring
on terminals" thing is mostly true on Unix systems, though.)
</p><p>Some people also believe that sending <code class="code">endl</code> down an
output stream only writes a newline. This is incorrect; after a
newline is written, the buffer is also flushed. Perhaps this
is the effect you want when writing to a screen -- get the text
out as soon as possible, etc -- but the buffering is largely
wasted when doing this to a file:
</p><pre class="programlisting">
output &lt;&lt; "a line of text" &lt;&lt; endl;
output &lt;&lt; some_data_variable &lt;&lt; endl;
output &lt;&lt; "another line of text" &lt;&lt; endl; </pre><p>The proper thing to do in this case to just write the data out
and let the libraries and the system worry about the buffering.
If you need a newline, just write a newline:
</p><pre class="programlisting">
output &lt;&lt; "a line of text\n"
&lt;&lt; some_data_variable &lt;&lt; '\n'
&lt;&lt; "another line of text\n"; </pre><p>I have also joined the output statements into a single statement.
You could make the code prettier by moving the single newline to
the start of the quoted text on the last line, for example.
</p><p>If you do need to flush the buffer above, you can send an
<code class="code">endl</code> if you also need a newline, or just flush the buffer
yourself:
</p><pre class="programlisting">
output &lt;&lt; ...... &lt;&lt; flush; // can use std::flush manipulator
output.flush(); // or call a member fn </pre><p>On the other hand, there are times when writing to a file should
be like writing to standard error; no buffering should be done
because the data needs to appear quickly (a prime example is a
log file for security-related information). The way to do this is
just to turn off the buffering <span class="emphasis"><em>before any I/O operations at
all</em></span> have been done (note that opening counts as an I/O operation):
</p><pre class="programlisting">
std::ofstream os;
std::ifstream is;
int i;
os.rdbuf()-&gt;pubsetbuf(0,0);
is.rdbuf()-&gt;pubsetbuf(0,0);
os.open("/foo/bar/baz");
is.open("/qux/quux/quuux");
...
os &lt;&lt; "this data is written immediately\n";
is &gt;&gt; i; // and this will probably cause a disk read </pre><p>Since all aspects of buffering are handled by a streambuf-derived
member, it is necessary to get at that member with <code class="code">rdbuf()</code>.
Then the public version of <code class="code">setbuf</code> can be called. The
arguments are the same as those for the Standard C I/O Library
function (a buffer area followed by its size).
</p><p>A great deal of this is implementation-dependent. For example,
<code class="code">streambuf</code> does not specify any actions for its own
<code class="code">setbuf()</code>-ish functions; the classes derived from
<code class="code">streambuf</code> each define behavior that "makes
sense" for that class: an argument of (0,0) turns off buffering
for <code class="code">filebuf</code> but does nothing at all for its siblings
<code class="code">stringbuf</code> and <code class="code">strstreambuf</code>, and specifying
anything other than (0,0) has varying effects.
User-defined classes derived from <code class="code">streambuf</code> can
do whatever they want. (For <code class="code">filebuf</code> and arguments for
<code class="code">(p,s)</code> other than zeros, libstdc++ does what you'd expect:
the first <code class="code">s</code> bytes of <code class="code">p</code> are used as a buffer,
which you must allocate and deallocate.)
</p><p>A last reminder: there are usually more buffers involved than
just those at the language/library level. Kernel buffers, disk
buffers, and the like will also have an effect. Inspecting and
changing those are system-dependent.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch25.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt11ch25.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch26.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 25. Stream Buffers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 26. Memory Based Streams</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch26.html 0 → 100644
<?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 26. Memory Based Streams</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" 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="bk01pt11ch25s02.html" title="Buffering" /><link rel="next" href="bk01pt11ch27.html" title="Chapter 27. File Based Streams" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 26. Memory Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch25s02.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch27.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.memstreams"></a>Chapter 26. Memory Based Streams</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch26.html#manual.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.memstreams.compat"></a>Compatibility With strstream</h2></div></div></div><p>
</p><p>Stringstreams (defined in the header <code class="code">&lt;sstream&gt;</code>)
are in this author's opinion one of the coolest things since
sliced time. An example of their use is in the Received Wisdom
section for Chapter 21 (Strings),
<a class="ulink" href="../21_strings/howto.html#1.1internal" target="_top"> describing how to
format strings</a>.
</p><p>The quick definition is: they are siblings of ifstream and ofstream,
and they do for <code class="code">std::string</code> what their siblings do for
files. All that work you put into writing <code class="code">&lt;&lt;</code> and
<code class="code">&gt;&gt;</code> functions for your classes now pays off
<span class="emphasis"><em>again!</em></span> Need to format a string before passing the string
to a function? Send your stuff via <code class="code">&lt;&lt;</code> to an
ostringstream. You've read a string as input and need to parse it?
Initialize an istringstream with that string, and then pull pieces
out of it with <code class="code">&gt;&gt;</code>. Have a stringstream and need to
get a copy of the string inside? Just call the <code class="code">str()</code>
member function.
</p><p>This only works if you've written your
<code class="code">&lt;&lt;</code>/<code class="code">&gt;&gt;</code> functions correctly, though,
and correctly means that they take istreams and ostreams as
parameters, not i<span class="emphasis"><em>f</em></span>streams and o<span class="emphasis"><em>f</em></span>streams. If they
take the latter, then your I/O operators will work fine with
file streams, but with nothing else -- including stringstreams.
</p><p>If you are a user of the strstream classes, you need to update
your code. You don't have to explicitly append <code class="code">ends</code> to
terminate the C-style character array, you don't have to mess with
"freezing" functions, and you don't have to manage the
memory yourself. The strstreams have been officially deprecated,
which means that 1) future revisions of the C++ Standard won't
support them, and 2) if you use them, people will laugh at you.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch25s02.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="bk01pt11ch27.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Buffering </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 27. File Based Streams</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch27.html 0 → 100644
<?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 27. File Based Streams</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" 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="bk01pt11ch26.html" title="Chapter 26. Memory Based Streams" /><link rel="next" href="bk01pt11ch27s02.html" title="Binary Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. File Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch26.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch27s02.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.filestreams"></a>Chapter 27. File Based Streams</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch27.html#manual.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch27s02.html">Binary Input and Output</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch27s03.html">More Binary Input and Output</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.filestreams.copying_a_file"></a>Copying a File</h2></div></div></div><p>
</p><p>So you want to copy a file quickly and easily, and most important,
completely portably. And since this is C++, you have an open
ifstream (call it IN) and an open ofstream (call it OUT):
</p><pre class="programlisting">
#include &lt;fstream&gt;
std::ifstream IN ("input_file");
std::ofstream OUT ("output_file"); </pre><p>Here's the easiest way to get it completely wrong:
</p><pre class="programlisting">
OUT &lt;&lt; IN;</pre><p>For those of you who don't already know why this doesn't work
(probably from having done it before), I invite you to quickly
create a simple text file called "input_file" containing
the sentence
</p><pre class="programlisting">
The quick brown fox jumped over the lazy dog.</pre><p>surrounded by blank lines. Code it up and try it. The contents
of "output_file" may surprise you.
</p><p>Seriously, go do it. Get surprised, then come back. It's worth it.
</p><p>The thing to remember is that the <code class="code">basic_[io]stream</code> classes
handle formatting, nothing else. In particular, they break up on
whitespace. The actual reading, writing, and storing of data is
handled by the <code class="code">basic_streambuf</code> family. Fortunately, the
<code class="code">operator&lt;&lt;</code> is overloaded to take an ostream and
a pointer-to-streambuf, in order to help with just this kind of
"dump the data verbatim" situation.
</p><p>Why a <span class="emphasis"><em>pointer</em></span> to streambuf and not just a streambuf? Well,
the [io]streams hold pointers (or references, depending on the
implementation) to their buffers, not the actual
buffers. This allows polymorphic behavior on the part of the buffers
as well as the streams themselves. The pointer is easily retrieved
using the <code class="code">rdbuf()</code> member function. Therefore, the easiest
way to copy the file is:
</p><pre class="programlisting">
OUT &lt;&lt; IN.rdbuf();</pre><p>So what <span class="emphasis"><em>was</em></span> happening with OUT&lt;&lt;IN? Undefined
behavior, since that particular &lt;&lt; isn't defined by the Standard.
I have seen instances where it is implemented, but the character
extraction process removes all the whitespace, leaving you with no
blank lines and only "Thequickbrownfox...". With
libraries that do not define that operator, IN (or one of IN's
member pointers) sometimes gets converted to a void*, and the output
file then contains a perfect text representation of a hexadecimal
address (quite a big surprise). Others don't compile at all.
</p><p>Also note that none of this is specific to o<span class="emphasis"><em>*f*</em></span>streams.
The operators shown above are all defined in the parent
basic_ostream class and are therefore available with all possible
descendants.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch26.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="bk01pt11ch27s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. Memory Based Streams </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Binary Input and Output</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html 0 → 100644
<?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>Binary Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt11ch27.html" title="Chapter 27. File Based Streams" /><link rel="prev" href="bk01pt11ch27.html" title="Chapter 27. File Based Streams" /><link rel="next" href="bk01pt11ch27s03.html" title="More Binary Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Binary Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch27.html">Prev</a> </td><th width="60%" align="center">Chapter 27. File Based Streams</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch27s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.filestreams.binary"></a>Binary Input and Output</h2></div></div></div><p>
</p><p>The first and most important thing to remember about binary I/O is
that opening a file with <code class="code">ios::binary</code> is not, repeat
<span class="emphasis"><em>not</em></span>, the only thing you have to do. It is not a silver
bullet, and will not allow you to use the <code class="code">&lt;&lt;/&gt;&gt;</code>
operators of the normal fstreams to do binary I/O.
</p><p>Sorry. Them's the breaks.
</p><p>This isn't going to try and be a complete tutorial on reading and
writing binary files (because "binary"
<a class="ulink" href="#7" target="_top">covers a lot of ground)</a>, but we will try and clear
up a couple of misconceptions and common errors.
</p><p>First, <code class="code">ios::binary</code> has exactly one defined effect, no more
and no less. Normal text mode has to be concerned with the newline
characters, and the runtime system will translate between (for
example) '\n' and the appropriate end-of-line sequence (LF on Unix,
CRLF on DOS, CR on Macintosh, etc). (There are other things that
normal mode does, but that's the most obvious.) Opening a file in
binary mode disables this conversion, so reading a CRLF sequence
under Windows won't accidentally get mapped to a '\n' character, etc.
Binary mode is not supposed to suddenly give you a bitstream, and
if it is doing so in your program then you've discovered a bug in
your vendor's compiler (or some other part of the C++ implementation,
possibly the runtime system).
</p><p>Second, using <code class="code">&lt;&lt;</code> to write and <code class="code">&gt;&gt;</code> to
read isn't going to work with the standard file stream classes, even
if you use <code class="code">skipws</code> during reading. Why not? Because
ifstream and ofstream exist for the purpose of <span class="emphasis"><em>formatting</em></span>,
not reading and writing. Their job is to interpret the data into
text characters, and that's exactly what you don't want to happen
during binary I/O.
</p><p>Third, using the <code class="code">get()</code> and <code class="code">put()/write()</code> member
functions still aren't guaranteed to help you. These are
"unformatted" I/O functions, but still character-based.
(This may or may not be what you want, see below.)
</p><p>Notice how all the problems here are due to the inappropriate use
of <span class="emphasis"><em>formatting</em></span> functions and classes to perform something
which <span class="emphasis"><em>requires</em></span> that formatting not be done? There are a
seemingly infinite number of solutions, and a few are listed here:
</p><div class="itemizedlist"><ul type="disc"><li><p>“<span class="quote">Derive your own fstream-type classes and write your own
&lt;&lt;/&gt;&gt; operators to do binary I/O on whatever data
types you're using.</span>”
</p><p>
This is a Bad Thing, because while
the compiler would probably be just fine with it, other humans
are going to be confused. The overloaded bitshift operators
have a well-defined meaning (formatting), and this breaks it.
</p></li><li><p>
“<span class="quote">Build the file structure in memory, then
<code class="code">mmap()</code> the file and copy the
structure.
</span>”
</p><p>
Well, this is easy to make work, and easy to break, and is
pretty equivalent to using <code class="code">::read()</code> and
<code class="code">::write()</code> directly, and makes no use of the
iostream library at all...
</p></li><li><p>
“<span class="quote">Use streambufs, that's what they're there for.</span>”
</p><p>
While not trivial for the beginner, this is the best of all
solutions. The streambuf/filebuf layer is the layer that is
responsible for actual I/O. If you want to use the C++
library for binary I/O, this is where you start.
</p></li></ul></div><p>How to go about using streambufs is a bit beyond the scope of this
document (at least for now), but while streambufs go a long way,
they still leave a couple of things up to you, the programmer.
As an example, byte ordering is completely between you and the
operating system, and you have to handle it yourself.
</p><p>Deriving a streambuf or filebuf
class from the standard ones, one that is specific to your data
types (or an abstraction thereof) is probably a good idea, and
lots of examples exist in journals and on Usenet. Using the
standard filebufs directly (either by declaring your own or by
using the pointer returned from an fstream's <code class="code">rdbuf()</code>)
is certainly feasible as well.
</p><p>One area that causes problems is trying to do bit-by-bit operations
with filebufs. C++ is no different from C in this respect: I/O
must be done at the byte level. If you're trying to read or write
a few bits at a time, you're going about it the wrong way. You
must read/write an integral number of bytes and then process the
bytes. (For example, the streambuf functions take and return
variables of type <code class="code">int_type</code>.)
</p><p>Another area of problems is opening text files in binary mode.
Generally, binary mode is intended for binary files, and opening
text files in binary mode means that you now have to deal with all of
those end-of-line and end-of-file problems that we mentioned before.
An instructive thread from comp.lang.c++.moderated delved off into
this topic starting more or less at
<a class="ulink" href="http://groups.google.com/groups?oi=djq&amp;selm=an_436187505" target="_top">this</a>
article and continuing to the end of the thread. (You'll have to
sort through some flames every couple of paragraphs, but the points
made are good ones.)
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch27.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt11ch27.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch27s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 27. File Based Streams </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> More Binary Input and Output</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch27s03.html 0 → 100644
<?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>More Binary Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt11ch27.html" title="Chapter 27. File Based Streams" /><link rel="prev" href="bk01pt11ch27s02.html" title="Binary Input and Output" /><link rel="next" href="bk01pt11ch28.html" title="Chapter 28. Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">More Binary Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch27s02.html">Prev</a> </td><th width="60%" align="center">Chapter 27. File Based Streams</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch28.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.filestreams.binary2"></a>More Binary Input and Output</h2></div></div></div><p>Towards the beginning of February 2001, the subject of
"binary" I/O was brought up in a couple of places at the
same time. One notable place was Usenet, where James Kanze and
Dietmar Kühl separately posted articles on why attempting
generic binary I/O was not a good idea. (Here are copies of
<a class="ulink" href="binary_iostreams_kanze.txt" target="_top">Kanze's article</a> and
<a class="ulink" href="binary_iostreams_kuehl.txt" target="_top">Kühl's article</a>.)
</p><p>Briefly, the problems of byte ordering and type sizes mean that
the unformatted functions like <code class="code">ostream::put()</code> and
<code class="code">istream::get()</code> cannot safely be used to communicate
between arbitrary programs, or across a network, or from one
invocation of a program to another invocation of the same program
on a different platform, etc.
</p><p>The entire Usenet thread is instructive, and took place under the
subject heading "binary iostreams" on both comp.std.c++
and comp.lang.c++.moderated in parallel. Also in that thread,
Dietmar Kühl mentioned that he had written a pair of stream
classes that would read and write XDR, which is a good step towards
a portable binary format.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch27s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt11ch27.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch28.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Binary 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 28. Interacting with C</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch28.html 0 → 100644
<?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 28. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" 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="bk01pt11ch27s03.html" title="More Binary Input and Output" /><link rel="next" href="bk01pt11ch28s02.html" title="Performance" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 28. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch27s03.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch28s02.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.c"></a>Chapter 28. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch28.html#manual.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch28s02.html">Performance</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.c.FILE"></a>Using FILE* and file descriptors</h2></div></div></div><p>
See the <a class="link" href="bk01pt12ch38.html" title="Chapter 38. Input and Output">extensions</a> for using
<span class="type">FILE</span> and <span class="type">file descriptors</span> with
<code class="classname">ofstream</code> and
<code class="classname">ifstream</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch27s03.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="bk01pt11ch28s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">More Binary 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"> Performance</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html 0 → 100644
<?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>Performance</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt11ch28.html" title="Chapter 28. Interacting with C" /><link rel="prev" href="bk01pt11ch28.html" title="Chapter 28. Interacting with C" /><link rel="next" href="extensions.html" title="Part XII. Extensions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Performance</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch28.html">Prev</a> </td><th width="60%" align="center">Chapter 28. Interacting with C</th><td width="20%" align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.c.sync"></a>Performance</h2></div></div></div><p>
Pathetic Performance? Ditch C.
</p><p>It sounds like a flame on C, but it isn't. Really. Calm down.
I'm just saying it to get your attention.
</p><p>Because the C++ library includes the C library, both C-style and
C++-style I/O have to work at the same time. For example:
</p><pre class="programlisting">
#include &lt;iostream&gt;
#include &lt;cstdio&gt;
std::cout &lt;&lt; "Hel";
std::printf ("lo, worl");
std::cout &lt;&lt; "d!\n";
</pre><p>This must do what you think it does.
</p><p>Alert members of the audience will immediately notice that buffering
is going to make a hash of the output unless special steps are taken.
</p><p>The special steps taken by libstdc++, at least for version 3.0,
involve doing very little buffering for the standard streams, leaving
most of the buffering to the underlying C library. (This kind of
thing is tricky to get right.)
The upside is that correctness is ensured. The downside is that
writing through <code class="code">cout</code> can quite easily lead to awful
performance when the C++ I/O library is layered on top of the C I/O
library (as it is for 3.0 by default). Some patches have been applied
which improve the situation for 3.1.
</p><p>However, the C and C++ standard streams only need to be kept in sync
when both libraries' facilities are in use. If your program only uses
C++ I/O, then there's no need to sync with the C streams. The right
thing to do in this case is to call
</p><pre class="programlisting">
#include <span class="emphasis"><em>any of the I/O headers such as ios, iostream, etc</em></span>
std::ios::sync_with_stdio(false);
</pre><p>You must do this before performing any I/O via the C++ stream objects.
Once you call this, the C++ streams will operate independently of the
(unused) C streams. For GCC 3.x, this means that <code class="code">cout</code> and
company will become fully buffered on their own.
</p><p>Note, by the way, that the synchronization requirement only applies to
the standard streams (<code class="code">cin</code>, <code class="code">cout</code>,
<code class="code">cerr</code>,
<code class="code">clog</code>, and their wide-character counterparts). File stream
objects that you declare yourself have no such requirement and are fully
buffered.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch28.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt11ch28.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 28. Interacting with C </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part XII. Extensions</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch29.html 0 → 100644
<?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 29. Compile Time Checks</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12pr03.html" title="" /><link rel="next" href="debug_mode.html" title="Chapter 30. Debug Mode" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 29. Compile Time Checks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12pr03.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="debug_mode.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.ext.compile_checks"></a>Chapter 29. Compile Time Checks</h2></div></div></div><p>
Also known as concept checking.
</p><p>In 1999, SGI added <span class="emphasis"><em>concept checkers</em></span> to their implementation
of the STL: code which checked the template parameters of
instantiated pieces of the STL, in order to insure that the parameters
being used met the requirements of the standard. For example,
the Standard requires that types passed as template parameters to
<code class="code">vector</code> be “<span class="quote">Assignable</span>” (which means what you think
it means). The checking was done during compilation, and none of
the code was executed at runtime.
</p><p>Unfortunately, the size of the compiler files grew significantly
as a result. The checking code itself was cumbersome. And bugs
were found in it on more than one occasion.
</p><p>The primary author of the checking code, Jeremy Siek, had already
started work on a replacement implementation. The new code has been
formally reviewed and accepted into
<a class="ulink" href="http://www.boost.org/libs/concept_check/concept_check.htm" target="_top">the
Boost libraries</a>, and we are pleased to incorporate it into the
GNU C++ library.
</p><p>The new version imposes a much smaller space overhead on the generated
object file. The checks are also cleaner and easier to read and
understand.
</p><p>They are off by default for all versions of GCC from 3.0 to 3.4 (the
latest release at the time of writing).
They can be enabled at configure time with
<a class="ulink" href="../configopts.html" target="_top"><code class="literal">--enable-concept-checks</code></a>.
You can enable them on a per-translation-unit basis with
<code class="code">#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
(or with <code class="code">#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
3.1, 3.2 and 3.3).
</p><p>Please note that the upcoming C++ standard has first-class
support for template parameter constraints based on concepts in the core
language. This will obviate the need for the library-simulated concept
checking described above.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12pr03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 30. Debug Mode</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch30s02.html 0 → 100644
<?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>Semantics</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; debug&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 30. Debug Mode" /><link rel="prev" href="debug_mode.html" title="Chapter 30. Debug Mode" /><link rel="next" href="bk01pt12ch30s03.html" title="Using" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Semantics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 30. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch30s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.semantics"></a>Semantics</h2></div></div></div><p>
</p><p>A program that uses the C++ standard library correctly
will maintain the same semantics under debug mode as it had with
the normal (release) library. All functional and exception-handling
guarantees made by the normal library also hold for the debug mode
library, with one exception: performance guarantees made by the
normal library may not hold in the debug mode library. For
instance, erasing an element in a <code class="code">std::list</code> is a
constant-time operation in normal library, but in debug mode it is
linear in the number of iterators that reference that particular
list. So while your (correct) program won't change its results, it
is likely to execute more slowly.</p><p>libstdc++ includes many extensions to the C++ standard library. In
some cases the extensions are obvious, such as the hashed
associative containers, whereas other extensions give predictable
results to behavior that would otherwise be undefined, such as
throwing an exception when a <code class="code">std::basic_string</code> is
constructed from a NULL character pointer. This latter category also
includes implementation-defined and unspecified semantics, such as
the growth rate of a vector. Use of these extensions is not
considered incorrect, so code that relies on them will not be
rejected by debug mode. However, use of these extensions may affect
the portability of code to other implementations of the C++ standard
library, and is therefore somewhat hazardous. For this reason, the
libstdc++ debug mode offers a "pedantic" mode (similar to
GCC's <code class="code">-pedantic</code> compiler flag) that attempts to emulate
the semantics guaranteed by the C++ standard. For
instance, constructing a <code class="code">std::basic_string</code> with a NULL
character pointer would result in an exception under normal mode or
non-pedantic debug mode (this is a libstdc++ extension), whereas
under pedantic debug mode libstdc++ would signal an error. To enable
the pedantic debug mode, compile your program with
both <code class="code">-D_GLIBCXX_DEBUG</code>
and <code class="code">-D_GLIBCXX_DEBUG_PEDANTIC</code> .
(N.B. In GCC 3.4.x and 4.0.0, due to a bug,
<code class="code">-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has
been fixed in GCC 4.0.1 and later versions.) </p><p>The following library components provide extra debugging
capabilities in debug mode:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li><p><code class="code">std::bitset</code></p></li><li><p><code class="code">std::deque</code></p></li><li><p><code class="code">std::list</code></p></li><li><p><code class="code">std::map</code></p></li><li><p><code class="code">std::multimap</code></p></li><li><p><code class="code">std::multiset</code></p></li><li><p><code class="code">std::set</code></p></li><li><p><code class="code">std::vector</code></p></li><li><p><code class="code">std::unordered_map</code></p></li><li><p><code class="code">std::unordered_multimap</code></p></li><li><p><code class="code">std::unordered_set</code></p></li><li><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations,
e.g. <code class="code">operator[]</code>,
they will not always be run when using the <code class="code">char</code> and
<code class="code">wchar_t</code> specialisations (<code class="code">std::string</code> and
<code class="code">std::wstring</code>). This is because libstdc++ uses GCC's
<code class="code">extern template</code> extension to provide explicit instantiations
of <code class="code">std::string</code> and <code class="code">std::wstring</code>, and those
explicit instantiations don't include the debug-mode checks. If the
containing functions are inlined then the checks will run, so compiling
with <code class="code">-O1</code> might be enough to enable them. Alternatively
<code class="code">-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
of the explicit instantiations and cause the functions to be instantiated
with the debug-mode checks included, but this is unsupported and not
guaranteed to work. For full debug-mode support you can use the
<code class="code">__gnu_debug::basic_string</code> debugging container directly,
which always works correctly.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch30s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 30. Debug Mode </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Using</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html 0 → 100644
<?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>Using</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; debug&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 30. Debug Mode" /><link rel="prev" href="bk01pt12ch30s02.html" title="Semantics" /><link rel="next" href="bk01pt12ch30s04.html" title="Design" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch30s02.html">Prev</a> </td><th width="60%" align="center">Chapter 30. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch30s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.using"></a>Using</h2></div></div></div><p>
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.using.mode"></a>Using the Debug Mode</h3></div></div></div><p>To use the libstdc++ debug mode, compile your application with the
compiler flag <code class="code">-D_GLIBCXX_DEBUG</code>. Note that this flag
changes the sizes and behavior of standard class templates such
as <code class="code">std::vector</code>, and therefore you can only link code
compiled with debug mode and code compiled without debug mode if no
instantiation of a container is passed between the two translation
units.</p><p>By default, error messages are formatted to fit on lines of about
78 characters. The environment variable
<code class="code">GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a
different length.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.using.specific"></a>Using a Specific Debug Container</h3></div></div></div><p>When it is not feasible to recompile your entire application, or
only specific containers need checking, debugging containers are
available as GNU extensions. These debugging containers are
functionally equivalent to the standard drop-in containers used in
debug mode, but they are available in a separate namespace as GNU
extensions and may be used in programs compiled with either release
mode or with debug mode. The
following table provides the names and headers of the debugging
containers:
</p><div class="table"><a id="id400605"></a><p class="title"><b>Table 30.1. Debugging Containers</b></p><div class="table-contents"><table summary="Debugging Containers" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col /><col /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></thead><tbody><tr><td align="left"><code class="classname">std::bitset</code></td><td align="left"><code class="filename">bitset</code></td><td align="left"><code class="classname">__gnu_debug::bitset</code></td><td align="left"><code class="filename">bitset</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::deque</code></td><td align="left"><code class="filename">deque</code></td><td align="left"><code class="classname">__gnu_debug::deque</code></td><td align="left"><code class="filename">deque</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::list</code></td><td align="left"><code class="filename">list</code></td><td align="left"><code class="classname">__gnu_debug::list</code></td><td align="left"><code class="filename">list</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::map</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::map</code></td><td align="left"><code class="filename">map</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::multimap</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::multimap</code></td><td align="left"><code class="filename">map</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::multiset</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::multiset</code></td><td align="left"><code class="filename">set</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::set</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::set</code></td><td align="left"><code class="filename">set</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::string</code></td><td align="left"><code class="filename">string</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::wstring</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::wstring</code></td><td align="left"><code class="filename">string</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::basic_string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::basic_string</code></td><td align="left"><code class="filename">string</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::vector</code></td><td align="left"><code class="filename">vector</code></td><td align="left"><code class="classname">__gnu_debug::vector</code></td><td align="left"><code class="filename">vector</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break" /><p>In addition, when compiling in C++0x mode, these additional
containers have additional debug capability.
</p><div class="table"><a id="id452759"></a><p class="title"><b>Table 30.2. Debugging Containers C++0x</b></p><div class="table-contents"><table summary="Debugging Containers C++0x" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col /><col /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></thead><tbody><tr><td align="left"><code class="classname">std::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td align="left"><code class="classname">std::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch30s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch30s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch31s02.html 0 → 100644
<?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>Semantics</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; parallel&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /><link rel="prev" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /><link rel="next" href="bk01pt12ch31s03.html" title="Using" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Semantics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="parallel_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 31. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch31s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.parallel_mode.semantics"></a>Semantics</h2></div></div></div><p> The parallel mode STL algorithms are currently not exception-safe,
i. e. user-defined functors must not throw exceptions.
</p><p> Since the current GCC OpenMP implementation does not support
OpenMP parallel regions in concurrent threads,
it is not possible to call parallel STL algorithm in
concurrent threads, either.
It might work with other compilers, though.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch31s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 31. Parallel Mode </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Using</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch31s04.html 0 → 100644
<?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>Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; parallel&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /><link rel="prev" href="bk01pt12ch31s03.html" title="Using" /><link rel="next" href="bk01pt12ch31s05.html" title="Testing" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch31s03.html">Prev</a> </td><th width="60%" align="center">Chapter 31. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch31s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.parallel_mode.design"></a>Design</h2></div></div></div><p>
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.parallel_mode.design.intro"></a>Interface Basics</h3></div></div></div><p>All parallel algorithms are intended to have signatures that are
equivalent to the ISO C++ algorithms replaced. For instance, the
<code class="code">std::adjacent_find</code> function is declared as:
</p><pre class="programlisting">
namespace std
{
template&lt;typename _FIter&gt;
_FIter
adjacent_find(_FIter, _FIter);
}
</pre><p>
Which means that there should be something equivalent for the parallel
version. Indeed, this is the case:
</p><pre class="programlisting">
namespace std
{
namespace __parallel
{
template&lt;typename _FIter&gt;
_FIter
adjacent_find(_FIter, _FIter);
...
}
}
</pre><p>But.... why the elipses?
</p><p> The elipses in the example above represent additional overloads
required for the parallel version of the function. These additional
overloads are used to dispatch calls from the ISO C++ function
signature to the appropriate parallel function (or sequential
function, if no parallel functions are deemed worthy), based on either
compile-time or run-time conditions.
</p><p> Compile-time conditions are referred to as "embarrassingly
parallel," and are denoted with the appropriate dispatch object, ie
one of <code class="code">__gnu_parallel::sequential_tag</code>,
<code class="code">__gnu_parallel::parallel_tag</code>,
<code class="code">__gnu_parallel::balanced_tag</code>,
<code class="code">__gnu_parallel::unbalanced_tag</code>,
<code class="code">__gnu_parallel::omp_loop_tag</code>, or
<code class="code">__gnu_parallel::omp_loop_static_tag</code>.
</p><p> Run-time conditions depend on the hardware being used, the number
of threads available, etc., and are denoted by the use of the enum
<code class="code">__gnu_parallel::parallelism</code>. Values of this enum include
<code class="code">__gnu_parallel::sequential</code>,
<code class="code">__gnu_parallel::parallel_unbalanced</code>,
<code class="code">__gnu_parallel::parallel_balanced</code>,
<code class="code">__gnu_parallel::parallel_omp_loop</code>,
<code class="code">__gnu_parallel::parallel_omp_loop_static</code>, or
<code class="code">__gnu_parallel::parallel_taskqueue</code>.
</p><p> Putting all this together, the general view of overloads for the
parallel algorithms look like this:
</p><div class="itemizedlist"><ul type="disc"><li><p>ISO C++ signature</p></li><li><p>ISO C++ signature + sequential_tag argument</p></li><li><p>ISO C++ signature + parallelism argument</p></li></ul></div><p> Please note that the implementation may use additional functions
(designated with the <code class="code">_switch</code> suffix) to dispatch from the
ISO C++ signature to the correct parallel version. Also, some of the
algorithms do not have support for run-time conditions, so the last
overload is therefore missing.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.parallel_mode.design.tuning"></a>Configuration and Tuning</h3></div></div></div><p> Some algorithm variants can be enabled/disabled/selected at compile-time.
See <a class="ulink" href="latest-doxygen/compiletime__settings_8h.html" target="_top">
<code class="code">&lt;compiletime_settings.h&gt;</code></a> and
See <a class="ulink" href="latest-doxygen/compiletime__settings_8h.html" target="_top">
<code class="code">&lt;features.h&gt;</code></a> for details.
</p><p>
To specify the number of threads to be used for an algorithm,
use <code class="code">omp_set_num_threads</code>.
To force a function to execute sequentially,
even though parallelism is switched on in general,
add <code class="code">__gnu_parallel::sequential_tag()</code>
to the end of the argument list.
</p><p>
Parallelism always incurs some overhead. Thus, it is not
helpful to parallelize operations on very small sets of data.
There are measures to avoid parallelizing stuff that is not worth it.
For each algorithm, a minimum problem size can be stated,
usually using the variable
<code class="code">__gnu_parallel::Settings::[algorithm]_minimal_n</code>.
Please see <a class="ulink" href="latest-doxygen/settings_8h.html" target="_top">
<code class="code">&lt;settings.h&gt;</code></a> for details.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.parallel_mode.design.impl"></a>Implementation Namespaces</h3></div></div></div><p> One namespace contain versions of code that are explicitly sequential:
<code class="code">__gnu_serial</code>.
</p><p> Two namespaces contain the parallel mode:
<code class="code">std::__parallel</code> and <code class="code">__gnu_parallel</code>.
</p><p> Parallel implementations of standard components, including
template helpers to select parallelism, are defined in <code class="code">namespace
std::__parallel</code>. For instance, <code class="code">std::transform</code> from
&lt;algorithm&gt; has a parallel counterpart in
<code class="code">std::__parallel::transform</code> from
&lt;parallel/algorithm&gt;. In addition, these parallel
implementations are injected into <code class="code">namespace
__gnu_parallel</code> with using declarations.
</p><p> Support and general infrastructure is in <code class="code">namespace
__gnu_parallel</code>.
</p><p> More information, and an organized index of types and functions
related to the parallel mode on a per-namespace basis, can be found in
the generated source documentation.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch31s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch31s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Using </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Testing</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch31s05.html 0 → 100644
<?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>Testing</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; parallel&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /><link rel="prev" href="bk01pt12ch31s04.html" title="Design" /><link rel="next" href="bk01pt12ch32.html" title="Chapter 32. Allocators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Testing</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch31s04.html">Prev</a> </td><th width="60%" align="center">Chapter 31. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.parallel_mode.test"></a>Testing</h2></div></div></div><p>
Both the normal conformance and regression tests and the
supplemental performance tests work.
</p><p>
To run the conformance and regression tests with the parallel mode
active,
</p><pre class="screen">
<strong class="userinput"><code>make check-parallel</code></strong>
</pre><p>
The log and summary files for conformance testing are in the
<code class="code">testsuite/parallel</code> directory.
</p><p>
To run the performance tests with the parallel mode active,
</p><pre class="screen">
<strong class="userinput"><code>check-performance-parallel</code></strong>
</pre><p>
The result file for performance testing are in the
<code class="code">testsuite</code> directory, in the file
<code class="code">libstdc++_performance.sum</code>. In addition, the
policy-based containers have their own visualizations, which have
additional software dependencies than the usual bare-boned text
file, and can be generated by using the <code class="code">make
doc-performance</code> rule in the testsuite's Makefile.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch31s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Design </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 32. Allocators</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch33.html 0 → 100644
<?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 33. Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bitmap_allocator.html" title="bitmap_allocator" /><link rel="next" href="bk01pt12ch33s02.html" title="HP/SGI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 33. Containers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch33s02.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.ext.containers"></a>Chapter 33. Containers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt12ch33.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch33s02.html">HP/SGI</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch33s03.html">Deprecated HP/SGI</a></span></dt></dl></div><p>
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.containers.pbds"></a>Policy Based Data Structures</h2></div></div></div><p>
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html" target="_top">More details here</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch33s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">bitmap_allocator </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> HP/SGI</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch33s02.html 0 → 100644
<?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>HP/SGI</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt12ch33.html" title="Chapter 33. Containers" /><link rel="prev" href="bk01pt12ch33.html" title="Chapter 33. Containers" /><link rel="next" href="bk01pt12ch33s03.html" title="Deprecated HP/SGI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">HP/SGI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch33.html">Prev</a> </td><th width="60%" align="center">Chapter 33. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch33s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.containers.sgi"></a>HP/SGI</h2></div></div></div><p>
</p><p>A few extensions and nods to backwards-compatibility have been made with
containers. Those dealing with older SGI-style allocators are dealt with
elsewhere. The remaining ones all deal with bits:
</p><p>The old pre-standard <code class="code">bit_vector</code> class is present for
backwards compatibility. It is simply a typedef for the
<code class="code">vector&lt;bool&gt;</code> specialization.
</p><p>The <code class="code">bitset</code> class has a number of extensions, described in the
rest of this item. First, we'll mention that this implementation of
<code class="code">bitset&lt;N&gt;</code> is specialized for cases where N number of
bits will fit into a single word of storage. If your choice of N is
within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
of the operations will be faster.
</p><p>There are
versions of single-bit test, set, reset, and flip member functions which
do no range-checking. If we call them member functions of an instantiation
of "bitset&lt;N&gt;," then their names and signatures are:
</p><pre class="programlisting">
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos, int val);
bitset&lt;N&gt;&amp; _Unchecked_reset (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_flip (size_t pos);
bool _Unchecked_test (size_t pos);
</pre><p>Note that these may in fact be removed in the future, although we have
no present plans to do so (and there doesn't seem to be any immediate
reason to).
</p><p>The semantics of member function <code class="code">operator[]</code> are not specified
in the C++ standard. A long-standing defect report calls for sensible
obvious semantics, which are already implemented here: <code class="code">op[]</code>
on a const bitset returns a bool, and for a non-const bitset returns a
<code class="code">reference</code> (a nested type). However, this implementation does
no range-checking on the index argument, which is in keeping with other
containers' <code class="code">op[]</code> requirements. The defect report's proposed
resolution calls for range-checking to be done. We'll just wait and see...
</p><p>Finally, two additional searching functions have been added. They return
the index of the first "on" bit, and the index of the first
"on" bit that is after <code class="code">prev</code>, respectively:
</p><pre class="programlisting">
size_t _Find_first() const;
size_t _Find_next (size_t prev) const;</pre><p>The same caveat given for the _Unchecked_* functions applies here also.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch33.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt12ch33.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch33s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 33. Containers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Deprecated HP/SGI</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch33s03.html 0 → 100644
<?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>Deprecated HP/SGI</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt12ch33.html" title="Chapter 33. Containers" /><link rel="prev" href="bk01pt12ch33s02.html" title="HP/SGI" /><link rel="next" href="bk01pt12ch34.html" title="Chapter 34. Utilities" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Deprecated HP/SGI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch33s02.html">Prev</a> </td><th width="60%" align="center">Chapter 33. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch34.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.containers.deprecated_sgi"></a>Deprecated HP/SGI</h2></div></div></div><p>
The SGI hashing classes <code class="classname">hash_set</code> and
<code class="classname">hash_set</code> have been deprecated by the
unordered_set, unordered_multiset, unordered_map,
unordered_multimap containers in TR1 and the upcoming C++0x, and
may be removed in future releases.
</p><p>The SGI headers</p><pre class="programlisting">
&lt;hash_map&gt;
&lt;hash_set&gt;
&lt;rope&gt;
&lt;slist&gt;
&lt;rb_tree&gt;
</pre><p>are all here;
<code class="code">&lt;hash_map&gt;</code> and <code class="code">&lt;hash_set&gt;</code>
are deprecated but available as backwards-compatible extensions,
as discussed further below. <code class="code">&lt;rope&gt;</code> is the
SGI specialization for large strings ("rope,"
"large strings," get it? Love that geeky humor.)
<code class="code">&lt;slist&gt;</code> is a singly-linked list, for when the
doubly-linked <code class="code">list&lt;&gt;</code> is too much space
overhead, and <code class="code">&lt;rb_tree&gt;</code> exposes the red-black
tree classes used in the implementation of the standard maps and
sets.
</p><p>Each of the associative containers map, multimap, set, and multiset
have a counterpart which uses a
<a class="ulink" href="http://www.sgi.com/tech/stl/HashFunction.html" target="_top">hashing
function</a> to do the arranging, instead of a strict weak ordering
function. The classes take as one of their template parameters a
function object that will return the hash value; by default, an
instantiation of
<a class="ulink" href="http://www.sgi.com/tech/stl/hash.html" target="_top">hash</a>.
You should specialize this functor for your class, or define your own,
before trying to use one of the hashing classes.
</p><p>The hashing classes support all the usual associative container
functions, as well as some extra constructors specifying the number
of buckets, etc.
</p><p>Why would you want to use a hashing class instead of the
“<span class="quote">normal</span>”implementations? Matt Austern writes:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>[W]ith a well chosen hash function, hash tables
generally provide much better average-case performance than
binary search trees, and much worse worst-case performance. So
if your implementation has hash_map, if you don't mind using
nonstandard components, and if you aren't scared about the
possibility of pathological cases, you'll probably get better
performance from hash_map.
</em></span>
</p></blockquote></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch33s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt12ch33.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch34.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">HP/SGI </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 34. Utilities</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch34.html 0 → 100644
<?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 34. Utilities</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch33s03.html" title="Deprecated HP/SGI" /><link rel="next" href="bk01pt12ch35.html" title="Chapter 35. Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 34. Utilities</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch33s03.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch35.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.ext.util"></a>Chapter 34. Utilities</h2></div></div></div><p>
The &lt;functional&gt; header contains many additional functors
and helper functions, extending section 20.3. They are
implemented in the file stl_function.h:
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">identity_element</code> for addition and multiplication. *
</p></li><li><p>The functor <code class="code">identity</code>, whose <code class="code">operator()</code>
returns the argument unchanged. *
</p></li><li><p>Composition functors <code class="code">unary_function</code> and
<code class="code">binary_function</code>, and their helpers <code class="code">compose1</code>
and <code class="code">compose2</code>. *
</p></li><li><p><code class="code">select1st</code> and <code class="code">select2nd</code>, to strip pairs. *
</p></li><li><p><code class="code">project1st</code> and <code class="code">project2nd</code>. * </p></li><li><p>A set of functors/functions which always return the same result. They
are <code class="code">constant_void_fun</code>, <code class="code">constant_binary_fun</code>,
<code class="code">constant_unary_fun</code>, <code class="code">constant0</code>,
<code class="code">constant1</code>, and <code class="code">constant2</code>. * </p></li><li><p>The class <code class="code">subtractive_rng</code>. * </p></li><li><p>mem_fun adaptor helpers <code class="code">mem_fun1</code> and
<code class="code">mem_fun1_ref</code> are provided for backwards compatibility. </p></li></ul></div><p>
20.4.1 can use several different allocators; they are described on the
main extensions page.
</p><p>
20.4.3 is extended with a special version of
<code class="code">get_temporary_buffer</code> taking a second argument. The
argument is a pointer, which is ignored, but can be used to specify
the template type (instead of using explicit function template
arguments like the standard version does). That is, in addition to
</p><pre class="programlisting">
get_temporary_buffer&lt;int&gt;(5);
</pre><p>
you can also use
</p><pre class="programlisting">
get_temporary_buffer(5, (int*)0);
</pre><p>
A class <code class="code">temporary_buffer</code> is given in stl_tempbuf.h. *
</p><p>
The specialized algorithms of section 20.4.4 are extended with
<code class="code">uninitialized_copy_n</code>. *
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch33s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch35.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Deprecated HP/SGI </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 35. Algorithms</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch35.html 0 → 100644
<?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 35. Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch34.html" title="Chapter 34. Utilities" /><link rel="next" href="bk01pt12ch36.html" title="Chapter 36. Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 35. Algorithms</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch34.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch36.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.ext.algorithms"></a>Chapter 35. Algorithms</h2></div></div></div><p>25.1.6 (count, count_if) is extended with two more versions of count
and count_if. The standard versions return their results. The
additional signatures return void, but take a final parameter by
reference to which they assign their results, e.g.,
</p><pre class="programlisting">
void count (first, last, value, n);</pre><p>25.2 (mutating algorithms) is extended with two families of signatures,
random_sample and random_sample_n.
</p><p>25.2.1 (copy) is extended with
</p><pre class="programlisting">
copy_n (_InputIter first, _Size count, _OutputIter result);</pre><p>which copies the first 'count' elements at 'first' into 'result'.
</p><p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
predicates. Look in the doxygen-generated pages for notes on these.
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">is_heap</code> tests whether or not a range is a heap.</p></li><li><p><code class="code">is_sorted</code> tests whether or not a range is sorted in
nondescending order.</p></li></ul></div><p>25.3.8 (lexigraphical_compare) is extended with
</p><pre class="programlisting">
lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
_InputIter2 first2, _InputIter2 last2)</pre><p>which does... what?
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch34.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch36.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 36. Numerics</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch36.html 0 → 100644
<?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 36. Numerics</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch35.html" title="Chapter 35. Algorithms" /><link rel="next" href="bk01pt12ch37.html" title="Chapter 37. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 36. Numerics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch35.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch37.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.ext.numerics"></a>Chapter 36. Numerics</h2></div></div></div><p>26.4, the generalized numeric operations such as accumulate, are extended
with the following functions:
</p><pre class="programlisting">
power (x, n);
power (x, n, moniod_operation);</pre><p>Returns, in FORTRAN syntax, "x ** n" where n&gt;=0. In the
case of n == 0, returns the <a class="ulink" href="#ch20" target="_top">identity element</a> for the
monoid operation. The two-argument signature uses multiplication (for
a true "power" implementation), but addition is supported as well.
The operation functor must be associative.
</p><p>The <code class="code">iota</code> function wins the award for Extension With the
Coolest Name. It "assigns sequentially increasing values to a range.
That is, it assigns value to *first, value + 1 to *(first + 1) and so
on." Quoted from SGI documentation.
</p><pre class="programlisting">
void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch35.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch37.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 35. Algorithms </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. Iterators</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch37.html 0 → 100644
<?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 37. Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch36.html" title="Chapter 36. Numerics" /><link rel="next" href="bk01pt12ch38.html" title="Chapter 38. Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 37. Iterators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch36.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch38.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.ext.iterators"></a>Chapter 37. Iterators</h2></div></div></div><p>24.3.2 describes <code class="code">struct iterator</code>, which didn't exist in the
original HP STL implementation (the language wasn't rich enough at the
time). For backwards compatibility, base classes are provided which
declare the same nested typedefs:
</p><div class="itemizedlist"><ul type="disc"><li><p>input_iterator</p></li><li><p>output_iterator</p></li><li><p>forward_iterator</p></li><li><p>bidirectional_iterator</p></li><li><p>random_access_iterator</p></li></ul></div><p>24.3.4 describes iterator operation <code class="code">distance</code>, which takes
two iterators and returns a result. It is extended by another signature
which takes two iterators and a reference to a result. The result is
modified, and the function returns nothing.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch36.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch38.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 36. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Input and Output</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch38.html 0 → 100644
<?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 38. Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch37.html" title="Chapter 37. Iterators" /><link rel="next" href="bk01pt12ch39.html" title="Chapter 39. Demangling" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 38. Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch37.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch39.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.ext.io"></a>Chapter 38. Input and Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt12ch38.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></div><p>
Extensions allowing <code class="code">filebuf</code>s to be constructed from
"C" types like FILE*s and file descriptors.
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.io.filebuf_derived"></a>Derived filebufs</h2></div></div></div><p>The v2 library included non-standard extensions to construct
<code class="code">std::filebuf</code>s from C stdio types such as
<code class="code">FILE*</code>s and POSIX file descriptors.
Today the recommended way to use stdio types with libstdc++
IOStreams is via the <code class="code">stdio_filebuf</code> class (see below),
but earlier releases provided slightly different mechanisms.
</p><div class="itemizedlist"><ul type="disc"><li><p>3.0.x <code class="code">filebuf</code>s have another ctor with this signature:
<code class="code">basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
</code>
This comes in very handy in a number of places, such as
attaching Unix sockets, pipes, and anything else which uses file
descriptors, into the IOStream buffering classes. The three
arguments are as follows:
</p><div class="itemizedlist"><ul type="circle"><li><p><code class="code">__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE
</p></li><li><p><code class="code">ios_base::openmode M </code>
// same as all the other uses of openmode
</p></li><li><p><code class="code">int_type B </code>
// buffer size, defaults to BUFSIZ if not specified
</p></li></ul></div><p>
For those wanting to use file descriptors instead of FILE*'s, I
invite you to contemplate the mysteries of C's <code class="code">fdopen()</code>.
</p></li><li><p>In library snapshot 3.0.95 and later, <code class="code">filebuf</code>s bring
back an old extension: the <code class="code">fd()</code> member function. The
integer returned from this function can be used for whatever file
descriptors can be used for on your platform. Naturally, the
library cannot track what you do on your own with a file descriptor,
so if you perform any I/O directly, don't expect the library to be
aware of it.
</p></li><li><p>Beginning with 3.1, the extra <code class="code">filebuf</code> constructor and
the <code class="code">fd()</code> function were removed from the standard
filebuf. Instead, <code class="code">&lt;ext/stdio_filebuf.h&gt;</code> contains
a derived class called
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html" target="_top"><code class="code">__gnu_cxx::stdio_filebuf</code></a>.
This class can be constructed from a C <code class="code">FILE*</code> or a file
descriptor, and provides the <code class="code">fd()</code> function.
</p></li></ul></div><p>If you want to access a <code class="code">filebuf</code>'s file descriptor to
implement file locking (e.g. using the <code class="code">fcntl()</code> system
call) then you might be interested in Henry Suter's
<a class="ulink" href="http://suter.home.cern.ch/suter/RWLock.html" target="_top">RWLock</a>
class.
</p><p>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch37.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch39.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 37. Iterators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 39. Demangling</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch39.html 0 → 100644
<?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 39. Demangling</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch38.html" title="Chapter 38. Input and Output" /><link rel="next" href="concurrency.html" title="Chapter 40. Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 39. Demangling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch38.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="concurrency.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.ext.demangle"></a>Chapter 39. Demangling</h2></div></div></div><p>
Transforming C++ ABI itentifiers (like RTTI symbols) into the
original C++ source identifiers is called
“<span class="quote">demangling.</span>”
</p><p>
If you have read the <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html" target="_top">source
documentation for <code class="code">namespace abi</code></a> then you are
aware of the cross-vendor C++ ABI in use by GCC. One of the
exposed functions is used for demangling,
<code class="code">abi::__cxa_demangle</code>.
</p><p>
In programs like <span class="command"><strong>c++filt</strong></span>, the linker, and other tools
have the ability to decode C++ ABI names, and now so can you.
</p><p>
(The function itself might use different demanglers, but that's the
whole point of abstract interfaces. If we change the implementation,
you won't notice.)
</p><p>
Probably the only times you'll be interested in demangling at runtime
are when you're seeing <code class="code">typeid</code> strings in RTTI, or when
you're handling the runtime-support exception classes. For example:
</p><pre class="programlisting">
#include &lt;exception&gt;
#include &lt;iostream&gt;
#include &lt;cxxabi.h&gt;
struct empty { };
template &lt;typename T, int N&gt;
struct bar { };
int main()
{
int status;
char *realname;
// exception classes not in &lt;stdexcept&gt;, thrown by the implementation
// instead of the user
std::bad_exception e;
realname = abi::__cxa_demangle(e.what(), 0, 0, &amp;status);
std::cout &lt;&lt; e.what() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
free(realname);
// typeid
bar&lt;empty,17&gt; u;
const std::type_info &amp;ti = typeid(u);
realname = abi::__cxa_demangle(ti.name(), 0, 0, &amp;status);
std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
free(realname);
return 0;
}
</pre><p>
This prints
</p><pre class="screen">
<code class="computeroutput">
St13bad_exception =&gt; std::bad_exception : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0
</code>
</pre><p>
The demangler interface is described in the source documentation
linked to above. It is actually written in C, so you don't need to
be writing C++ in order to demangle C++. (That also means we have to
use crummy memory management facilities, so don't forget to free()
the returned char array.)
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch38.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. 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 40. Concurrency</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch40s02.html 0 → 100644
<?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>Implementation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="concurrency.html" title="Chapter 40. Concurrency" /><link rel="prev" href="concurrency.html" title="Chapter 40. Concurrency" /><link rel="next" href="bk01pt12ch40s03.html" title="Use" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 40. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch40s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.concurrency.impl"></a>Implementation</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.atomic_fallbacks"></a>Using Builitin Atomic Functions</h3></div></div></div><p>The functions for atomic operations described above are either
implemented via compiler intrinsics (if the underlying host is
capable) or by library fallbacks.</p><p>Compiler intrinsics (builtins) are always preferred. However, as
the compiler builtins for atomics are not universally implemented,
using them directly is problematic, and can result in undefined
function calls. (An example of an undefined symbol from the use
of <code class="code">__sync_fetch_and_add</code> on an unsupported host is a
missing reference to <code class="code">__sync_fetch_and_add_4</code>.)
</p><p>In addition, on some hosts the compiler intrinsics are enabled
conditionally, via the <code class="code">-march</code> command line flag. This makes
usage vary depending on the target hardware and the flags used during
compile.
</p><p> If builtins are possible, <code class="code">_GLIBCXX_ATOMIC_BUILTINS</code>
will be defined.
</p><p>For the following hosts, intrinsics are enabled by default.
</p><div class="itemizedlist"><ul type="disc"><li><p>alpha</p></li><li><p>ia64</p></li><li><p>powerpc</p></li><li><p>s390</p></li></ul></div><p>For others, some form of <code class="code">-march</code> may work. On
non-ancient x86 hardware, <code class="code">-march=native</code> usually does the
trick.</p><p> For hosts without compiler intrinsics, but with capable
hardware, hand-crafted assembly is selected. This is the case for the following hosts:
</p><div class="itemizedlist"><ul type="disc"><li><p>cris</p></li><li><p>hppa</p></li><li><p>i386</p></li><li><p>i486</p></li><li><p>m48k</p></li><li><p>mips</p></li><li><p>sparc</p></li></ul></div><p>And for the rest, a simulated atomic lock via pthreads.
</p><p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html" target="_top"> documentation</a>.
</p><p> More details on the library fallbacks from the porting <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety" target="_top">section</a>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.thread"></a>Thread Abstraction</h3></div></div></div><p>A thin layer above IEEE 1003.1 (ie pthreads) is used to abstract
the thread interface for GCC. This layer is called "gthread," and is
comprised of one header file that wraps the host's default thread layer with
a POSIX-like interface.
</p><p> The file &lt;gthr-default.h&gt; points to the deduced wrapper for
the current host. In libstdc++ implementation files,
&lt;bits/gthr.h&gt; is used to select the proper gthreads file.
</p><p>Within libstdc++ sources, all calls to underlying thread functionality
use this layer. More detail as to the specific interface can be found in the source <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html" target="_top">documentation</a>.
</p><p>By design, the gthread layer is interoperable with the types,
functions, and usage found in the usual &lt;pthread.h&gt; file,
including <code class="code">pthread_t</code>, <code class="code">pthread_once_t</code>, <code class="code">pthread_create</code>,
etc.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="concurrency.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concurrency.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch40s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 40. Concurrency </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Use</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12ch40s03.html 0 → 100644
<?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>Use</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="concurrency.html" title="Chapter 40. Concurrency" /><link rel="prev" href="bk01pt12ch40s02.html" title="Implementation" /><link rel="next" href="appendix_contributing.html" title="Appendix A. Contributing" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Use</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch40s02.html">Prev</a> </td><th width="60%" align="center">Chapter 40. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.concurrency.use"></a>Use</h2></div></div></div><p>Typical usage of the last two constructs is demonstrated as follows:
</p><pre class="programlisting">
#include &lt;ext/concurrence.h&gt;
namespace
{
__gnu_cxx::__mutex safe_base_mutex;
} // anonymous namespace
namespace other
{
void
foo()
{
__gnu_cxx::__scoped_lock sentry(safe_base_mutex);
for (int i = 0; i &lt; max; ++i)
{
_Safe_iterator_base* __old = __iter;
__iter = __iter-&lt;_M_next;
__old-&lt;_M_detach_single();
}
}
</pre><p>In this sample code, an anonymous namespace is used to keep
the <code class="code">__mutex</code> private to the compilation unit,
and <code class="code">__scoped_lock</code> is used to guard access to the critical
section within the for loop, locking the mutex on creation and freeing
the mutex as control moves out of this block.
</p><p>Several exception classes are used to keep track of
concurrence-related errors. These classes
are: <code class="code">__concurrence_lock_error</code>, <code class="code">__concurrence_unlock_error</code>, <code class="code">__concurrence_wait_error</code>,
and <code class="code">__concurrence_broadcast_error</code>.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch40s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concurrency.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Implementation </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix A. Contributing</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/bk01pt12pr03.html 0 → 100644
<?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></title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="extensions.html" title="Part XII. Extensions" /><link rel="next" href="bk01pt12ch29.html" title="Chapter 29. Compile Time Checks" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch29.html">Next</a></td></tr></table><hr /></div><div class="preface" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id516952"></a></h2></div></div></div><p>
Here we will make an attempt at describing the non-Standard extensions to
the library. Some of these are from SGI's STL, some of these are GNU's,
and some just seemed to appear on the doorstep.
</p><p><span class="emphasis"><em>Before</em></span> you leap in and use any of these
extensions, be aware of two things:
</p><div class="orderedlist"><ol type="1"><li><p>
Non-Standard means exactly that.
</p><p>
The behavior, and the very
existence, of these extensions may change with little or no
warning. (Ideally, the really good ones will appear in the next
revision of C++.) Also, other platforms, other compilers, other
versions of g++ or libstdc++ may not recognize these names, or
treat them differently, or...
</p></li><li><p>
You should know how to <a class="ulink" href="XXX" target="_top">access
these headers properly</a>.
</p></li></ol></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch29.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part XII. Extensions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 29. Compile Time Checks</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/build.html 0 → 100644
<?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>Build</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; build&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt01ch02.html" title="Chapter 2. Setup" /><link rel="prev" href="bk01pt01ch02.html" title="Chapter 2. Setup" /><link rel="next" href="test.html" title="Test" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Build</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch02.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Setup</th><td width="20%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.setup.build"></a>Build</h2></div></div></div><p>
Because libstdc++ is part of GCC, the primary source for
installation instructions is
<a class="ulink" href="http://gcc.gnu.org/install/" target="_top">the GCC install page</a>.
Additional data is given here only where it applies to libstdc++.
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build.prereq"></a>Prerequisites</h3></div></div></div><p>
The list of software needed to build the library is kept with the
rest of the compiler, at
<a class="ulink" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">
http://gcc.gnu.org/install/prerequisites.html</a>. The same page
also lists the tools you will need if you wish to modify the source.
</p><p>As of GCC 4.0.1 the minimum version of binutils required to build
libstdc++ is <code class="code">2.15.90.0.1.1</code>. You can get snapshots
(as well as releases) of binutils from
<a class="ulink" href="ftp://sources.redhat.com/pub/binutils" target="_top">
ftp://sources.redhat.com/pub/binutils</a>.
Older releases of libstdc++ do not require such a recent version,
but to take full advantage of useful space-saving features and
bug-fixes you should use a recent binutils if possible.
The configure process will automatically detect and use these
features if the underlying support is present.
</p><p>
Finally, a few system-specific requirements:
</p><div class="variablelist"><dl><dt><span class="term">linux</span></dt><dd><p>
If gcc 3.1.0 or later on is being used on linux, an attempt
will be made to use "C" library functionality necessary for
C++ named locale support. For gcc 3.2.1 and later, this
means that glibc 2.2.5 or later is required and the "C"
library de_DE locale information must be installed.
</p><p>
Note however that the sanity checks involving the de_DE
locale are skipped when an explicit --enable-clocale=gnu
configure option is used: only the basic checks are carried
out, defending against misconfigurations.
</p><p>
If the 'gnu' locale model is being used, the following
locales are used and tested in the libstdc++ testsuites.
The first column is the name of the locale, the second is
the character set it is expected to use.
</p><pre class="programlisting">
de_DE ISO-8859-1
de_DE@euro ISO-8859-15
en_HK ISO-8859-1
en_PH ISO-8859-1
en_US ISO-8859-1
en_US.ISO-8859-1 ISO-8859-1
en_US.ISO-8859-15 ISO-8859-15
en_US.UTF-8 UTF-8
es_ES ISO-8859-1
es_MX ISO-8859-1
fr_FR ISO-8859-1
fr_FR@euro ISO-8859-15
is_IS UTF-8
it_IT ISO-8859-1
ja_JP.eucjp EUC-JP
se_NO.UTF-8 UTF-8
ta_IN UTF-8
zh_TW BIG5
</pre><p>Failure to have the underlying "C" library locale
information installed will mean that C++ named locales for the
above regions will not work: because of this, the libstdc++
testsuite will skip the named locale tests. If this isn't an
issue, don't worry about it. If named locales are needed, the
underlying locale information must be installed. Note that
rebuilding libstdc++ after the "C" locales are installed is not
necessary.
</p><p>
To install support for locales, do only one of the following:
</p><div class="itemizedlist"><ul type="disc"><li><p>install all locales</p><div class="itemizedlist"><ul type="circle"><li><p>with RedHat Linux:
</p><p> <code class="code"> export LC_ALL=C </code>
</p><p> <code class="code"> rpm -e glibc-common --nodeps </code>
</p><p>
<code class="code"> rpm -i --define "_install_langs all"
glibc-common-2.2.5-34.i386.rpm
</code>
</p></li><li><p>
Instructions for other operating systems solicited.
</p></li></ul></div></li><li><p>install just the necessary locales</p><div class="itemizedlist"><ul type="circle"><li><p>with Debian Linux:</p><p> Add the above list, as shown, to the file
<code class="code">/etc/locale.gen</code> </p><p> run <code class="code">/usr/sbin/locale-gen</code> </p></li><li><p>on most Unix-like operating systems:</p><p><code class="code"> localedef -i de_DE -f ISO-8859-1 de_DE </code></p><p>(repeat for each entry in the above list) </p></li><li><p>
Instructions for other operating systems solicited.
</p></li></ul></div></li></ul></div></dd></dl></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="build.configure"></a>Make</h3></div></div></div><p>If you have never done this before, you should read the basic
<a class="ulink" href="http://gcc.gnu.org/install/" target="_top">GCC Installation
Instructions</a> first. Read <span class="emphasis"><em>all of them</em></span>.
<span class="emphasis"><em>Twice.</em></span>
</p><p>When building libstdc++ you'll have to configure
the entire <span class="emphasis"><em>gccsrcdir</em></span> directory. The full list of libstdc++
specific configuration options, not dependent on the specific compiler
release being used, can be found <a class="ulink" href="configopts.html" target="_top">here</a>.
</p><p>Consider possibly using --enable-languages=c++ to save time by only
building the C++ language parts.
</p><pre class="programlisting">
cd <span class="emphasis"><em>gccbuilddir</em></span>
<span class="emphasis"><em>gccsrcdir</em></span>/configure --prefix=<span class="emphasis"><em>destdir</em></span> --other-opts...</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt01ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Setup </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Test</td></tr></table></div></body></html>
libstdc++-v3/doc/html/manual/concurrency.html 0 → 100644
<?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 40. Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch39.html" title="Chapter 39. Demangling" /><link rel="next" href="bk01pt12ch40s02.html" title="Implementation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 40. Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch39.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch40s02.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.ext.concurrency"></a>Chapter 40. Concurrency</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="sect2"><a href="concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch40s02.html">Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch40s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builitin Atomic Functions</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch40s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch40s03.html">Use</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.concurrency.design"></a>Design</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.threads"></a>Interface to Locks and Mutexes</h3></div></div></div><p>The file &lt;ext/concurrence.h&gt; contains all the higher-level
constructs for playing with threads. In contrast to the atomics layer,
the concurrence layer consists largely of types. All types are defined within <code class="code">namespace __gnu_cxx</code>.
</p><p>
These types can be used in a portable manner, regardless of the
specific environment. They are carefully designed to provide optimum
efficiency and speed, abstracting out underlying thread calls and
accesses when compiling for single-threaded situations (even on hosts
that support multiple threads.)
</p><p>The enumerated type <code class="code">_Lock_policy</code> details the set of
available locking
policies: <code class="code">_S_single</code>, <code class="code">_S_mutex</code>,
and <code class="code">_S_atomic</code>.
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">_S_single</code></p><p>Indicates single-threaded code that does not need locking.
</p></li><li><p><code class="code">_S_mutex</code></p><p>Indicates multi-threaded code using thread-layer abstractions.
</p></li><li><p><code class="code">_S_atomic</code></p><p>Indicates multi-threaded code using atomic operations.
</p></li></ul></div><p>The compile-time constant <code class="code">__default_lock_policy</code> is set
to one of the three values above, depending on characteristics of the
host environment and the current compilation flags.
</p><p>Two more datatypes make up the rest of the
interface: <code class="code">__mutex</code>, and <code class="code">__scoped_lock</code>.
</p><p>
</p><p>The scoped lock idiom is well-discussed within the C++
community. This version takes a <code class="code">__mutex</code> reference, and
locks it during construction of <code class="code">__scoped_locke</code> and
unlocks it during destruction. This is an efficient way of locking
critical sections, while retaining exception-safety.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.atomics"></a>Interface to Atomic Functions</h3></div></div></div><p>
Two functions and one type form the base of atomic support.
</p><p>The type <code class="code">_Atomic_word</code> is a signed integral type
supporting atomic operations.
</p><p>
The two functions functions are:
</p><pre class="programlisting">
_Atomic_word
__exchange_and_add_dispatch(volatile _Atomic_word*, int);
void
__atomic_add_dispatch(volatile _Atomic_word*, int);
</pre><p>Both of these functions are declared in the header file
&lt;ext/atomicity.h&gt;, and are in <code class="code">namespace __gnu_cxx</code>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="code">
__exchange_and_add_dispatch
</code>
</p><p>Adds the second argument's value to the first argument. Returns the old value.
</p></li><li><p>
<code class="code">
__atomic_add_dispatch
</code>
</p><p>Adds the second argument's value to the first argument. Has no return value.
</p></li></ul></div><p>
These functions forward to one of several specialized helper
functions, depending on the circumstances. For instance,
</p><p>
<code class="code">
__exchange_and_add_dispatch
</code>
</p><p>
Calls through to either of:
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">__exchange_and_add</code>
</p><p>Multi-thread version. Inlined if compiler-generated builtin atomics
can be used, otherwise resolved at link time to a non-builtin code
sequence.
</p></li><li><p><code class="code">__exchange_and_add_single</code>
</p><p>Single threaded version. Inlined.</p></li></ul></div><p>However, only <code class="code">__exchange_and_add_dispatch</code>
and <code class="code">__atomic_add_dispatch</code> should be used. These functions
can be used in a portable manner, regardless of the specific
environment. They are carefully designed to provide optimum efficiency
and speed, abstracting out atomic accesses when they are not required
(even on hosts that support compiler intrinsics for atomic
operations.)
</p><p>
In addition, there are two macros
</p><p>
<code class="code">
_GLIBCXX_READ_MEM_BARRIER
</code>
</p><p>
<code class="code">
_GLIBCXX_WRITE_MEM_BARRIER
</code>
</p><p>
Which expand to the appropriate write and read barrier required by the
host hardware and operating system.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch39.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch40s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 39. Demangling </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation</td></tr></table></div></body></html>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment