procyberian/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

faq.xml: Link to manual.

Browse source 
2010-04-22  Jonathan Wakely  <jwakely.gcc@gmail.com>

	* doc/xml/faq.xml: Link to manual.
	* doc/xml/manual/using.xml: Expand dynamic libraries section.
	* doc/xml/manual/strings.xml: Mention shrink_to_fit() member.
	* doc/xml/manual/prerequisites.xml: Link to doxygen requirements.
	* doc/xml/manual/appendix_contributing.xml: Update Bash version.
	* doc/html/*: Regenerate.

From-SVN: r158624
This commit is contained in:
Jonathan Wakely 2010-04-21 23:33:44 +00:00 • committed by Jonathan Wakely
parent bc58d7e1bd
commit 18246cedb5
135 changed files with 4338 additions and 4205 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
libstdc++-v3/ChangeLog
View file

@ -1,3 +1,12 @@
2010-04-22 Jonathan Wakely <jwakely.gcc@gmail.com>
* doc/xml/faq.xml: Link to manual.
* doc/xml/manual/using.xml: Expand dynamic libraries section.
* doc/xml/manual/strings.xml: Mention shrink_to_fit() member.
* doc/xml/manual/prerequisites.xml: Link to doxygen requirements.
* doc/xml/manual/appendix_contributing.xml: Update Bash version.
* doc/html/*: Regenerate.
2010-04-13 Ian Lance Taylor <iant@google.com>
* include/backward/hash_map: Don't #include "backward_warning.h"

35
libstdc++-v3/doc/html/api.html
View file

@ -1,24 +1,25 @@
<?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.75.2" /><link rel="home" 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" title="API and Source Level Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="api"></a>API and Source Level Documentation</h2></div><div><p class="copyright">Copyright ©
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>API Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" 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 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" title="API Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="api"></a>API Documentation</h2></div><div><p class="copyright">Copyright ©
2008
,
2010
<a class="ulink" href="http://www.fsf.org/" target="_top">FSF
</a>
</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id561368"></a><p>
</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id515244"></a><p>
<a class="link" href="manual/license.html" title="License">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.
The GNU C++ library sources have been specially formatted so that
with the proper invocation of another tool (Doxygen), a set of
indexed reference material can generated from the sources files
themselves. The resultant documentation is referred to as the API
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:
The API documentation, rendered into HTML, can be viewed online:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-3.4/index.html" target="_top">for the 3.4 release
</a>
@ -39,16 +40,14 @@ viewed online:
</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
The rendered HTML, as above, is also available for download on the
gcc.org site in a directory located 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
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).
In addition, a rendered set of man pages are available in the same
location specified above. 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>

2
libstdc++-v3/doc/html/bk02.html
View file

@ -1,3 +1,3 @@
<?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.75.2" /><link rel="home" 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"><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>
<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.75.2" /><link rel="home" 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 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"><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 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 Documentation</td></tr></table></div></body></html>

2
libstdc++-v3/doc/html/bk03.html
View file

@ -1,3 +1,3 @@
<?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.75.2" /><link rel="home" 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"><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>
<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.75.2" /><link rel="home" 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 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"><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 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>

16
libstdc++-v3/doc/html/faq.html
View file

@ -4,7 +4,7 @@
2008
<a class="ulink" href="http://www.fsf.org" target="_top">FSF</a>
</p></div></div><hr /></div><div class="qandaset" title="Frequently Asked Questions"><a id="id571249"></a><dl><dt>1. <a href="faq.html#faq.info">General Information</a></dt><dd><dl><dt>1.1. <a href="faq.html#faq.what">
</p></div></div><hr /></div><div class="qandaset" title="Frequently Asked Questions"><a id="id621954"></a><dl><dt>1. <a href="faq.html#faq.info">General Information</a></dt><dd><dl><dt>1.1. <a href="faq.html#faq.what">
What is libstdc++?
</a></dt><dt>1.2. <a href="faq.html#faq.why">
Why should I use libstdc++?
@ -315,12 +315,15 @@
and <span class="command"><strong>ldconfig</strong></span> for more information. The dynamic
linker has different names on different platforms but the man page
is usually called something such as <code class="filename">ld.so/rtld/dld.so</code>.
</p><p>
Using LD_LIBRARY_PATH is not always the best solution, <a class="link" href="manual/using_dynamic_or_shared.html#manual.intro.using.linkage.dynamic" title="Finding Dynamic or Shared Libraries">Finding Dynamic or Shared
Libraries</a> in the manual gives some alternatives.
</p></td></tr><tr class="question" title="3.5."><td align="left" valign="top"><a id="faq.what_is_libsupcxx"></a><a id="q-what_is_libsupcxx"></a><p><b>3.5.</b></p></td><td align="left" valign="top"><p>
What's libsupc++?
</p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-what_is_libsupcxx"></a></td><td align="left" valign="top"><p>
If the only functions from <code class="filename">libstdc++.a</code>
which you need are language support functions (those listed in
<a class="link" href="manual/support.html" title="Part II.  Support">clause 18</a> of the
<a class="link" href="manual/support.html" title="Chapter 4.  Support">clause 18</a> of the
standard, e.g., <code class="function">new</code> and
<code class="function">delete</code>), then try linking against
<code class="filename">libsupc++.a</code>, which is a subset of
@ -647,8 +650,9 @@
typo, or wrong visibility, or you just plain forgot, etc).
</p><p>
More information, including how to optionally enable/disable the
checks, is available
<a class="link" href="manual/bk01pt03ch08.html" title="Chapter 8. Concept Checking">here</a>.
checks, is available in the
<a class="link" href="manual/bk01pt02ch05s02.html" title="Concept Checking">Diagnostics</a>.
chapter of the manual.
</p></td></tr><tr class="question" title="6.6."><td align="left" valign="top"><a id="faq.dlopen_crash"></a><a id="q-dlopen_crash"></a><p><b>6.6.</b></p></td><td align="left" valign="top"><p>
Program crashes when using library code in a
dynamically-loaded library
@ -685,7 +689,7 @@
list::size() is O(n)!
</p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-list_size_on"></a></td><td align="left" valign="top"><p>
See
the <a class="link" href="manual/containers.html" title="Part VII.  Containers">Containers</a>
the <a class="link" href="manual/containers.html" title="Chapter 9.  Containers">Containers</a>
chapter.
</p></td></tr><tr class="question" title="6.9."><td align="left" valign="top"><a id="faq.easy_to_fix"></a><a id="q-easy_to_fix"></a><p><b>6.9.</b></p></td><td align="left" valign="top"><p>
Aw, that's easy to fix!
@ -869,6 +873,6 @@
    </p></div><p>
The copy will take O(n) time and the swap is constant time.
</p><p>
See <a class="link" href="manual/bk01pt05ch13s05.html" title="Shrink to Fit">Shrink-to-fit
See <a class="link" href="manual/strings.html#strings.string.shrink" title="Shrink to Fit">Shrink-to-fit
strings</a> for a similar solution for strings.
</p></td></tr></tbody></table></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk03.html">Up</a></td><td width="40%" align="right"> </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>

157
libstdc++-v3/doc/html/manual/abi.html
View file

@ -8,12 +8,12 @@
C++ applications often dependent on specific language support
routines, say for throwing exceptions, or catching exceptions, and
perhaps also dependent on features in the C++ Standard Library.
</p><p>
</p><p>
The C++ Standard Library has many include files, types defined in
those include files, specific named functions, and other
behavior. The text of these behaviors, as written in source include
files, is called the Application Programing Interface, or API.
</p><p>
</p><p>
Furthermore, C++ source that is compiled into object files is
transformed by the compiler: it arranges objects with specific
alignment and in a particular layout, mangling names according to a
@ -32,7 +32,7 @@
<code class="code">-fno-exceptions</code>, but include others: see the complete
list in the GCC manual under the heading <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options" target="_top">Options
for Code Generation Conventions</a>.
</p><p>
</p><p>
The configure options used when building a specific libstdc++
version may also impact the resulting library ABI. The available
configure options, and their impact on the library ABI, are
@ -240,11 +240,11 @@ int main()
%g++ hello.cc -o hello.out
%ldd hello.out
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
%nm hello.out
</pre><p>
@ -273,7 +273,7 @@ class that would otherwise have implicit versions. This will change
the way the compiler deals with this class in by-value return
statements or parameters: instead of being passing instances of this
class in registers, the compiler will be forced to use memory. See <a class="ulink" href="http://www.codesourcery.com/cxx-abi/abi.html#calls" target="_top"> this part</a>
of the C++ ABI documentation for further details.
of the C++ ABI documentation for further details.
</p></li></ol></div></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"></a>Implementation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Separation of interface and implementation
</p><p>
@ -298,7 +298,7 @@ class in registers, the compiler will be forced to use memory. See <a class="uli
char</code> and <code class="code"> wchar_t</code> instantiations, and
includes <code class="code"> basic_string</code>, the locale facets, and the
types in <code class="code"> iostreams</code>.
</p></dd></dl></div><p>
</p></dd></dl></div><p>
In addition, these techniques have the additional benefit that they
reduce binary size, which can increase runtime performance.
</p></li><li class="listitem"><p>
@ -329,7 +329,7 @@ standard includes.</p></li></ol></div></div><div class="sect2" title="Testing"><
</p><p>
Testing the C++ compiler ABI can be done various ways.
</p><p>
One. Intel ABI checker.
One. Intel ABI checker.
</p><p>
Two.
The second is yet unreleased, but has been announced on the gcc
@ -344,16 +344,16 @@ discussed on the gcc mailing lists.
</p><p>
Testing the C++ library ABI can also be done various ways.
</p><p>
One.
(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
One.
(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
one with a new compiler and an old library, and the other with an old
compiler and a new library, and look for testsuite regressions)
</p><p>
Details on how to set this kind of test up can be found here:
http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
</p><p>
Two.
Use the 'make check-abi' rule in the libstdc++ Makefile.
Two.
Use the 'make check-abi' rule in the libstdc++ Makefile.
</p><p>
This is a proactive check the library ABI. Currently, exported symbol
names that are either weak or defined are checked against a last known
@ -372,7 +372,7 @@ machinery.
</p><p>
This dataset is insufficient, yet a start. Also needed is a
comprehensive check for all user-visible types part of the standard
library for sizeof() and alignof() changes.
library for sizeof() and alignof() changes.
</p><p>
Verifying compatible layouts of objects is not even attempted. It
should be possible to use sizeof, alignof, and offsetof to compute
@ -403,7 +403,7 @@ exceptions, locale, etc.
%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
%ar cru libone.a a.o
%ar cru libone.a a.o
</pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting">
%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
@ -413,24 +413,24 @@ exceptions, locale, etc.
%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
%ar cru libtwo.a b.o
%ar cru libtwo.a b.o
</pre><p> ...with the resulting libraries looking like </p><pre class="screen">
<code class="computeroutput">
%ldd libone.so.1.0.0
libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
%ldd libtwo.so.1.0.0
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</code>
</pre><p>
</pre><p>
Then, the "C" compiler is used to compile a source file that uses
functions from each library.
</p><pre class="programlisting">
@ -440,18 +440,18 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.
</p><pre class="screen">
<code class="computeroutput">
%ldd a.out
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
/lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</code>
</pre><p>
This resulting binary, when executed, will be able to safely use
code from both liba, and the dependent libstdc++.so.6, and libb,
with the dependent libstdc++.so.5.
</p></div></div><div class="sect2" title="Outstanding Issues"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"></a>Outstanding Issues</h3></div></div></div><p>
</p></div></div><div class="sect2" title="Outstanding Issues"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"></a>Outstanding Issues</h3></div></div></div><p>
Some features in the C++ language make versioning especially
difficult. In particular, compiler generated constructs such as
implicit instantiations for templates, typeinfo information, and
@ -464,60 +464,71 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.
<a class="ulink" href="http://gcc.gnu.org/PR24660" target="_top">24660: versioning weak symbols in libstdc++</a>
</p><p>
<a class="ulink" href="http://gcc.gnu.org/PR19664" target="_top">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a>
</p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="ABIcheck, a vague idea of checking ABI compatibility"><a id="id725008"></a><p><span class="title"><i>
ABIcheck, a vague idea of checking ABI compatibility
</i>. </span><span class="biblioid">
</p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id422104"></a><p><span class="biblioid">
<a class="ulink" href="http://abicheck.sourceforge.net/" target="_top">
<em class="citetitle">
ABIcheck, a vague idea of checking ABI compatibility
</em>
</a>
. </span></p></div><div class="biblioentry" title="C++ ABI Reference"><a id="id725026"></a><p><span class="title"><i>
C++ ABI Reference
</i>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id422124"></a><p><span class="biblioid">
<a class="ulink" href="http://www.codesourcery.com/public/cxx-abi/" target="_top">
<em class="citetitle">
C++ ABI Reference
</em>
</a>
. </span></p></div><div class="biblioentry" title="Intel® Compilers for Linux* -Compatibility with the GNU Compilers"><a id="id725043"></a><p><span class="title"><i>
Intel® Compilers for Linux* -Compatibility with the GNU Compilers
</i>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id422144"></a><p><span class="biblioid">
<a class="ulink" href="http://www.intel.com/cd/software/products/asmo-na/eng/284736.htm" target="_top">
<em class="citetitle">
Intel Compilers for Linux Compatibility with the GNU Compilers
</em>
</a>
. </span></p></div><div class="biblioentry" title="Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)"><a id="id725060"></a><p><span class="title"><i>
Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
</i>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id422164"></a><p><span class="biblioid">
<a class="ulink" href="http://docs.sun.com/app/docs/doc/817-1984" target="_top">
<em class="citetitle">
Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
</em>
</a>
. </span></p></div><div class="biblioentry" title="Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)"><a id="id725077"></a><p><span class="title"><i>
Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
</i>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id493165"></a><p><span class="biblioid">
<a class="ulink" href="http://docs.sun.com/app/docs/doc/819-5266" target="_top">
<em class="citetitle">
Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
</em>
</a>
. </span></p></div><div class="biblioentry" title="How to Write Shared Libraries"><a id="id725094"></a><p><span class="title"><i>
How to Write Shared Libraries
</i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id493184"></a><p><span class="biblioid">
<a class="ulink" href="http://people.redhat.com/drepper/dsohowto.pdf" target="_top">
<em class="citetitle">
How to Write Shared Libraries
</em>
</a>
. </span></p></div><div class="biblioentry" title="C++ ABI for the ARM Architecture"><a id="id725122"></a><p><span class="title"><i>
C++ ABI for the ARM Architecture
</i>. </span><span class="biblioid">
. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span></p></div><div class="biblioentry"><a id="id493215"></a><p><span class="biblioid">
<a class="ulink" href="http://www.arm.com/miscPDFs/8033.pdf" target="_top">
<em class="citetitle">
C++ ABI for the ARM Architecture
</em>
</a>
. </span></p></div><div class="biblioentry" title="Dynamic Shared Objects: Survey and Issues"><a id="id651420"></a><p><span class="title"><i>
Dynamic Shared Objects: Survey and Issues
</i>. </span><span class="subtitle">
ISO C++ J16/06-0046
. </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
. </span></p></div><div class="biblioentry"><a id="id493234"></a><p><span class="biblioid">
<a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html" target="_top">
<em class="citetitle">
Dynamic Shared Objects: Survey and Issues
</em>
</a>
. </span></p></div><div class="biblioentry" title="Versioning With Namespaces"><a id="id651453"></a><p><span class="title"><i>
Versioning With Namespaces
</i>. </span><span class="subtitle">
ISO C++ J16/06-0083
. </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
. </span><span class="subtitle">
ISO C++ J16/06-0046
. </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id493269"></a><p><span class="biblioid">
<a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html" target="_top">
<em class="citetitle">
Versioning With Namespaces
</em>
</a>
. </span></p></div><div class="biblioentry" title="Binary Compatibility of Shared Libraries Implemented in C++ on GNU/Linux Systems"><a id="id651486"></a><p><span class="title"><i>
Binary Compatibility of Shared Libraries Implemented in C++ on GNU/Linux Systems
</i>. </span><span class="subtitle">
SYRCoSE 2009
. </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span><span class="biblioid">
. </span><span class="subtitle">
ISO C++ J16/06-0083
. </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id493304"></a><p><span class="biblioid">
<a class="ulink" href="http://syrcose.ispras.ru/2009/files/SYRCoSE2009-CfP.pdf" target="_top">
<em class="citetitle">
Binary Compatibility of Shared Libraries Implemented in C++
on GNU/Linux Systems
</em>
</a>
. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Test </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>
. </span><span class="subtitle">
SYRCoSE 2009
. </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Test </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>

60
libstdc++-v3/doc/html/manual/algorithms.html
View file

@ -1,9 +1,61 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="home" 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. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 11.  Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="iterators.html" title="Chapter 10.  Iterators" /><link rel="next" href="numerics.html" title="Chapter 12.  Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. 
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" title="Part IX.  Algorithms"><div class="titlepage"><div><div><h1 class="title"><a id="manual.algorithms"></a>Part IX. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="iterators.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="numerics.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 11.  Algorithms"><div class="titlepage"><div><div><h2 class="title"><a id="std.algorithms"></a>Chapter 11. 
Algorithms
<a id="id638163" class="indexterm"></a>
</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>
<a id="id505811" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="algorithms.html#std.algorithms.mutating">Mutating</a></span></dt><dd><dl><dt><span class="sect2"><a href="algorithms.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt></dl></dd></dl></div><p>
The neatest accomplishment of the algorithms sect1 is that all the
work is done via iterators, not containers directly. This means two
important things:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><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 class="listitem"><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="link" href="containers.html" title="Chapter 9.  Containers">containers sect1</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="link" href="iterators.html" title="Chapter 10.  Iterators">iterators sect1</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 class="sect1" title="Mutating"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.algorithms.mutating"></a>Mutating</h2></div></div></div><div class="sect2" title="swap"><div class="titlepage"><div><div><h3 class="title"><a id="algorithms.mutating.swap"></a><code class="function">swap</code></h3></div></div></div><div class="sect3" title="Specializations"><div class="titlepage"><div><div><h4 class="title"><a id="algorithms.swap.specializations"></a>Specializations</h4></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><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="bk01pt02.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">Chapter 10. 
Iterators
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. 
Numerics
</td></tr></table></div></body></html>

14
libstdc++-v3/doc/html/manual/api.html
View file

@ -30,8 +30,8 @@ Removal of <code class="filename">ext/tree</code>, moved to <code class="filenam
</p><p>Symbol versioning introduced for shared library.</p><p>Removal of include <code class="filename">backward/strstream.h</code>.</p><p>Allocator changes. Change <code class="code">__malloc_alloc</code> to <code class="code">malloc_allocator</code> and <code class="code">__new_alloc</code> to <code class="code">new_allocator</code>. </p><p> For GCC releases from 2.95 through the 3.1 series, defining
<code class="literal">__USE_MALLOC</code> on the gcc command line would change the
default allocation strategy to instead use <code class="code"> malloc</code> and
<code class="function">free</code>. (This same functionality is now spelled <code class="literal">_GLIBCXX_FORCE_NEW</code>, see
<a class="link" href="using_macros.html" title="Macros">this page</a>
<code class="function">free</code>. (This same functionality is now spelled <code class="literal">_GLIBCXX_FORCE_NEW</code>, see
<a class="link" href="using_macros.html" title="Macros">this page</a>
for details.
</p><p>Error handling in iostreams cleaned up, made consistent. </p></div><div class="sect2" title="3.3"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_330"></a><code class="constant">3.3</code></h3></div></div></div><p>
</p></div><div class="sect2" title="3.4"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_340"></a><code class="constant">3.4</code></h3></div></div></div><p>
@ -75,11 +75,11 @@ _Alloc_traits</code> have been removed.
<span class="type">__alloc</span> to select an underlying allocator that
satisfied memory allocation requests. The selection of this
underlying allocator was not user-configurable.
</p><div class="table"><a id="id653273"></a><p class="title"><b>Table B.1. Extension Allocators</b></p><div class="table-contents"><table summary="Extension Allocators" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Allocator (3.4)</th><th align="left">Header (3.4)</th><th align="left">Allocator (3.[0-3])</th><th align="left">Header (3.[0-3])</th></tr></thead><tbody><tr><td align="left"><code class="classname">__gnu_cxx::new_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/new_allocator.h</code></td><td align="left"><code class="classname">std::__new_alloc</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::malloc_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/malloc_allocator.h</code></td><td align="left"><code class="classname">std::__malloc_alloc_template&lt;int&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::debug_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/debug_allocator.h</code></td><td align="left"><code class="classname">std::debug_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::__pool_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">ext/pool_allocator.h</code></td><td align="left"><code class="classname">std::__default_alloc_template&lt;bool,int&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::__mt_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">ext/mt_allocator.h</code></td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left"><code class="classname">__gnu_cxx::bitmap_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/bitmap_allocator.h</code></td><td align="left"> </td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break" /><p> Releases after gcc-3.4 have continued to add to the collection
</p><div class="table"><a id="id433329"></a><p class="title"><b>Table B.1. Extension Allocators</b></p><div class="table-contents"><table summary="Extension Allocators" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Allocator (3.4)</th><th align="left">Header (3.4)</th><th align="left">Allocator (3.[0-3])</th><th align="left">Header (3.[0-3])</th></tr></thead><tbody><tr><td align="left"><code class="classname">__gnu_cxx::new_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/new_allocator.h</code></td><td align="left"><code class="classname">std::__new_alloc</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::malloc_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/malloc_allocator.h</code></td><td align="left"><code class="classname">std::__malloc_alloc_template&lt;int&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::debug_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/debug_allocator.h</code></td><td align="left"><code class="classname">std::debug_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::__pool_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">ext/pool_allocator.h</code></td><td align="left"><code class="classname">std::__default_alloc_template&lt;bool,int&gt;</code></td><td align="left"><code class="filename">memory</code></td></tr><tr><td align="left"><code class="classname">__gnu_cxx::__mt_alloc&lt;T&gt;</code></td><td align="left"><code class="filename">ext/mt_allocator.h</code></td><td align="left"> </td><td align="left"> </td></tr><tr><td align="left"><code class="classname">__gnu_cxx::bitmap_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/bitmap_allocator.h</code></td><td align="left"> </td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break" /><p> Releases after gcc-3.4 have continued to add to the collection
of available allocators. All of these new allocators are
standard-style. The following table includes details, along with
the first released version of GCC that included the extension allocator.
</p><div class="table"><a id="id594438"></a><p class="title"><b>Table B.2. Extension Allocators Continued</b></p><div class="table-contents"><table summary="Extension Allocators Continued" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Allocator</th><th align="left">Include</th><th align="left">Version</th></tr></thead><tbody><tr><td align="left"><code class="classname">__gnu_cxx::array_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/array_allocator.h</code></td><td align="left">4.0.0</td></tr><tr><td align="left"><code class="classname">__gnu_cxx::throw_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/throw_allocator.h</code></td><td align="left">4.2.0</td></tr></tbody></table></div></div><br class="table-break" /><p>
</p><div class="table"><a id="id432659"></a><p class="title"><b>Table B.2. Extension Allocators Continued</b></p><div class="table-contents"><table summary="Extension Allocators Continued" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Allocator</th><th align="left">Include</th><th align="left">Version</th></tr></thead><tbody><tr><td align="left"><code class="classname">__gnu_cxx::array_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/array_allocator.h</code></td><td align="left">4.0.0</td></tr><tr><td align="left"><code class="classname">__gnu_cxx::throw_allocator&lt;T&gt;</code></td><td align="left"><code class="filename">ext/throw_allocator.h</code></td><td align="left">4.2.0</td></tr></tbody></table></div></div><br class="table-break" /><p>
Debug mode first appears.
</p><p>
Precompiled header support <acronym class="acronym">PCH</acronym> support.
@ -143,13 +143,13 @@ Debug mode for <code class="filename">unordered_map</code> and <code class="file
</p><p>
Parallel mode first appears.
</p><p>Variadic template implementations of items in <code class="filename">tuple</code> and
<code class="filename">functional</code>.
<code class="filename">functional</code>.
</p><p>Default <code class="code">what</code> implementations give more elaborate
exception strings for <code class="code">bad_cast</code>,
<code class="code">bad_typeid</code>, <code class="code">bad_exception</code>, and
<code class="code">bad_alloc</code>.
</p><p>
PCH binary files no longer installed. Instead, the source files are installed.
PCH binary files no longer installed. Instead, the source files are installed.
</p><p>
Namespace pb_ds moved to __gnu_pb_ds.
</p></div><div class="sect2" title="4.4"><div class="titlepage"><div><div><h3 class="title"><a id="api.rel_440"></a><code class="constant">4.4</code></h3></div></div></div><p>
@ -227,7 +227,7 @@ C++0X features.
</p></li></ul></div><p>
Profile mode first appears.
</p><p>
Support for decimal floating-point arithmetic, including <code class="classname">decimal32</code>, <code class="classname">decimal64</code>, and <code class="classname">decimal128</code>.
Support for decimal floating-point arithmetic, including <code class="classname">decimal32</code>, <code class="classname">decimal64</code>, and <code class="classname">decimal128</code>.
</p><p>
Python pretty-printers are added for use with appropriately-advanced versions of <span class="command"><strong>gdb</strong></span>.
</p><p>

54
libstdc++-v3/doc/html/manual/appendix_contributing.html
View file

@ -1,17 +1,19 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt12ch41s03.html" title="Use" /><link rel="next" href="source_organization.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. 
<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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt04.html" title="Part IV.  Appendices" /><link rel="prev" href="bk01pt04.html" title="Part IV.  Appendices" /><link rel="next" href="source_organization.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="bk01pt12ch41s03.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="source_organization.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix A.  Contributing"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.contrib"></a>Appendix A. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt04.html">Prev</a> </td><th width="60%" align="center">Part IV. 
Appendices
</th><td width="20%" align="right"> <a accesskey="n" href="source_organization.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix A.  Contributing"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.contrib"></a>Appendix A. 
Contributing
<a id="id598653" class="indexterm"></a>
</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="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="sect1"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="sect2"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="documentation_style.html">Documentation Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="documentation_style.html#doc_style.doxygen">Doxygen</a></span></dt><dt><span class="sect2"><a href="documentation_style.html#doc_style.docbook">Docbook</a></span></dt></dl></dd><dt><span class="sect1"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></div><p>
<a id="id488768" class="indexterm"></a>
</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="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="sect1"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="sect2"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="documentation_style.html">Documentation Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="documentation_style.html#doc_style.doxygen">Doxygen</a></span></dt><dt><span class="sect2"><a href="documentation_style.html#doc_style.docbook">Docbook</a></span></dt><dt><span class="sect2"><a href="documentation_style.html#doc_style.combines">Combines</a></span></dt></dl></dd><dt><span class="sect1"><a href="source_design_notes.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" title="Contributor Checklist"><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" title="Reading"><div class="titlepage"><div><div><h3 class="title"><a id="list.reading"></a>Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
</p><div class="sect1" title="Contributor Checklist"><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" title="Reading"><div class="titlepage"><div><div><h3 class="title"><a id="list.reading"></a>Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><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
@ -21,29 +23,29 @@
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://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/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003" target="_top">buy the standard on-line.)</a>
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><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 class="listitem"><p>
</p></li><li class="listitem"><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.comeaucomputing.com/csc/faq.html" target="_top">
here </a>.
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><p>
Peruse
the <a class="ulink" href="http://www.gnu.org/prep/standards" target="_top">GNU
Coding Standards</a>, and chuckle when you hit the part
about <span class="quote">“<span class="quote">Using Languages Other Than C</span>”</span>.
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><p>
Be familiar with the extensions that preceded these
general GNU rules. These style issues for libstdc++ can be
found <a class="link" href="source_code_style.html" title="Coding Style">here</a>.
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><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>.
@ -51,8 +53,8 @@
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>
to fill out appropriate disclaimer forms as well.
</p><p>
Historically, the libstdc++ assignment form added the following
question:
</p><p>
@ -64,7 +66,7 @@
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
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>
@ -81,22 +83,22 @@
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 class="itemizedlist" type="disc"><li class="listitem"><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><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 class="listitem"><p>
implementation.
</p></li><li class="listitem"><p>
A ChangeLog entry as plain text; see the various
ChangeLog files for format and content. If 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 class="listitem"><p>
functionality also exists for vi.
</p></li><li class="listitem"><p>
A testsuite submission or sample program that will
easily and simply show the existing error or test new
functionality.
</p></li><li class="listitem"><p>
functionality.
</p></li><li class="listitem"><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
@ -105,9 +107,11 @@
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 class="listitem"><p>
</p></li><li class="listitem"><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="bk01pt12ch41s03.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="source_organization.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++ 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="bk01pt04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source_organization.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part IV. 
Appendices
 </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>

12
libstdc++-v3/doc/html/manual/appendix_free.html
View file

@ -1,11 +1,13 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="appendix_gpl.html" title="Appendix D.  GNU General Public License version 3" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix C. 
<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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt04.html" title="Part IV.  Appendices" /><link rel="prev" href="backwards.html" title="Backwards Compatibility" /><link rel="next" href="appendix_gpl.html" title="Appendix D.  GNU General Public License version 3" /></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="appendix_gpl.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix C.  Free Software Needs Free Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.free"></a>Appendix C. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="backwards.html">Prev</a> </td><th width="60%" align="center">Part IV. 
Appendices
</th><td width="20%" align="right"> <a accesskey="n" href="appendix_gpl.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix C.  Free Software Needs Free Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.free"></a>Appendix C. 
Free Software Needs Free Documentation
<a id="id702684" class="indexterm"></a>
<a id="id490083" class="indexterm"></a>
</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
@ -35,7 +37,7 @@ 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>
</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.
@ -119,6 +121,6 @@ prefer copylefted manuals to non-copylefted ones.
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="appendix_gpl.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. 
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="bk01pt04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_gpl.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. 
<acronym class="acronym">GNU</acronym> General Public License version 3
</td></tr></table></div></body></html>

8
libstdc++-v3/doc/html/manual/appendix_gfdl.html
View file

@ -1,6 +1,8 @@
<?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 E. GNU Free Documentation License</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" 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_gpl.html" title="Appendix D.  GNU General Public License version 3" /><link rel="next" href="bk01ix01.html" title="Index" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. GNU Free Documentation License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_gpl.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01ix01.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix E. GNU Free Documentation License"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gfdl-1.2"></a>Appendix E. GNU Free Documentation License</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. GNU Free Documentation License</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt04.html" title="Part IV.  Appendices" /><link rel="prev" href="appendix_gpl.html" title="Appendix D.  GNU General Public License version 3" /><link rel="next" href="../bk02.html" title="" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. GNU Free Documentation License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_gpl.html">Prev</a> </td><th width="60%" align="center">Part IV. 
Appendices
</th><td width="20%" align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix E. GNU Free Documentation License"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gfdl-1.2"></a>Appendix E. GNU Free Documentation License</h2></div></div></div><p>
Copyright (C) 2000, 2001, 2002 Free Software Foundation,
<abbr class="abbrev">Inc.</abbr> 51 Franklin <abbr class="abbrev">St</abbr>, Fifth Floor,
Boston, <abbr class="abbrev">MA</abbr> 02110-1301 <abbr class="abbrev">USA</abbr>. Everyone is permitted to copy and
@ -390,6 +392,6 @@
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit their
use in free software.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_gpl.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="bk01ix01.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix D. 
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_gpl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix D. 
<acronym class="acronym">GNU</acronym> General Public License version 3
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Index</td></tr></table></div></body></html>
 </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>

12
libstdc++-v3/doc/html/manual/appendix_gpl.html
View file

@ -1,8 +1,10 @@
<?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 version 3</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" 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="appendix_gfdl.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">Appendix D. 
<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 version 3</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt04.html" title="Part IV.  Appendices" /><link rel="prev" href="appendix_free.html" title="Appendix C.  Free Software Needs Free Documentation" /><link rel="next" href="appendix_gfdl.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">Appendix D. 
<acronym class="acronym">GNU</acronym> General Public License version 3
</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="appendix_gfdl.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix D.  GNU General Public License version 3"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gpl-3.0"></a>Appendix D. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><th width="60%" align="center">Part IV. 
Appendices
</th><td width="20%" align="right"> <a accesskey="n" href="appendix_gfdl.html">Next</a></td></tr></table><hr /></div><div class="appendix" title="Appendix D.  GNU General Public License version 3"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gpl-3.0"></a>Appendix D. 
<acronym class="acronym">GNU</acronym> General Public License version 3
</h2></div></div></div><p>
Version 3, 29 June 2007
@ -76,7 +78,7 @@
</p><p>
The precise terms and conditions for copying, distribution and modification
follow.
</p><h2><a id="id703002"></a>
</p><h2><a id="id382653"></a>
TERMS AND CONDITIONS
</h2><h2><a id="gpl-3-definitions"></a>
0. Definitions.
@ -617,7 +619,7 @@
waiver of all civil liability in connection with the Program, unless a
warranty or assumption of liability accompanies a copy of the Program in
return for a fee.
</p><h2><a id="id635999"></a>
</p><h2><a id="id421222"></a>
END OF TERMS AND CONDITIONS
</h2><h2><a id="HowToApply"></a>
How to Apply These Terms to Your New Programs
@ -675,7 +677,7 @@ under certain conditions; type ‘<code class="literal">show c</code>’ for det
proprietary applications with the library. If this is what you want to do,
use the <acronym class="acronym">GNU</acronym> Lesser General Public License instead of this
License. But first, please read <a class="ulink" href="http://www.gnu.org/philosophy/why-not-lgpl.html" target="_top">http://www.gnu.org/philosophy/why-not-lgpl.html</a>.
</p></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="appendix_gfdl.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix C. 
</p></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="bk01pt04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_gfdl.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"> Appendix E. GNU Free Documentation License</td></tr></table></div></body></html>

12
libstdc++-v3/doc/html/manual/appendix_porting.html
View file

File diff suppressed because one or more lines are too long

113
libstdc++-v3/doc/html/manual/associative.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII.  Containers" /><link rel="prev" href="vector.html" title="vector" /><link rel="next" href="bitset.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="vector.html">Prev</a> </td><th width="60%" align="center">Part VII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Associative</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Chapter 9.  Containers" /><link rel="prev" href="containers.html" title="Chapter 9.  Containers" /><link rel="next" href="containers_and_c.html" title="Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Associative</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="containers.html">Prev</a> </td><th width="60%" align="center">Chapter 9. 
Containers
</th><td width="20%" align="right"> <a accesskey="n" href="bitset.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 17. Associative"><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="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect1"><a href="bitset.html">bitset</a></span></dt><dd><dl><dt><span class="sect2"><a href="bitset.html#associative.bitset.size_variable">Size Variable</a></span></dt><dt><span class="sect2"><a href="bitset.html#associative.bitset.type_string">Type String</a></span></dt></dl></dd></dl></div><div class="sect1" title="Insertion Hints"><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>
</th><td width="20%" align="right"> <a accesskey="n" href="containers_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Associative"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.containers.associative"></a>Associative</h2></div></div></div><div class="sect2" title="Insertion Hints"><div class="titlepage"><div><div><h3 class="title"><a id="containers.associative.insert_hints"></a>Insertion Hints</h3></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">
@ -48,7 +48,7 @@
<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 before <code class="code">end()</code>.
the new entry before <code class="code">end()</code>.
</p></li><li class="listitem"><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
@ -84,4 +84,109 @@
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="vector.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="bitset.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>
</p></div><div class="sect2" title="bitset"><div class="titlepage"><div><div><h3 class="title"><a id="containers.associative.bitset"></a>bitset</h3></div></div></div><div class="sect3" title="Size Variable"><div class="titlepage"><div><div><h4 class="title"><a id="associative.bitset.size_variable"></a>Size Variable</h4></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 chaptericular order:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A very large N in <code class="code">bitset&lt;N&gt;</code>.</p></li><li class="listitem"><p>A container&lt;bool&gt;.</p></li><li class="listitem"><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">“<span class="quote">changed</span>”</span>/<span class="quote">“<span class="quote">unchanged</span>”</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">“<span class="quote">maximum bit used</span>”</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
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="link" href="bk01pt03ch21s02.html" title="HP/SGI">some extensions</a>.
</p></div><div class="sect3" title="Type String"><div class="titlepage"><div><div><h4 class="title"><a id="associative.bitset.type_string"></a>Type String</h4></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">“<span class="quote">Links</span>”</span> from
the homepage, and from the C++ information <span class="quote">“<span class="quote">defect
reflector</span>”</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">“<span class="quote">10110</span>”</span>) );
</pre><p>
instead of
</p><pre class="programlisting">
std::bitset&lt;5&gt; b ( <span class="quote">“<span class="quote">10110</span>”</span> ); // invalid
</pre></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="containers_and_c.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. 
Containers
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Interacting with C</td></tr></table></div></body></html>

31
libstdc++-v3/doc/html/manual/atomics.html Normal file
View file

@ -0,0 +1,31 @@
<?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 14.  Atomics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; atomic&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="io_and_c.html" title="Interacting with C" /><link rel="next" href="concurrency.html" title="Chapter 15.  Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. 
Atomics
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 14.  Atomics"><div class="titlepage"><div><div><h2 class="title"><a id="std.atomics"></a>Chapter 14. 
Atomics
<a id="id510195" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="atomics.html#std.atomics.api">API Reference</a></span></dt></dl></div><p>
Facilities for atomic operations.
</p><div class="sect1" title="API Reference"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.atomics.api"></a>API Reference</h2></div></div></div><p>
All items are declared in the standard header
file <code class="filename">atomic</code>.
</p><p>
Set of typedefs that map <span class="type">int</span> to
<code class="classname">atomic_int</code>, and so on for all builtin
integral types. Global enumeration <span class="type">memory_order</span> to
control memory ordering. Also includes
<code class="classname">atomic</code>, a class template with member
functions such as <code class="function">load</code> and
<code class="function">store</code> that is instantiable such that
<code class="classname">atomic_int</code> is the base class of
<code class="classname">atomic&lt;int&gt;</code>.
</p><p>
Full API details.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="io_and_c.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Interacting with C </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. 
Concurrency
</td></tr></table></div></body></html>

90
libstdc++-v3/doc/html/manual/auto_ptr.html
View file

@ -1,90 +0,0 @@
<?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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="memory.html" title="Chapter 11. Memory" /><link rel="prev" href="memory.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="memory.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" title="auto_ptr"><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" title="Limitations"><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" title="Use in Containers"><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="link" href="containers.html" title="Part VII.  Containers">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">“<span class="quote">undefined</span>”</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="link" href="ext_compile_checks.html" title="Chapter 29. Compile Time Checks">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="memory.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="memory.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>

211
libstdc++-v3/doc/html/manual/backwards.html
View file

@ -17,8 +17,8 @@ ISO Standard (e.g., statistical analysis). While there are a lot of
really useful things that are used by a lot of people, the Standards
Committee couldn't include everything, and so a lot of those
<span class="quote">“<span class="quote">obvious</span>”</span> classes didn't get included.
</p><p>Known Issues include many of the limitations of its immediate ancestor.</p><p>Portability notes and known implementation limitations are as follows.</p><div class="sect3" title="No ios_base"><div class="titlepage"><div><div><h4 class="title"><a id="id646429"></a>No <code class="code">ios_base</code></h4></div></div></div><p> At least some older implementations don't have <code class="code">std::ios_base</code>, so you should use <code class="code">std::ios::badbit</code>, <code class="code">std::ios::failbit</code> and <code class="code">std::ios::eofbit</code> and <code class="code">std::ios::goodbit</code>.
</p></div><div class="sect3" title="No cout in ostream.h, no cin in istream.h"><div class="titlepage"><div><div><h4 class="title"><a id="id646461"></a>No <code class="code">cout</code> in <code class="code">ostream.h</code>, no <code class="code">cin</code> in <code class="code">istream.h</code></h4></div></div></div><p>
</p><p>Known Issues include many of the limitations of its immediate ancestor.</p><p>Portability notes and known implementation limitations are as follows.</p><div class="sect3" title="No ios_base"><div class="titlepage"><div><div><h4 class="title"><a id="id508624"></a>No <code class="code">ios_base</code></h4></div></div></div><p> At least some older implementations don't have <code class="code">std::ios_base</code>, so you should use <code class="code">std::ios::badbit</code>, <code class="code">std::ios::failbit</code> and <code class="code">std::ios::eofbit</code> and <code class="code">std::ios::goodbit</code>.
</p></div><div class="sect3" title="No cout in ostream.h, no cin in istream.h"><div class="titlepage"><div><div><h4 class="title"><a id="id508656"></a>No <code class="code">cout</code> in <code class="code">ostream.h</code>, no <code class="code">cin</code> in <code class="code">istream.h</code></h4></div></div></div><p>
In earlier versions of the standard,
<code class="filename">fstream.h</code>,
<code class="filename">ostream.h</code>
@ -32,26 +32,26 @@ archived. For the desperate,
the <a class="ulink" href="http://gcc.gnu.org/extensions.html" target="_top">GCC extensions
page</a> describes where to find the last libg++ source. The code is
considered replaced and rewritten.
</p></div></div><div class="sect2" title="Second"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.second"></a>Second</h3></div></div></div><p>
</p></div></div><div class="sect2" title="Second"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.second"></a>Second</h3></div></div></div><p>
The second generation GNU C++ library was called libstdc++, or
libstdc++-v2. It spans the time between libg++ and pre-ISO C++
standardization and is usually associated with the following GCC
releases: egcs 1.x, gcc 2.95, and gcc 2.96.
</p><p>
</p><p>
The STL portions of this library are based on SGI/HP STL release 3.11.
</p><p>
This project is no longer maintained or supported, and the sources
archived. The code is considered replaced and rewritten.
</p><p>
Portability notes and known implementation limitations are as follows.
</p><div class="sect3" title="Namespace std:: not supported"><div class="titlepage"><div><div><h4 class="title"><a id="id646559"></a>Namespace <code class="code">std::</code> not supported</h4></div></div></div><p>
</p><div class="sect3" title="Namespace std:: not supported"><div class="titlepage"><div><div><h4 class="title"><a id="id508754"></a>Namespace <code class="code">std::</code> not supported</h4></div></div></div><p>
Some care is required to support C++ compiler and or library
implementation that do not have the standard library in
<code class="code">namespace std</code>.
</p><p>
The following sections list some possible solutions to support compilers
that cannot ignore <code class="code">std::</code>-qualified names.
</p><p>
</p><p>
First, see if the compiler has a flag for this. Namespace
back-portability-issues are generally not a problem for g++
compilers that do not have libstdc++ in <code class="code">std::</code>, as the
@ -62,7 +62,7 @@ considered replaced and rewritten.
probably applies to some other compilers as well.
</p><p>
Second, experiment with a variety of pre-processor tricks.
</p><p>
</p><p>
By defining <code class="code">std</code> as a macro, fully-qualified namespace
calls become global. Volia.
</p><pre class="programlisting">
@ -99,8 +99,8 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [
ac_cv_cxx_have_std_namespace,
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
AC_TRY_COMPILE([#include &lt;iostream&gt;
std::istream&amp; is = std::cin;],,
AC_TRY_COMPILE([#include &lt;iostream&gt;
std::istream&amp; is = std::cin;],,
ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
AC_LANG_RESTORE
])
@ -108,7 +108,7 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [
AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
fi
])
</pre></div><div class="sect3" title="Illegal iterator usage"><div class="titlepage"><div><div><h4 class="title"><a id="id699742"></a>Illegal iterator usage</h4></div></div></div><p>
</pre></div><div class="sect3" title="Illegal iterator usage"><div class="titlepage"><div><div><h4 class="title"><a id="id508877"></a>Illegal iterator usage</h4></div></div></div><p>
The following illustrate implementation-allowed illegal iterator
use, and then correct use.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
@ -120,28 +120,28 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [
0</code>) =&gt; use <code class="code">iterator = iterator_type();</code>
</p></li><li class="listitem"><p>
<code class="code">if (iterator)</code> won't work any more =&gt; use
<code class="code">if (iterator != iterator_type())</code>
</p></li></ul></div></div><div class="sect3" title="isspace from cctype is a macro"><div class="titlepage"><div><div><h4 class="title"><a id="id699804"></a><code class="code">isspace</code> from <code class="filename">cctype</code> is a macro
</h4></div></div></div><p>
<code class="code">if (iterator != iterator_type())</code>
</p></li></ul></div></div><div class="sect3" title="isspace from cctype is a macro"><div class="titlepage"><div><div><h4 class="title"><a id="id508938"></a><code class="code">isspace</code> from <code class="filename">cctype</code> is a macro
</h4></div></div></div><p>
Glibc 2.0.x and 2.1.x define <code class="filename">ctype.h</code> functionality as macros
(isspace, isalpha etc.).
</p><p>
This implementations of libstdc++, however, keep these functions
as macros, and so it is not back-portable to use fully qualified
names. For example:
</p><pre class="programlisting">
#include &lt;cctype&gt;
int main() { std::isspace('X'); }
</p><pre class="programlisting">
#include &lt;cctype&gt;
int main() { std::isspace('X'); }
</pre><p>
Results in something like this:
</p><pre class="programlisting">
std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
</pre><p>
</p><pre class="programlisting">
std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
</pre><p>
A solution is to modify a header-file so that the compiler tells
<code class="filename">ctype.h</code> to define functions
instead of macros:
</p><pre class="programlisting">
// This keeps isalnum, et al from being propagated as macros.
// This keeps isalnum, et al from being propagated as macros.
#if __linux__
# define __NO_CTYPE 1
#endif
@ -154,7 +154,7 @@ std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
(<code class="filename">ctype.h</code>) and the
definitions in namespace <code class="code">std::</code>
(<code class="code">&lt;cctype&gt;</code>).
</p></div><div class="sect3" title="No vector::at, deque::at, string::at"><div class="titlepage"><div><div><h4 class="title"><a id="id699897"></a>No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></h4></div></div></div><p>
</p></div><div class="sect3" title="No vector::at, deque::at, string::at"><div class="titlepage"><div><div><h4 class="title"><a id="id502656"></a>No <code class="code">vector::at</code>, <code class="code">deque::at</code>, <code class="code">string::at</code></h4></div></div></div><p>
One solution is to add an autoconf-test for this:
</p><pre class="programlisting">
AC_MSG_CHECKING(for container::at)
@ -163,7 +163,7 @@ AC_TRY_COMPILE(
#include &lt;vector&gt;
#include &lt;deque&gt;
#include &lt;string&gt;
using namespace std;
],
[
@ -180,7 +180,7 @@ AC_DEFINE(HAVE_CONTAINER_AT)],
</pre><p>
If you are using other (non-GNU) compilers it might be a good idea
to check for <code class="code">string::at</code> separately.
</p></div><div class="sect3" title="No std::char_traits&lt;char&gt;::eof"><div class="titlepage"><div><div><h4 class="title"><a id="id716937"></a>No <code class="code">std::char_traits&lt;char&gt;::eof</code></h4></div></div></div><p>
</p></div><div class="sect3" title="No std::char_traits&lt;char&gt;::eof"><div class="titlepage"><div><div><h4 class="title"><a id="id502694"></a>No <code class="code">std::char_traits&lt;char&gt;::eof</code></h4></div></div></div><p>
Use some kind of autoconf test, plus this:
</p><pre class="programlisting">
#ifdef HAVE_CHAR_TRAITS
@ -188,45 +188,45 @@ AC_DEFINE(HAVE_CONTAINER_AT)],
#else
#define CPP_EOF EOF
#endif
</pre></div><div class="sect3" title="No string::clear"><div class="titlepage"><div><div><h4 class="title"><a id="id716955"></a>No <code class="code">string::clear</code></h4></div></div></div><p>
</pre></div><div class="sect3" title="No string::clear"><div class="titlepage"><div><div><h4 class="title"><a id="id502712"></a>No <code class="code">string::clear</code></h4></div></div></div><p>
There are two functions for deleting the contents of a string:
<code class="code">clear</code> and <code class="code">erase</code> (the latter returns the
string).
</p><pre class="programlisting">
void
void
clear() { _M_mutate(0, this-&gt;size(), 0); }
</pre><pre class="programlisting">
basic_string&amp;
basic_string&amp;
erase(size_type __pos = 0, size_type __n = npos)
{
{
return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
_M_data(), _M_data());
_M_data(), _M_data());
}
</pre><p>
Unfortunately, <code class="code">clear</code> is not implemented in this
version, so you should use <code class="code">erase</code> (which is probably
faster than <code class="code">operator=(charT*)</code>).
</p></div><div class="sect3" title="Removal of ostream::form and istream::scan extensions"><div class="titlepage"><div><div><h4 class="title"><a id="id717001"></a>
</p></div><div class="sect3" title="Removal of ostream::form and istream::scan extensions"><div class="titlepage"><div><div><h4 class="title"><a id="id502758"></a>
Removal of <code class="code">ostream::form</code> and <code class="code">istream::scan</code>
extensions
</h4></div></div></div><p>
</h4></div></div></div><p>
These are no longer supported. Please use stringstreams instead.
</p></div><div class="sect3" title="No basic_stringbuf, basic_stringstream"><div class="titlepage"><div><div><h4 class="title"><a id="id717020"></a>No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></h4></div></div></div><p>
</p></div><div class="sect3" title="No basic_stringbuf, basic_stringstream"><div class="titlepage"><div><div><h4 class="title"><a id="id502777"></a>No <code class="code">basic_stringbuf</code>, <code class="code">basic_stringstream</code></h4></div></div></div><p>
Although the ISO standard <code class="code">i/ostringstream</code>-classes are
provided, (<code class="filename">sstream</code>), for
compatibility with older implementations the pre-ISO
<code class="code">i/ostrstream</code> (<code class="filename">strstream</code>) interface is also provided,
with these caveats:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<code class="code">strstream</code> is considered to be deprecated
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><p>
<code class="code">strstream</code> is limited to <code class="code">char</code>
</p></li><li class="listitem"><p>
</p></li><li class="listitem"><p>
with <code class="code">ostringstream</code> you don't have to take care of
terminating the string or freeing its memory
</p></li><li class="listitem"><p>
terminating the string or freeing its memory
</p></li><li class="listitem"><p>
<code class="code">istringstream</code> can be re-filled (clear();
str(input);)
str(input);)
</p></li></ul></div><p>
You can then use output-stringstreams like this:
</p><pre class="programlisting">
@ -268,7 +268,7 @@ std::istrstream iss(input.c_str());
#endif
int i;
iss &gt;&gt; i;
iss &gt;&gt; i;
</pre><p> One (the only?) restriction is that an istrstream cannot be re-filled:
</p><pre class="programlisting">
std::istringstream iss(numerator);
@ -295,18 +295,18 @@ if (iss.fail())
throw runtime_error(..)
any = temp;
}
</pre><p>
Another example of using stringstreams is in <a class="link" href="bk01pt05ch13s05.html" title="Shrink to Fit">this howto</a>.
</pre><p>
Another example of using stringstreams is in <a class="link" href="strings.html#strings.string.shrink" title="Shrink to Fit">this howto</a>.
</p><p> There is additional information in the libstdc++-v2 info files, in
particular <span class="quote">“<span class="quote">info iostream</span>”</span>.
</p></div><div class="sect3" title="Little or no wide character support"><div class="titlepage"><div><div><h4 class="title"><a id="id717171"></a>Little or no wide character support</h4></div></div></div><p>
</p></div><div class="sect3" title="Little or no wide character support"><div class="titlepage"><div><div><h4 class="title"><a id="id502928"></a>Little or no wide character support</h4></div></div></div><p>
Classes <code class="classname">wstring</code> and
<code class="classname">char_traits&lt;wchar_t&gt;</code> are
not supported.
</p></div><div class="sect3" title="No templatized iostreams"><div class="titlepage"><div><div><h4 class="title"><a id="id717190"></a>No templatized iostreams</h4></div></div></div><p>
</p></div><div class="sect3" title="No templatized iostreams"><div class="titlepage"><div><div><h4 class="title"><a id="id502947"></a>No templatized iostreams</h4></div></div></div><p>
Classes <code class="classname">wfilebuf</code> and
<code class="classname">wstringstream</code> are not supported.
</p></div><div class="sect3" title="Thread safety issues"><div class="titlepage"><div><div><h4 class="title"><a id="id717209"></a>Thread safety issues</h4></div></div></div><p>
</p></div><div class="sect3" title="Thread safety issues"><div class="titlepage"><div><div><h4 class="title"><a id="id502966"></a>Thread safety issues</h4></div></div></div><p>
Earlier GCC releases had a somewhat different approach to
threading configuration and proper compilation. Before GCC 3.0,
configuration of the threading model was dictated by compiler
@ -348,10 +348,10 @@ particular <span class="quote">“<span class="quote">info iostream</span>”</s
release series.
</p></li><li class="listitem"><p>
<a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html" target="_top">
This message</a> inspired a recent updating of issues with
threading and the SGI STL library. It also contains some
example POSIX-multithreaded STL code.
</p></li></ul></div><p>
This message</a> inspired a recent updating of issues with
threading and the SGI STL library. It also contains some
example POSIX-multithreaded STL code.
</p></li></ul></div><p>
(A large selection of links to older messages has been removed;
many of the messages from 1999 were lost in a disk crash, and the
few people with access to the backup tapes have been too swamped
@ -360,11 +360,11 @@ particular <span class="quote">“<span class="quote">info iostream</span>”</s
</p></div></div><div class="sect2" title="Third"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.third"></a>Third</h3></div></div></div><p> The third generation GNU C++ library is called libstdc++, or
libstdc++-v3.
</p><p>The subset commonly known as the Standard Template Library
(chapters 23 through 25, mostly) is adapted from the final release
of the SGI STL (version 3.3), with extensive changes.
(chapters 23 through 25, mostly) is adapted from the final release
of the SGI STL (version 3.3), with extensive changes.
</p><p>A more formal description of the V3 goals can be found in the
official <a class="link" href="source_design_notes.html" title="Design Notes">design document</a>.
</p><p>Portability notes and known implementation limitations are as follows.</p><div class="sect3" title="Pre-ISO headers moved to backwards or removed"><div class="titlepage"><div><div><h4 class="title"><a id="id706015"></a>Pre-ISO headers moved to backwards or removed</h4></div></div></div><p> The pre-ISO C++ headers
official <a class="link" href="source_design_notes.html" title="Design Notes">design document</a>.
</p><p>Portability notes and known implementation limitations are as follows.</p><div class="sect3" title="Pre-ISO headers moved to backwards or removed"><div class="titlepage"><div><div><h4 class="title"><a id="id426691"></a>Pre-ISO headers moved to backwards or removed</h4></div></div></div><p> The pre-ISO C++ headers
(<code class="code">iostream.h</code>, <code class="code">defalloc.h</code> etc.) are
available, unlike previous libstdc++ versions, but inclusion
generates a warning that you are using deprecated headers.
@ -385,7 +385,7 @@ AC_DEFUN([AC_HEADER_PRE_STDCXX], [
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -Wno-deprecated"
CXXFLAGS="$CXXFLAGS -Wno-deprecated"
# Omit defalloc.h, as compilation with newer compilers is problematic.
AC_TRY_COMPILE([
@ -436,11 +436,11 @@ like <code class="filename">vector.h</code> can be replaced with <code class="fi
directive <code class="code">using namespace std;</code> can be put at the global
scope. This should be enough to get this code compiling, assuming the
other usage is correct.
</p></div><div class="sect3" title="Extension headers hash_map, hash_set moved to ext or backwards"><div class="titlepage"><div><div><h4 class="title"><a id="id706097"></a>Extension headers hash_map, hash_set moved to ext or backwards</h4></div></div></div><p>At this time most of the features of the SGI STL extension have been
replaced by standardized libraries.
In particular, the unordered_map and unordered_set containers of TR1
are suitable replacement for the non-standard hash_map and hash_set
containers in the SGI STL.
</p></div><div class="sect3" title="Extension headers hash_map, hash_set moved to ext or backwards"><div class="titlepage"><div><div><h4 class="title"><a id="id426772"></a>Extension headers hash_map, hash_set moved to ext or backwards</h4></div></div></div><p>At this time most of the features of the SGI STL extension have been
replaced by standardized libraries.
In particular, the unordered_map and unordered_set containers of TR1
are suitable replacement for the non-standard hash_map and hash_set
containers in the SGI STL.
</p><p> Header files <code class="filename">hash_map</code> and <code class="filename">hash_set</code> moved
to <code class="filename">ext/hash_map</code> and <code class="filename">ext/hash_set</code>,
respectively. At the same time, all types in these files are enclosed
@ -448,29 +448,29 @@ in <code class="code">namespace __gnu_cxx</code>. Later versions move deprecate
these files, and suggest using TR1's <code class="filename">unordered_map</code>
and <code class="filename">unordered_set</code> instead.
</p><p>The extensions are no longer in the global or <code class="code">std</code>
namespaces, instead they are declared in the <code class="code">__gnu_cxx</code>
namespace. For maximum portability, consider defining a namespace
alias to use to talk about extensions, e.g.:
namespaces, instead they are declared in the <code class="code">__gnu_cxx</code>
namespace. For maximum portability, consider defining a namespace
alias to use to talk about extensions, e.g.:
</p><pre class="programlisting">
#ifdef __GNUC__
#if __GNUC__ &lt; 3
#include &lt;hash_map.h&gt;
namespace extension { using ::hash_map; }; // inherit globals
#include &lt;hash_map.h&gt;
namespace extension { using ::hash_map; }; // inherit globals
#else
#include &lt;backward/hash_map&gt;
#if __GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ == 0
namespace extension = std; // GCC 3.0
#else
namespace extension = ::__gnu_cxx; // GCC 3.1 and later
#endif
#include &lt;backward/hash_map&gt;
#if __GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ == 0
namespace extension = std; // GCC 3.0
#else
namespace extension = ::__gnu_cxx; // GCC 3.1 and later
#endif
#endif
#else // ... there are other compilers, right?
namespace extension = std;
namespace extension = std;
#endif
extension::hash_map&lt;int,int&gt; my_map;
extension::hash_map&lt;int,int&gt; my_map;
</pre><p>This is a bit cleaner than defining typedefs for all the
instantiations you might need.
instantiations you might need.
</p><p>The following autoconf tests check for working HP/SGI hash containers.
</p><pre class="programlisting">
# AC_HEADER_EXT_HASH_MAP
@ -480,7 +480,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -Werror"
CXXFLAGS="$CXXFLAGS -Werror"
AC_TRY_COMPILE([#include &lt;ext/hash_map&gt;], [using __gnu_cxx::hash_map;],
ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no)
CXXFLAGS="$ac_save_CXXFLAGS"
@ -498,7 +498,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -Werror"
CXXFLAGS="$CXXFLAGS -Werror"
AC_TRY_COMPILE([#include &lt;ext/hash_set&gt;], [using __gnu_cxx::hash_set;],
ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no)
CXXFLAGS="$ac_save_CXXFLAGS"
@ -508,7 +508,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ])
fi
])
</pre></div><div class="sect3" title="No ios::nocreate/ios::noreplace."><div class="titlepage"><div><div><h4 class="title"><a id="id706200"></a>No <code class="code">ios::nocreate/ios::noreplace</code>.
</pre></div><div class="sect3" title="No ios::nocreate/ios::noreplace."><div class="titlepage"><div><div><h4 class="title"><a id="id426874"></a>No <code class="code">ios::nocreate/ios::noreplace</code>.
</h4></div></div></div><p> The existence of <code class="code">ios::nocreate</code> being used for
input-streams has been confirmed, most probably because the author
thought it would be more correct to specify nocreate explicitly. So
@ -519,7 +519,7 @@ open the file for reading, check if it has been opened, and then
decide whether you want to create/replace or not. To my knowledge,
even older implementations support <code class="code">app</code>, <code class="code">ate</code>
and <code class="code">trunc</code> (except for <code class="code">app</code> ?).
</p></div><div class="sect3" title="No stream::attach(int fd)"><div class="titlepage"><div><div><h4 class="title"><a id="id703184"></a>
</p></div><div class="sect3" title="No stream::attach(int fd)"><div class="titlepage"><div><div><h4 class="title"><a id="id426921"></a>
No <code class="code">stream::attach(int fd)</code>
</h4></div></div></div><p>
Phil Edwards writes: It was considered and rejected for the ISO
@ -531,7 +531,7 @@ No <code class="code">stream::attach(int fd)</code>
<code class="code">std::streambuf</code> (or
<code class="code">std::basic_streambuf&lt;..&gt;</code>) which opens a file
given a descriptor, and then pass an instance of this to the
stream-constructor.
stream-constructor.
</p><p>
An extension is available that implements this.
<code class="filename">ext/stdio_filebuf.h</code> contains a derived class called
@ -540,9 +540,9 @@ No <code class="code">stream::attach(int fd)</code>
descriptor, and provides the <code class="code">fd()</code> function.
</p><p>
For another example of this, refer to
<a class="ulink" href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a>
<a class="ulink" href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a>
by Nicolai Josuttis.
</p></div><div class="sect3" title="Support for C++98 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id703247"></a>
</p></div><div class="sect3" title="Support for C++98 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id426985"></a>
Support for C++98 dialect.
</h4></div></div></div><p>Check for complete library coverage of the C++1998/2003 standard.
</p><pre class="programlisting">
@ -610,7 +610,7 @@ AC_DEFUN([AC_HEADER_STDCXX_98], [
AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
fi
])
</pre></div><div class="sect3" title="Support for C++TR1 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id703275"></a>
</pre></div><div class="sect3" title="Support for C++TR1 dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id489807"></a>
Support for C++TR1 dialect.
</h4></div></div></div><p>Check for library coverage of the TR1 standard.
</p><pre class="programlisting">
@ -687,7 +687,7 @@ AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
fi
])
</pre></div><div class="sect3" title="Support for C++0x dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id703319"></a>
</pre></div><div class="sect3" title="Support for C++0x dialect."><div class="titlepage"><div><div><h4 class="title"><a id="id489851"></a>
Support for C++0x dialect.
</h4></div></div></div><p>Check for baseline language coverage in the compiler for the C++0xstandard.
</p><pre class="programlisting">
@ -699,7 +699,7 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
AC_LANG_CPLUSPLUS
AC_TRY_COMPILE([
template &lt;typename T&gt;
struct check
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
@ -721,10 +721,10 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -std=c++0x"
CXXFLAGS="$CXXFLAGS -std=c++0x"
AC_TRY_COMPILE([
template &lt;typename T&gt;
struct check
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
@ -747,10 +747,10 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
[AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
AC_TRY_COMPILE([
template &lt;typename T&gt;
struct check
struct check
{
static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
};
@ -768,8 +768,8 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
AC_LANG_RESTORE
])
if test "$ac_cv_cxx_compile_cxx0x_native" = yes ||
test "$ac_cv_cxx_compile_cxx0x_cxx" = yes ||
if test "$ac_cv_cxx_compile_cxx0x_native" = yes ||
test "$ac_cv_cxx_compile_cxx0x_cxx" = yes ||
test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then
AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ])
fi
@ -784,7 +784,7 @@ AC_DEFUN([AC_HEADER_STDCXX_0X], [
AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
AC_TRY_COMPILE([
#include &lt;cassert&gt;
@ -870,7 +870,7 @@ AC_DEFUN([AC_HEADER_UNORDERED_MAP], [
AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
AC_TRY_COMPILE([#include &lt;unordered_map&gt;], [using std::unordered_map;],
ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no)
CXXFLAGS="$ac_save_CXXFLAGS"
@ -889,7 +889,7 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
AC_LANG_SAVE
AC_LANG_CPLUSPLUS
ac_save_CXXFLAGS="$CXXFLAGS"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
CXXFLAGS="$CXXFLAGS -std=gnu++0x"
AC_TRY_COMPILE([#include &lt;unordered_set&gt;], [using std::unordered_set;],
ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no)
CXXFLAGS="$ac_save_CXXFLAGS"
@ -899,32 +899,29 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
fi
])
</pre></div><div class="sect3" title="Container::iterator_type is not necessarily Container::value_type*"><div class="titlepage"><div><div><h4 class="title"><a id="id703396"></a>
</pre></div><div class="sect3" title="Container::iterator_type is not necessarily Container::value_type*"><div class="titlepage"><div><div><h4 class="title"><a id="id489928"></a>
Container::iterator_type is not necessarily Container::value_type*
</h4></div></div></div><p>
This is a change in behavior from the previous version. Now, most
<span class="type">iterator_type</span> typedefs in container classes are POD
objects, not <span class="type">value_type</span> pointers.
</p></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="Migrating to GCC 4.1"><a id="id703425"></a><p>[<abbr class="abbrev">
kegel41
</abbr>] <span class="title"><i>
Migrating to GCC 4.1
</i>. </span><span class="author"><span class="firstname">Dan</span> <span class="surname">Kegel</span>. </span><span class="biblioid">
</p></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="backwards.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id489958"></a><p><span class="biblioid">
<a class="ulink" href="http://www.kegel.com/gcc/gcc4.html" target="_top">
</a>
. </span></p></div><div class="biblioentry" title="Building the Whole Debian Archive with GCC 4.1: A Summary"><a id="id703458"></a><p>[<abbr class="abbrev">
kegel41
</abbr>] <span class="title"><i>
Building the Whole Debian Archive with GCC 4.1: A Summary
</i>. </span><span class="author"><span class="firstname">Martin</span> <span class="surname">Michlmayr</span>. </span><span class="biblioid">
<em class="citetitle">
Migrating to GCC 4.1
</em>
</a>
. </span><span class="author"><span class="firstname">Dan</span> <span class="surname">Kegel</span>. </span></p></div><div class="biblioentry"><a id="id489988"></a><p><span class="biblioid">
<a class="ulink" href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html" target="_top">
<em class="citetitle">
Building the Whole Debian Archive with GCC 4.1: A Summary
</em>
</a>
. </span></p></div><div class="biblioentry" title="Migration guide for GCC-3.2"><a id="id703491"></a><p>[<abbr class="abbrev">
lbl32
</abbr>] <span class="title"><i>
Migration guide for GCC-3.2
</i>. </span><span class="biblioid">
. </span><span class="author"><span class="firstname">Martin</span> <span class="surname">Michlmayr</span>. </span></p></div><div class="biblioentry"><a id="id490020"></a><p><span class="biblioid">
<a class="ulink" href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html" target="_top">
<em class="citetitle">
Migration guide for GCC-3.2
</em>
</a>
. </span></p></div></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"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_free.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">API Evolution and Deprecation History </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix C. 
Free Software Needs Free Documentation

14
libstdc++-v3/doc/html/manual/bitmap_allocator.html
View file

@ -1,6 +1,6 @@
<?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>bitmap_allocator</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; allocator&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_allocators.html" title="Chapter 33. Allocators" /><link rel="prev" href="ext_allocators.html" title="Chapter 33. Allocators" /><link rel="next" href="ext_containers.html" title="Chapter 34. Containers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bitmap_allocator</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><th width="60%" align="center">Chapter 33. Allocators</th><td width="20%" align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="bitmap_allocator"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.allocator.bitmap"></a>bitmap_allocator</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>bitmap_allocator</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; allocator&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_allocators.html" title="Chapter 20. Allocators" /><link rel="prev" href="ext_allocators.html" title="Chapter 20. Allocators" /><link rel="next" href="ext_containers.html" title="Chapter 21. Containers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bitmap_allocator</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><th width="60%" align="center">Chapter 20. Allocators</th><td width="20%" align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="bitmap_allocator"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.allocator.bitmap"></a>bitmap_allocator</h2></div></div></div><p>
</p><div class="sect2" title="Design"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.bitmap.design"></a>Design</h3></div></div></div><p>
As this name suggests, this allocator uses a bit-map to keep track
of the used and unused memory locations for it's book-keeping
@ -103,7 +103,7 @@ else return false.</p></li></ol></div><p>
</p><p>
Consider a block of size 64 ints. In memory, it would look like this:
(assume a 32-bit system where, size_t is a 32-bit entity).
</p><div class="table"><a id="id620814"></a><p class="title"><b>Table 33.1. Bitmap Allocator Memory Map</b></p><div class="table-contents"><table summary="Bitmap Allocator Memory Map" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left">268</td><td align="left">0</td><td align="left">4294967295</td><td align="left">4294967295</td><td align="left">Data -&gt; Space for 64 ints</td></tr></tbody></table></div></div><br class="table-break" /><p>
</p><div class="table"><a id="id379923"></a><p class="title"><b>Table 20.1. Bitmap Allocator Memory Map</b></p><div class="table-contents"><table summary="Bitmap Allocator Memory Map" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left">268</td><td align="left">0</td><td align="left">4294967295</td><td align="left">4294967295</td><td align="left">Data -&gt; Space for 64 ints</td></tr></tbody></table></div></div><br class="table-break" /><p>
The first Column(268) represents the size of the Block in bytes as
seen by the Bitmap Allocator. Internally, a global free list is
used to keep track of the free blocks used and given back by the
@ -192,20 +192,20 @@ For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524%
_S_refill_pool which does the following:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Gets more memory from the Global Free List of the Required
size.
size.
</p></li><li class="listitem"><p>
Adjusts the size for the next call to itself.
Adjusts the size for the next call to itself.
</p></li><li class="listitem"><p>
Writes the appropriate headers in the bit-maps.
</p></li><li class="listitem"><p>
Sets the use count for that super-block just allocated to 0
(zero).
(zero).
</p></li><li class="listitem"><p>
All of the above accounts to maintaining the basic invariant
for the allocator. If the invariant is maintained, we are
sure that all is well. Now, the same process is applied on
the newly acquired free blocks, which are dispatched
accordingly.
accordingly.
</p></li></ul></div></li></ol></div><p>
Thus, you can clearly see that the allocate function is nothing but a
combination of the next-fit and first-fit algorithm optimized ONLY for
@ -337,4 +337,4 @@ equivalent.</p></li><li class="listitem"><p>And also this would preserve the cac
sizeof(size_t) x 8 which is the number of bits in an integer,
which can fit exactly in a CPU register. Hence, the term given is
exponential growth of the internal pool.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_allocators.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 33. Allocators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 34. Containers</td></tr></table></div></body></html>
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_allocators.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_allocators.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_containers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 20. Allocators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 21. Containers</td></tr></table></div></body></html>

105
libstdc++-v3/doc/html/manual/bitset.html
View file

@ -1,105 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="associative.html" title="Chapter 17. Associative" /><link rel="prev" href="associative.html" title="Chapter 17. Associative" /><link rel="next" href="containers_and_c.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="associative.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Associative</th><td width="20%" align="right"> <a accesskey="n" href="containers_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="bitset"><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" title="Size Variable"><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 class="itemizedlist" type="disc"><li class="listitem"><p>A very large N in <code class="code">bitset&lt;N&gt;</code>.</p></li><li class="listitem"><p>A container&lt;bool&gt;.</p></li><li class="listitem"><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">“<span class="quote">changed</span>”</span>/<span class="quote">“<span class="quote">unchanged</span>”</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">“<span class="quote">maximum bit used</span>”</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
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="link" href="bk01pt12ch34s02.html" title="HP/SGI">some extensions</a>.
</p></div><div class="sect2" title="Type String"><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">“<span class="quote">Links</span>”</span> from
the homepage, and from the C++ information <span class="quote">“<span class="quote">defect
reflector</span>”</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">“<span class="quote">10110</span>”</span>) );
</pre><p>
instead of
</p><pre class="programlisting">
std::bitset&lt;5&gt; b ( <span class="quote">“<span class="quote">10110</span>”</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="associative.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="associative.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="containers_and_c.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>

51
libstdc++-v3/doc/html/manual/bk01ix01.html
View file

@ -1,51 +0,0 @@
<?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>Index</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" 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_gfdl.html" title="Appendix E. GNU Free Documentation License" /><link rel="next" href="../bk02.html" title="" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Index</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_gfdl.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr></table><hr /></div><div class="index" title="Index"><div class="titlepage"><div><div><h2 class="title"><a id="id649926"></a>Index</h2></div></div></div><div class="index"><div class="indexdiv"><h3>A</h3><dl><dt>Algorithms, <a class="indexterm" href="algorithms.html">
Algorithms
</a></dt><dt>Appendix</dt><dd><dl><dt>Contributing, <a class="indexterm" href="appendix_contributing.html">
Contributing
</a></dt><dt>Free Documentation, <a class="indexterm" href="appendix_free.html">
Free Software Needs Free Documentation
</a></dt><dt>Porting and Maintenance, <a class="indexterm" href="appendix_porting.html">
Porting and Maintenance
</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>C</h3><dl><dt>Containers, <a class="indexterm" href="containers.html">
Containers
</a></dt></dl></div><div class="indexdiv"><h3>D</h3><dl><dt>Diagnostics, <a class="indexterm" href="diagnostics.html">
Diagnostics
</a></dt></dl></div><div class="indexdiv"><h3>E</h3><dl><dt>Extensions, <a class="indexterm" href="extensions.html">
Extensions
</a></dt></dl></div><div class="indexdiv"><h3>I</h3><dl><dt>Input and Output, <a class="indexterm" href="io.html">
Input and Output
</a></dt><dt>Introduction, <a class="indexterm" href="intro.html">
Introduction
</a></dt><dt>Iterators, <a class="indexterm" href="iterators.html">
Iterators
</a></dt></dl></div><div class="indexdiv"><h3>L</h3><dl><dt>Localization, <a class="indexterm" href="localization.html">
Localization
</a></dt></dl></div><div class="indexdiv"><h3>N</h3><dl><dt>Numerics, <a class="indexterm" href="numerics.html">
Numerics
</a></dt></dl></div><div class="indexdiv"><h3>S</h3><dl><dt>Strings, <a class="indexterm" href="strings.html">
Strings
</a></dt><dt>Support, <a class="indexterm" href="support.html">
Support
</a></dt></dl></div><div class="indexdiv"><h3>T</h3><dl><dt>Test</dt><dd><dl><dt>Exception Safety, <a class="indexterm" href="test.html#test.exception.safety">
Qualifying Exception Safety Guarantees
</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>U</h3><dl><dt>Utilities, <a class="indexterm" href="utilities.html">
Utilities
</a></dt></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_gfdl.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="../bk02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix E. GNU Free Documentation License </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>

46
libstdc++-v3/doc/html/manual/bk01pt02.html Normal file
View file

@ -0,0 +1,46 @@
<?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 II.  Standard Contents</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="debug.html" title="Debugging Support" /><link rel="next" href="support.html" title="Chapter 4.  Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part II. 
Standard Contents
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="debug.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="support.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part II.  Standard Contents"><div class="titlepage"><div><div><h1 class="title"><a id="manual.std"></a>Part II. 
Standard Contents
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="support.html">4.
Support
</a></span></dt><dd><dl><dt><span class="sect1"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="sect2"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="sect2"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="sect1"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="sect1"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="sect2"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="sect2"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5.
Diagnostics
</a></span></dt><dd><dl><dt><span class="sect1"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="sect2"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="sect2"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt02ch05s02.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6.
Utilities
</a></span></dt><dd><dl><dt><span class="section"><a href="utilities.html#std.util.functors">Functors</a></span></dt><dt><span class="section"><a href="pairs.html">Pairs</a></span></dt><dt><span class="section"><a href="memory.html">Memory</a></span></dt><dd><dl><dt><span class="section"><a href="memory.html#std.util.memory.allocator">Allocators</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.auto_ptr">auto_ptr</a></span></dt><dt><span class="section"><a href="memory.html#std.util.memory.shared_ptr">shared_ptr</a></span></dt></dl></dd><dt><span class="section"><a href="traits.html">Traits</a></span></dt></dl></dd><dt><span class="chapter"><a href="strings.html">7.
Strings
</a></span></dt><dd><dl><dt><span class="sect1"><a href="strings.html#std.strings.string">String Classes</a></span></dt><dd><dl><dt><span class="sect2"><a href="strings.html#strings.string.simple">Simple Transformations</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.case">Case Sensitivity</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.character_types">Arbitrary Character Types</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.token">Tokenizing</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.shrink">Shrink to Fit</a></span></dt><dt><span class="sect2"><a href="strings.html#strings.string.Cstring">CString (MFC)</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="localization.html">8.
Localization
</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales">Locales</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales.locale">locale</a></span></dt></dl></dd><dt><span class="section"><a href="facets.html">Facets</a></span></dt><dd><dl><dt><span class="section"><a href="facets.html#std.localization.facet.ctype">ctype</a></span></dt><dt><span class="section"><a href="facets.html#std.localization.facet.codecvt">codecvt</a></span></dt><dt><span class="section"><a href="facets.html#manual.localization.facet.messages">messages</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="containers.html">9.
Containers
</a></span></dt><dd><dl><dt><span class="sect1"><a href="containers.html#std.containers.sequences">Sequences</a></span></dt><dd><dl><dt><span class="sect2"><a href="containers.html#containers.sequences.list">list</a></span></dt><dt><span class="sect2"><a href="containers.html#containers.sequences.vector">vector</a></span></dt></dl></dd><dt><span class="sect1"><a href="associative.html">Associative</a></span></dt><dd><dl><dt><span class="sect2"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect2"><a href="associative.html#containers.associative.bitset">bitset</a></span></dt></dl></dd><dt><span class="sect1"><a href="containers_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="sect2"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="iterators.html">10.
Iterators
</a></span></dt><dd><dl><dt><span class="sect1"><a href="iterators.html#std.iterators.predefined">Predefined</a></span></dt><dd><dl><dt><span class="sect2"><a href="iterators.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="sect2"><a href="iterators.html#iterators.predefined.end">One Past the End</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="algorithms.html">11.
Algorithms
</a></span></dt><dd><dl><dt><span class="sect1"><a href="algorithms.html#std.algorithms.mutating">Mutating</a></span></dt><dd><dl><dt><span class="sect2"><a href="algorithms.html#algorithms.mutating.swap"><code class="function">swap</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="numerics.html">12.
Numerics
</a></span></dt><dd><dl><dt><span class="sect1"><a href="numerics.html#std.numerics.complex">Complex</a></span></dt><dd><dl><dt><span class="sect2"><a href="numerics.html#numerics.complex.processing">complex Processing</a></span></dt></dl></dd><dt><span class="sect1"><a href="generalized_numeric_operations.html">Generalized Operations</a></span></dt><dt><span class="sect1"><a href="numerics_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="sect2"><a href="numerics_and_c.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="sect2"><a href="numerics_and_c.html#numerics.c.c99">C99</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="io.html">13.
Input and Output
</a></span></dt><dd><dl><dt><span class="sect1"><a href="io.html#std.io.objects">Iostream Objects</a></span></dt><dt><span class="sect1"><a href="streambufs.html">Stream Buffers</a></span></dt><dd><dl><dt><span class="sect2"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="sect2"><a href="streambufs.html#io.streambuf.buffering">Buffering</a></span></dt></dl></dd><dt><span class="sect1"><a href="stringstreams.html">Memory Based Streams</a></span></dt><dd><dl><dt><span class="sect2"><a href="stringstreams.html#std.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="sect1"><a href="fstreams.html">File Based Streams</a></span></dt><dd><dl><dt><span class="sect2"><a href="fstreams.html#std.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="sect2"><a href="fstreams.html#std.io.filestreams.binary">Binary Input and Output</a></span></dt></dl></dd><dt><span class="sect1"><a href="io_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="sect2"><a href="io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="sect2"><a href="io_and_c.html#std.io.c.sync">Performance</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="atomics.html">14.
Atomics
</a></span></dt><dd><dl><dt><span class="sect1"><a href="atomics.html#std.atomics.api">API Reference</a></span></dt></dl></dd><dt><span class="chapter"><a href="concurrency.html">15.
Concurrency
</a></span></dt><dd><dl><dt><span class="sect1"><a href="concurrency.html#std.concurrency.api">API Reference</a></span></dt></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="debug.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="support.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Debugging 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. 
Support
</td></tr></table></div></body></html>

49
libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html
View file

@ -1,49 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="fundamental_types.html" title="Chapter 4. Types" /><link rel="prev" href="fundamental_types.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="fundamental_types.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" title="Numeric Properties"><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/a00593.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="fundamental_types.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fundamental_types.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>

29
libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html
View file

@ -1,29 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="fundamental_types.html" title="Chapter 4. Types" /><link rel="prev" href="bk01pt02ch04s02.html" title="Numeric Properties" /><link rel="next" href="dynamic_memory.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="dynamic_memory.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="NULL"><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">“<span class="quote">0L</span>”</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="fundamental_types.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic_memory.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>

9
libstdc++-v3/doc/html/manual/bk01pt03ch08.html → libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="diagnostics.html" title="Part III.  Diagnostics" /><link rel="prev" href="bk01pt03ch07s02.html" title="Adding Data to Exceptions" /><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="bk01pt03ch07s02.html">Prev</a> </td><th width="60%" align="center">Part III. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Concept Checking</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="diagnostics.html" title="Chapter 5.  Diagnostics" /><link rel="prev" href="diagnostics.html" title="Chapter 5.  Diagnostics" /><link rel="next" href="utilities.html" title="Chapter 6.  Utilities" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concept Checking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><th width="60%" align="center">Chapter 5. 
Diagnostics
</th><td width="20%" align="right"> <a accesskey="n" href="utilities.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 8. Concept Checking"><div class="titlepage"><div><div><h2 class="title"><a id="manual.diagnostics.concept_checking"></a>Chapter 8. Concept Checking</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="utilities.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Concept Checking"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.diagnostics.concept_checking"></a>Concept Checking</h2></div></div></div><p>
In 1999, SGI added <span class="quote">“<span class="quote">concept checkers</span>”</span> to their
implementation of the STL: code which checked the template
parameters of instantiated pieces of the STL, in order to insure
@ -39,7 +39,10 @@
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="bk01pt03ch07s02.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">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"> Part IV. 
</p></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="utilities.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. 
Diagnostics
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. 
Utilities
</td></tr></table></div></body></html>

17
libstdc++-v3/doc/html/manual/bk01pt02pr01.html
View file

@ -1,17 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="fundamental_types.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="fundamental_types.html">Next</a></td></tr></table><hr /></div><div class="preface"><div class="titlepage"><div><div><h2 class="title"><a id="id616146"></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="fundamental_types.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>

20
libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html
View file

@ -1,20 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="exceptions.html" title="Chapter 7. Exceptions" /><link rel="prev" href="exceptions.html" title="Chapter 7. 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">Adding Data to Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="exceptions.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" title="Adding Data to Exceptions"><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="exceptions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="exceptions.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">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"> Chapter 8. Concept Checking</td></tr></table></div></body></html>

4
libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html
View file

@ -1,4 +0,0 @@
<?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.74.3" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="exceptions.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="exceptions.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>

6
libstdc++-v3/doc/html/manual/bk01pt12ch30s02.html → libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" 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" title="Semantics"><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>
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode" /><link rel="prev" href="debug_mode.html" title="Chapter 17. Debug Mode" /><link rel="next" href="bk01pt03ch17s03.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 17. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch17s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Semantics"><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
@ -10,7 +10,7 @@
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
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
@ -52,4 +52,4 @@ 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>
</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="bk01pt03ch17s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 17. 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>

24
libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html Normal file
View file

@ -0,0 +1,24 @@
<?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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode" /><link rel="prev" href="bk01pt03ch17s02.html" title="Semantics" /><link rel="next" href="bk01pt03ch17s04.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="bk01pt03ch17s02.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch17s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Using"><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" title="Using the Debug Mode"><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" title="Using a Specific Debug Container"><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="id487304"></a><p class="title"><b>Table 17.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" /></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></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">&lt;debug/bitset&gt;</code></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">&lt;debug/deque&gt;</code></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">&lt;debug/list&gt;</code></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">&lt;debug/map&gt;</code></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">&lt;debug/map&gt;</code></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">&lt;debug/set&gt;</code></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">&lt;debug/set&gt;</code></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">&lt;debug/string&gt;</code></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">&lt;debug/string&gt;</code></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">&lt;debug/string&gt;</code></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">&lt;debug/vector&gt;</code></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="id488498"></a><p class="title"><b>Table 17.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" /></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></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">&lt;debug/unordered_map&gt;</code></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">&lt;debug/unordered_map&gt;</code></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">&lt;debug/unordered_set&gt;</code></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">&lt;debug/unordered_set&gt;</code></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="bk01pt03ch17s02.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="bk01pt03ch17s04.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>

32
libstdc++-v3/doc/html/manual/bk01pt12ch30s04.html → libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" 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="bk01pt12ch30s03.html" title="Using" /><link rel="next" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /></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="bk01pt12ch30s03.html">Prev</a> </td><th width="60%" align="center">Chapter 30. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.design"></a>Design</h2></div></div></div><p>
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode" /><link rel="prev" href="bk01pt03ch17s03.html" title="Using" /><link rel="next" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /></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="bk01pt03ch17s03.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.design"></a>Design</h2></div></div></div><p>
</p><div class="sect2" title="Goals"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.goals"></a>Goals</h3></div></div></div><p>
</p><p> The libstdc++ debug mode replaces unsafe (but efficient) standard
containers and iterators with semantically equivalent safe standard
@ -38,7 +38,7 @@
own usability and implementation characteristics. In general, the
higher-numbered conformance levels are more usable (i.e., require
less recompilation) but are more complicated to implement than
the lower-numbered conformance levels.
the lower-numbered conformance levels.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Full recompilation</em></span>: The user must recompile his or
her entire application and all C++ libraries it depends on,
including the C++ standard library that ships with the
@ -101,7 +101,7 @@
container that will perform the actual work. This design decision
ensures that we cannot regress release-mode performance (because the
release-mode containers are left untouched) and partially
enables <a class="link" href="bk01pt12ch30s04.html#methods.coexistence.link" title="Link- and run-time coexistence of release- and debug-mode components">mixing debug and
enables <a class="link" href="bk01pt03ch17s04.html#methods.coexistence.link" title="Link- and run-time coexistence of release- and debug-mode components">mixing debug and
release code</a> at link time, although that will not be
discussed at this time.</p><p>Two types of wrappers are used in the implementation of the debug
mode: container wrappers and iterator wrappers. The two types of
@ -133,8 +133,8 @@
version) as appropriate. However, all safe containers inherit from
the class template <code class="code">__gnu_debug::_Safe_sequence</code>,
instantiated with the type of the safe container itself (an instance
of the curiously recurring template pattern).</p><p>The iterators of a container wrapper will be
<a class="link" href="bk01pt12ch30s04.html#debug_mode.design.methods.safe_iter" title="Safe Iterators">safe
of the curiously recurring template pattern).</p><p>The iterators of a container wrapper will be
<a class="link" href="bk01pt03ch17s04.html#debug_mode.design.methods.safe_iter" title="Safe Iterators">safe
iterators</a> that reference sequences of this type and wrap the
iterators provided by the release-mode base class. The debugging
container will use only the safe iterators within its own interface
@ -221,7 +221,7 @@ namespace std
};
} // namespace std
</pre><p>In debug mode we include the release-mode container (which is now
defined in in the namespace <code class="code">__norm</code>) and also the
defined in the namespace <code class="code">__norm</code>) and also the
debug-mode container. The debug-mode container is defined within the
namespace <code class="code">__debug</code>, which is associated with namespace
<code class="code">std</code> via the C++0x namespace association language feature. This
@ -236,7 +236,7 @@ namespace std
template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
class list
{
// ...
// ...
};
} // namespace __gnu_norm
@ -245,9 +245,9 @@ namespace std
template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
class list
: public __norm::list&lt;_Tp, _Alloc&gt;,
public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
{
// ...
// ...
};
} // namespace __norm
@ -256,7 +256,7 @@ namespace std
}
</pre></div><div class="sect4" title="Link- and run-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.link"></a>Link- and run-time coexistence of release- and
debug-mode components</h5></div></div></div><p>Because each component has a distinct and separate release and
debug implementation, there are are no issues with link-time
debug implementation, there is no issue with link-time
coexistence: the separate namespaces result in different mangled
names, and thus unique linkage.</p><p>However, components that are defined and used within the C++
standard library itself face additional constraints. For instance,
@ -273,12 +273,12 @@ runtime errors. A simplified example of this problem is as follows.
#include &lt;string&gt;
std::string test02();
std::string test01()
{
return test02();
}
int main()
{
test01();
@ -286,7 +286,7 @@ int main()
}
</pre><p> ... and linked to this translation unit, compiled in release mode:</p><pre class="programlisting">
#include &lt;string&gt;
std::string
test02()
{
@ -349,7 +349,7 @@ test02()
enticing option, because it would eliminate the need for
the <code class="code">link_name</code> extension by aliasing the
templates. However, there is no true template aliasing mechanism
is C++, because both <code class="code">using</code> directives and using
in C++, because both <code class="code">using</code> directives and using
declarations disallow specialization. This method fails
the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em> Use implementation-specific properties of anonymous
namespaces. </em></span>
@ -375,7 +375,7 @@ test02()
include ordering. Two, ODR issues remained with container member
functions taking no arguments in mixed-mode settings resulting in
equivalent link names, <code class="code"> vector::push_back() </code> being
one example.
one example.
See <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html" target="_top">link
name</a> </p></li></ul></div><p>Other options may exist for implementing the debug mode, many of
which have probably been considered and others that may still be
@ -409,4 +409,4 @@ test02()
a full debug-mode implementation (including debugging for
CodeWarrior extensions) and is easy to use, although it meets only
the "Full recompilation" (1) recompilation
guarantee.</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch30s03.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="parallel_mode.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"> Chapter 31. Parallel Mode</td></tr></table></div></body></html>
guarantee.</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch17s03.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="parallel_mode.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"> Chapter 18. Parallel Mode</td></tr></table></div></body></html>

4
libstdc++-v3/doc/html/manual/bk01pt12ch31s02.html → libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" 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" title="Semantics"><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,
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /><link rel="prev" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /><link rel="next" href="bk01pt03ch18s03.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 18. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch18s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Semantics"><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.
Also, the order of execution is not guaranteed for some functions, of course.
Therefore, user-defined functors should not have any concurrent side effects.
@ -8,4 +8,4 @@ Therefore, user-defined functors should not have any concurrent side effects.
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>
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="bk01pt03ch18s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 18. 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>

6
libstdc++-v3/doc/html/manual/bk01pt12ch31s03.html → libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html
View file

File diff suppressed because one or more lines are too long

10
libstdc++-v3/doc/html/manual/bk01pt12ch31s04.html → libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" 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" title="Design"><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>
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /><link rel="prev" href="bk01pt03ch18s03.html" title="Using" /><link rel="next" href="bk01pt03ch18s05.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="bk01pt03ch18s03.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch18s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><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" title="Interface Basics"><div class="titlepage"><div><div><h3 class="title"><a id="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
@ -105,7 +105,7 @@ For the following algorithms in general, we have
<code class="code">__gnu_parallel::parallel_tag</code> and
<code class="code">__gnu_parallel::default_parallel_tag</code>, in addition to
<code class="code">__gnu_parallel::sequential_tag</code>.
<code class="code">__gnu_parallel::default_parallel_tag</code> chooses the default
<code class="code">__gnu_parallel::default_parallel_tag</code> chooses the default
algorithm at compiletime, as does omitting the tag.
<code class="code">__gnu_parallel::parallel_tag</code> postpones the decision to runtime
(see next section).
@ -120,7 +120,7 @@ Exact and sampling are the two available splitting strategies.
For the <code class="code">sort</code> and <code class="code">stable_sort</code> algorithms, there are
several additional choices, namely
<code class="code">__gnu_parallel::multiway_mergesort_tag</code>,
<code class="code">__gnu_parallel::multiway_mergesort_exact_tag</code>,
<code class="code">__gnu_parallel::multiway_mergesort_exact_tag</code>,
<code class="code">__gnu_parallel::multiway_mergesort_sampling_tag</code>,
<code class="code">__gnu_parallel::quicksort_tag</code>, and
<code class="code">__gnu_parallel::balanced_quicksort_tag</code>.
@ -198,7 +198,7 @@ int main()
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>.
<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="function">std::transform</code> from <code class="filename">algorithm</code> has a parallel counterpart in
@ -210,4 +210,4 @@ __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>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch18s03.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="bk01pt03ch18s05.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>

8
libstdc++-v3/doc/html/manual/bk01pt12ch31s05.html → libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html
View file

@ -1,9 +1,9 @@
<?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.75.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="home" 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="profile_mode.html" title="Chapter 32. Profile Mode" /></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="profile_mode.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Testing"><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>
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /><link rel="prev" href="bk01pt03ch18s04.html" title="Design" /><link rel="next" href="profile_mode.html" title="Chapter 19. Profile Mode" /></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="bk01pt03ch18s04.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Testing"><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>
</p><p>
To run the conformance and regression tests with the parallel mode
active,
</p><pre class="screen">
@ -11,7 +11,7 @@
</pre><p>
The log and summary files for conformance testing are in the
<code class="filename">testsuite/parallel</code> directory.
</p><p>
</p><p>
To run the performance tests with the parallel mode active,
</p><pre class="screen">
<strong class="userinput"><code>make check-performance-parallel</code></strong>
@ -23,4 +23,4 @@
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="profile_mode.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. Profile Mode</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch18s04.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="profile_mode.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 19. Profile Mode</td></tr></table></div></body></html>

22
libstdc++-v3/doc/html/manual/bk01pt12ch32s02.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html
View file

@ -1,7 +1,7 @@
<?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.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="next" href="bk01pt12ch32s03.html" title="Extensions for Custom Containers" /></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="profile_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.design"></a>Design</h2></div></div></div><p>
</p><div class="table"><a id="id594983"></a><p class="title"><b>Table 32.1. Code Location</b></p><div class="table-contents"><table summary="Code Location" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Code Location</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><code class="code">libstdc++-v3/include/std/*</code></td><td align="left">Preprocessor code to redirect to profile extension headers.</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/*</code></td><td align="left">Profile extension public headers (map, vector, ...).</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/impl/*</code></td><td align="left">Profile extension internals. Implementation files are
<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.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="next" href="bk01pt03ch19s03.html" title="Extensions for Custom Containers" /></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="profile_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.design"></a>Design</h2></div></div></div><p>
</p><div class="table"><a id="id387560"></a><p class="title"><b>Table 19.1. Profile Code Location</b></p><div class="table-contents"><table summary="Profile Code Location" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Code Location</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><code class="code">libstdc++-v3/include/std/*</code></td><td align="left">Preprocessor code to redirect to profile extension headers.</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/*</code></td><td align="left">Profile extension public headers (map, vector, ...).</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/impl/*</code></td><td align="left">Profile extension internals. Implementation files are
only included from <code class="code">impl/profiler.h</code>, which is the only
file included from the public headers.</td></tr></tbody></table></div></div><br class="table-break" /><p>
</p><div class="sect2" title="Wrapper Model"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.wrapper"></a>Wrapper Model</h3></div></div></div><p>
@ -10,12 +10,12 @@
we use the same wrapper model as the debug mode.
We subclass entities from the release version. Wherever
<code class="code">_GLIBCXX_PROFILE</code> is defined, the release namespace is
<code class="code">std::__norm</code>, whereas the profile namespace is
<code class="code">std::__norm</code>, whereas the profile namespace is
<code class="code">std::__profile</code>. Using plain <code class="code">std</code> translates
into <code class="code">std::__profile</code>.
</p><p>
Whenever possible, we try to wrap at the public interface level, e.g.,
in <code class="code">unordered_set</code> rather than in <code class="code">hashtable</code>,
in <code class="code">unordered_set</code> rather than in <code class="code">hashtable</code>,
in order not to depend on implementation.
</p><p>
Mixing object files built with and without the profile mode must
@ -29,12 +29,12 @@
Instead of instrumenting every public entry and exit point,
we chose to add instrumentation on demand, as needed
by individual diagnostics.
The main reason is that some diagnostics require us to extract bits of
The main reason is that some diagnostics require us to extract bits of
internal state that are particular only to that diagnostic.
We plan to formalize this later, after we learn more about the requirements
of several diagnostics.
</p><p>
All the instrumentation points can be switched on and off using
All the instrumentation points can be switched on and off using
<code class="code">-D[_NO]_GLIBCXX_PROFILE_&lt;diagnostic&gt;</code> options.
With all the instrumentation calls off, there should be negligible
overhead over the release version. This property is needed to support
@ -42,7 +42,7 @@
we anticipate turning most of the instrumentation off in order to prevent
profiling overhead from polluting time measurements, and thus diagnostics.
</p><p>
All the instrumentation on/off compile time switches live in
All the instrumentation on/off compile time switches live in
<code class="code">include/profile/profiler.h</code>.
</p></div><div class="sect2" title="Run Time Behavior"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.rtlib"></a>Run Time Behavior</h3></div></div></div><p>
For practical reasons, the instrumentation library processes the trace
@ -60,7 +60,7 @@
is destroyed, we accumulate its effect to the corresponding entry for the
call stack of its constructor location.
</p><p>
For details, see
For details, see
<a class="ulink" href="http://dx.doi.org/10.1109/CGO.2009.36" target="_top">paper presented at
CGO 2009</a>.
</p></div><div class="sect2" title="Analysis and Diagnostics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.analysis"></a>Analysis and Diagnostics</h3></div></div></div><p>
@ -71,7 +71,7 @@
The input to the analysis is a table indexed by profile type and call stack.
The data type for each entry depends on the profile type.
</p></div><div class="sect2" title="Cost Model"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.cost-model"></a>Cost Model</h3></div></div></div><p>
While it is likely that cost models become complex as we get into
While it is likely that cost models become complex as we get into
more sophisticated analysis, we will try to follow a simple set of rules
at the beginning.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Relative benefit estimation:</em></span>
@ -95,7 +95,7 @@
and report the one that performs best for each call context.
</p></li><li class="listitem"><p><span class="emphasis"><em>Show stoppers:</em></span>
We may decide that the presence of an operation nullifies the advice.
For instance, when considering switching from <code class="code">set</code> to
For instance, when considering switching from <code class="code">set</code> to
<code class="code">unordered_set</code>, if we detect use of operator <code class="code">++</code>,
we will simply not issue the advice, since this could signal that the use
care require a sorted container.</p></li></ul></div></div><div class="sect2" title="Reports"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.reports"></a>Reports</h3></div></div></div><p>
@ -119,4 +119,4 @@ it helps the user focus on the key problems and ignore the uninteresting ones.
We created a <code class="code">profile</code> directory in the test suite.
Each diagnostic must come with at least two tests, one for false positives
and one for false negatives.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 32. Profile Mode </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Extensions for Custom Containers</td></tr></table></div></body></html>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Profile Mode </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Extensions for Custom Containers</td></tr></table></div></body></html>

4
libstdc++-v3/doc/html/manual/bk01pt12ch32s03.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html
View file

@ -1,10 +1,10 @@
<?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>Extensions for Custom Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="bk01pt12ch32s02.html" title="Design" /><link rel="next" href="bk01pt12ch32s04.html" title="Empirical Cost Model" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Extensions for Custom Containers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s02.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Extensions for Custom Containers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.api"></a>Extensions for Custom Containers</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Extensions for Custom Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="bk01pt03ch19s02.html" title="Design" /><link rel="next" href="bk01pt03ch19s04.html" title="Empirical Cost Model" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Extensions for Custom Containers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s02.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Extensions for Custom Containers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.api"></a>Extensions for Custom Containers</h2></div></div></div><p>
Many large projects use their own data structures instead of the ones in the
standard library. If these data structures are similar in functionality
to the standard library, they can be instrumented with the same hooks
that are used to instrument the standard library.
The instrumentation API is exposed in file
<code class="code">profiler.h</code> (look for "Instrumentation hooks").
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32s04.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"> Empirical Cost Model</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s04.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"> Empirical Cost Model</td></tr></table></div></body></html>

4
libstdc++-v3/doc/html/manual/bk01pt12ch32s04.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html
View file

@ -1,6 +1,6 @@
<?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>Empirical Cost Model</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="bk01pt12ch32s03.html" title="Extensions for Custom Containers" /><link rel="next" href="bk01pt12ch32s05.html" title="Implementation Issues" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Empirical Cost Model</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s03.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Empirical Cost Model"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.cost_model"></a>Empirical Cost Model</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Empirical Cost Model</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="bk01pt03ch19s03.html" title="Extensions for Custom Containers" /><link rel="next" href="bk01pt03ch19s05.html" title="Implementation Issues" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Empirical Cost Model</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s03.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Empirical Cost Model"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.cost_model"></a>Empirical Cost Model</h2></div></div></div><p>
Currently, the cost model uses formulas with predefined relative weights
for alternative containers or container implementations. For instance,
iterating through a vector is X times faster than iterating through a list.
@ -15,4 +15,4 @@
filled in either by hand or by an automated training mechanism.
The analysis module will then use this database instead of the built in.
generic parameters.
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extensions for Custom Containers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation Issues</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extensions for Custom Containers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation Issues</td></tr></table></div></body></html>

14
libstdc++-v3/doc/html/manual/bk01pt12ch32s05.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html
View file

@ -1,6 +1,6 @@
<?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 Issues</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="bk01pt12ch32s04.html" title="Empirical Cost Model" /><link rel="next" href="bk01pt12ch32s06.html" title="Developer Information" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation Issues</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s04.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32s06.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Implementation Issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.implementation"></a>Implementation Issues</h2></div></div></div><div class="sect2" title="Stack Traces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stack"></a>Stack Traces</h3></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Implementation Issues</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="bk01pt03ch19s04.html" title="Empirical Cost Model" /><link rel="next" href="bk01pt03ch19s06.html" title="Developer Information" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation Issues</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s04.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s06.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Implementation Issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.implementation"></a>Implementation Issues</h2></div></div></div><div class="sect2" title="Stack Traces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stack"></a>Stack Traces</h3></div></div></div><p>
Accurate stack traces are needed during profiling since we group events by
call context and dynamic instance. Without accurate traces, diagnostics
may be hard to interpret. For instance, when giving advice to the user
@ -24,15 +24,15 @@
During profiling, we keep a single information table per diagnostic.
There is a single lock per information table.
</p></div><div class="sect2" title="Using the Standard Library in the Instrumentation Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stdlib-in-proflib"></a>Using the Standard Library in the Instrumentation Implementation</h3></div></div></div><p>
As much as we would like to avoid uses of stdlibc++ within our
instrumentation library, containers such as unordered_map are very
appealing. We plan to use them as long as they are named properly
As much as we would like to avoid uses of libstdc++ within our
instrumentation library, containers such as unordered_map are very
appealing. We plan to use them as long as they are named properly
to avoid ambiguity.
</p></div><div class="sect2" title="Malloc Hooks"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.malloc-hooks"></a>Malloc Hooks</h3></div></div></div><p>
User applications/libraries can provide malloc hooks.
When the implementation of the malloc hooks uses stdlibc++, there can
be an infinite cycle between the profile mode instrumentation and the
the malloc hook code.
malloc hook code.
</p><p>
We protect against reentrance to the profile mode instrumentation code,
which should avoid this problem in most cases.
@ -46,6 +46,6 @@
The profiling library state is initialized at the first call to a profiling
method. This allows us to record the construction of all global objects.
However, we cannot do the same at destruction time. The trace is written
by a function registered by <code class="code">atexit</code>, thus invoked by
by a function registered by <code class="code">atexit</code>, thus invoked by
<code class="code">exit</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Empirical Cost Model </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Developer Information</td></tr></table></div></body></html>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Empirical Cost Model </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Developer Information</td></tr></table></div></body></html>

16
libstdc++-v3/doc/html/manual/bk01pt12ch32s06.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html
View file

@ -1,21 +1,21 @@
<?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>Developer Information</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="bk01pt12ch32s05.html" title="Implementation Issues" /><link rel="next" href="bk01pt12ch32s07.html" title="Diagnostics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Developer Information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s05.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch32s07.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Developer Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.developer"></a>Developer Information</h2></div></div></div><div class="sect2" title="Big Picture"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.bigpic"></a>Big Picture</h3></div></div></div><p>The profile mode headers are included with
<code class="code">-D_GLIBCXX_PROFILE</code> through preprocessor directives in
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Developer Information</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="bk01pt03ch19s05.html" title="Implementation Issues" /><link rel="next" href="bk01pt03ch19s07.html" title="Diagnostics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Developer Information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Developer Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.developer"></a>Developer Information</h2></div></div></div><div class="sect2" title="Big Picture"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.bigpic"></a>Big Picture</h3></div></div></div><p>The profile mode headers are included with
<code class="code">-D_GLIBCXX_PROFILE</code> through preprocessor directives in
<code class="code">include/std/*</code>.
</p><p>Instrumented implementations are provided in
</p><p>Instrumented implementations are provided in
<code class="code">include/profile/*</code>. All instrumentation hooks are macros
defined in <code class="code">include/profile/profiler.h</code>.
</p><p>All the implementation of the instrumentation hooks is in
</p><p>All the implementation of the instrumentation hooks is in
<code class="code">include/profile/impl/*</code>. Although all the code gets included,
thus is publicly visible, only a small number of functions are called from
outside this directory. All calls to hook implementations must be
done through macros defined in <code class="code">profiler.h</code>. The macro
must ensure (1) that the call is guarded against reentrance and
must ensure (1) that the call is guarded against reentrance and
(2) that the call can be turned off at compile time using a
<code class="code">-D_GLIBCXX_PROFILE_...</code> compiler option.
</p></div><div class="sect2" title="How To Add A Diagnostic"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.howto"></a>How To Add A Diagnostic</h3></div></div></div><p>Let's say the diagnostic name is "magic".
</p><p>If you need to instrument a header not already under
</p><p>If you need to instrument a header not already under
<code class="code">include/profile/*</code>, first edit the corresponding header
under <code class="code">include/std/</code> and add a preprocessor directive such
as the one in <code class="code">include/std/vector</code>:
@ -57,7 +57,7 @@
Define class <code class="code">__magic_stack_info: public __magic_info</code>.
This defines the content of a line in the stack table.
</p></li><li class="listitem"><p>
Define class <code class="code">__trace_magic: public __trace_base&lt;__magic_info,
Define class <code class="code">__trace_magic: public __trace_base&lt;__magic_info,
__magic_stack_info&gt;</code>.
It defines the content of the trace associated with this diagnostic.
</p></li></ul></div><p>
@ -65,4 +65,4 @@
<code class="code">include/profile/impl/profiler_trace.h</code>. Use
<code class="code">__trace_vector_to_list</code> as an example.
</p><p>Add documentation in file <code class="code">doc/xml/manual/profile_mode.xml</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch32s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Implementation Issues </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Diagnostics</td></tr></table></div></body></html>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Implementation Issues </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Diagnostics</td></tr></table></div></body></html>

100
libstdc++-v3/doc/html/manual/bk01pt12ch32s07.html → libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html
View file

@ -1,12 +1,12 @@
<?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>Diagnostics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 32. Profile Mode" /><link rel="prev" href="bk01pt12ch32s06.html" title="Developer Information" /><link rel="next" href="ext_allocators.html" title="Chapter 33. Allocators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Diagnostics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s06.html">Prev</a> </td><th width="60%" align="center">Chapter 32. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Diagnostics"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.diagnostics"></a>Diagnostics</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Diagnostics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; library&#10; , &#10; profile&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="bk01pt03ch19s06.html" title="Developer Information" /><link rel="next" href="ext_allocators.html" title="Chapter 20. Allocators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Diagnostics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s06.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Diagnostics"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.diagnostics"></a>Diagnostics</h2></div></div></div><p>
The table below presents all the diagnostics we intend to implement.
Each diagnostic has a corresponding compile time switch
<code class="code">-D_GLIBCXX_PROFILE_&lt;diagnostic&gt;</code>.
Groups of related diagnostics can be turned on with a single switch.
For instance, <code class="code">-D_GLIBCXX_PROFILE_LOCALITY</code> is equivalent to
<code class="code">-D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH
<code class="code">-D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH
-D_GLIBCXX_PROFILE_RBTREE_LOCALITY</code>.
</p><p>
The benefit, cost, expected frequency and accuracy of each diagnostic
@ -18,7 +18,7 @@
A high accuracy means that the diagnostic is unlikely to be wrong.
These grades are not perfect. They are just meant to guide users with
specific needs or time budgets.
</p><div class="table"><a id="id626153"></a><p class="title"><b>Table 32.2. Diagnostics</b></p><div class="table-contents"><table summary="Diagnostics" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Group</th><th align="left">Flag</th><th align="left">Benefit</th><th align="left">Cost</th><th align="left">Freq.</th><th align="left">Implemented</th></tr></thead><tbody><tr><td align="left"><a class="ulink" href="#manual.ext.profile_mode.analysis.containers" target="_top">
</p><div class="table"><a id="id425023"></a><p class="title"><b>Table 19.2. Profile Diagnostics</b></p><div class="table-contents"><table summary="Profile Diagnostics" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Group</th><th align="left">Flag</th><th align="left">Benefit</th><th align="left">Cost</th><th align="left">Freq.</th><th align="left">Implemented</th><td class="auto-generated"> </td></tr></thead><tbody><tr><td align="left"><a class="ulink" href="#manual.ext.profile_mode.analysis.containers" target="_top">
CONTAINERS</a></td><td align="left"><a class="ulink" href="#manual.ext.profile_mode.analysis.hashtable_too_small" target="_top">
HASHTABLE_TOO_SMALL</a></td><td align="left">10</td><td align="left">1</td><td align="left"> </td><td align="left">10</td><td align="left">yes</td></tr><tr><td align="left"> </td><td align="left"><a class="ulink" href="#manual.ext.profile_mode.analysis.hashtable_too_large" target="_top">
HASHTABLE_TOO_LARGE</a></td><td align="left">5</td><td align="left">1</td><td align="left"> </td><td align="left">10</td><td align="left">yes</td></tr><tr><td align="left"> </td><td align="left"><a class="ulink" href="#manual.ext.profile_mode.analysis.inefficient_hash" target="_top">
@ -57,22 +57,22 @@ advice sample
<code class="code">_GLIBCXX_PROFILE_CONTAINERS</code>.
</p><div class="sect3" title="Hashtable Too Small"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.hashtable_too_small"></a>Hashtable Too Small</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_HASHTABLE_TOO_SMALL</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables with many
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables with many
rehash operations, small construction size and large destruction size.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Rehash is very expensive.
Read content, follow chains within bucket, evaluate hash function, place at
new location in different order.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> 36%.
Code similar to example below.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
Set initial size to N at construction site S.
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span>
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span>
<code class="code">unordered_set, unordered_map</code> constructor, destructor, rehash.
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
For each dynamic instance of <code class="code">unordered_[multi]set|map</code>,
record initial size and call context of the constructor.
Record size increase, if any, after each relevant operation such as insert.
Record the estimated rehash cost.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Number of individual rehash operations * cost per rehash.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Number of individual rehash operations * cost per rehash.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 unordered_set&lt;int&gt; us;
2 for (int k = 0; k &lt; 1000000; ++k) {
@ -89,16 +89,16 @@ foo.cc:1: advice: Changing initial unordered_set size from 10 to 1000000 saves 1
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Save memory, which
is good in itself and may also improve memory reference performance through
fewer cache and TLB misses.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> unknown.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
Set initial size to N at construction site S.
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span>
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span>
<code class="code">unordered_set, unordered_map</code> constructor, destructor, rehash.
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
For each dynamic instance of <code class="code">unordered_[multi]set|map</code>,
record initial size and call context of the constructor, and correlate it
with its size at destruction time.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Number of iteration operations + memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Number of iteration operations + memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 vector&lt;unordered_set&lt;int&gt;&gt; v(100000, unordered_set&lt;int&gt;(100)) ;
2 for (int k = 0; k &lt; 100000; ++k) {
@ -114,7 +114,7 @@ bytes of memory and M iteration steps.
<code class="code">_GLIBCXX_PROFILE_INEFFICIENT_HASH</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect hashtables with polarized
distribution.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> A non-uniform
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> A non-uniform
distribution may lead to long chains, thus possibly increasing complexity
by a factor up to the number of elements.
</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span> factor up
@ -128,7 +128,7 @@ bytes of memory and M iteration steps.
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
Count the exact number of link traversals.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Total number of links traversed.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Total number of links traversed.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
class dumb_hash {
public:
@ -143,7 +143,7 @@ class dumb_hash {
</pre><p>
</p></li></ul></div></div><div class="sect3" title="Vector Too Small"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_too_small"></a>Vector Too Small</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_VECTOR_TOO_SMALL</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span>Detect vectors with many
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span>Detect vectors with many
resize operations, small construction size and large destruction size..
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>Resizing can be expensive.
Copying large amounts of data takes time. Resizing many small vectors may
@ -153,17 +153,17 @@ class dumb_hash {
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
For each dynamic instance of <code class="code">vector</code>,
record initial size and call context of the constructor.
Record size increase, if any, after each relevant operation such as
Record size increase, if any, after each relevant operation such as
<code class="code">push_back</code>. Record the estimated resize cost.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Total number of words copied * time to copy a word.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Total number of words copied * time to copy a word.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 vector&lt;int&gt; v;
2 for (int k = 0; k &lt; 1000000; ++k) {
3 v.push_back(k);
4 }
foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves
foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves
copying 4000000 bytes and 20 memory allocations and deallocations.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="Vector Too Large"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_too_large"></a>Vector Too Large</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
@ -180,7 +180,7 @@ copying 4000000 bytes and 20 memory allocations and deallocations.
For each dynamic instance of <code class="code">vector</code>,
record initial size and call context of the constructor, and correlate it
with its size at destruction time.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Total amount of memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Total amount of memory saved.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 vector&lt;vector&lt;int&gt;&gt; v(100000, vector&lt;int&gt;(100)) ;
2 for (int k = 0; k &lt; 100000; ++k) {
@ -194,20 +194,20 @@ bytes of memory and may reduce the number of cache and TLB misses.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="Vector to Hashtable"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_to_hashtable"></a>Vector to Hashtable</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_VECTOR_TO_HASHTABLE</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of
<code class="code">vector</code> that can be substituted with <code class="code">unordered_set</code>
to reduce execution time.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
Linear search in a vector is very expensive, whereas searching in a hashtable
is very quick.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>factor up
to container size.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace
<code class="code">vector</code> with <code class="code">unordered_set</code> at site S.
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">vector</code>
operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
For each dynamic instance of <code class="code">vector</code>,
record call context of the constructor. Issue the advice only if the
only methods called on this <code class="code">vector</code> are <code class="code">push_back</code>,
only methods called on this <code class="code">vector</code> are <code class="code">push_back</code>,
<code class="code">insert</code> and <code class="code">find</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Cost(vector::push_back) + cost(vector::insert) + cost(find, vector) -
@ -225,18 +225,18 @@ comparisons.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="Hashtable to Vector"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.hashtable_to_vector"></a>Hashtable to Vector</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_HASHTABLE_TO_VECTOR</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect uses of
<code class="code">unordered_set</code> that can be substituted with <code class="code">vector</code>
to reduce execution time.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
Hashtable iterator is slower than vector iterator.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>95%.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>Replace
<code class="code">unordered_set</code> with <code class="code">vector</code> at site S.
</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span><code class="code">unordered_set</code>
operations and access methods.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
For each dynamic instance of <code class="code">unordered_set</code>,
record call context of the constructor. Issue the advice only if the
number of <code class="code">find</code>, <code class="code">insert</code> and <code class="code">[]</code>
number of <code class="code">find</code>, <code class="code">insert</code> and <code class="code">[]</code>
operations on this <code class="code">unordered_set</code> are small relative to the
number of elements, and methods <code class="code">begin</code> or <code class="code">end</code>
are invoked (suggesting iteration).</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
@ -254,11 +254,11 @@ indirections and may achieve better data locality.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="Vector to List"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.vector_to_list"></a>Vector to List</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_VECTOR_TO_LIST</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
<code class="code">vector</code> could be substituted with <code class="code">list</code> for
better performance.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
Inserting in the middle of a vector is expensive compared to inserting in a
Inserting in the middle of a vector is expensive compared to inserting in a
list.
</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>factor up to
container size.
@ -272,19 +272,19 @@ indirections and may achieve better data locality.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
(Sum(cost(vector::method)) - Sum(cost(list::method)), for
method in [push_back, insert, erase])
+ (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
+ (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 vector&lt;int&gt; v;
2 for (int i = 0; i &lt; 10000; ++i) {
3 v.insert(v.begin(), i);
4 }
foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000
foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000
operations.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="List to Vector"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.list_to_vector"></a>List to Vector</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_LIST_TO_VECTOR</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
<code class="code">list</code> could be substituted with <code class="code">vector</code> for
better performance.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
@ -297,7 +297,7 @@ operations.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
(Sum(cost(vector::method)) - Sum(cost(list::method)), for
method in [push_back, insert, erase])
+ (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
+ (Cost(iterate vector) - Cost(iterate list))</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 list&lt;int&gt; l;
...
@ -311,7 +311,7 @@ memory references.
</pre><p>
</p></li></ul></div></div><div class="sect3" title="List to Forward List (Slist)"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.list_to_slist"></a>List to Forward List (Slist)</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_LIST_TO_SLIST</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where
<code class="code">list</code> could be substituted with <code class="code">forward_list</code> for
better performance.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
@ -328,7 +328,7 @@ memory references.
Issue the advice if there are no <code class="code">backwards</code> traversals
or insertion before a given node.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Always true.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
Always true.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 list&lt;int&gt; l;
...
@ -344,7 +344,7 @@ foo.cc:1: advice: Change "list" to "forward_list".
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect cases where ordered
associative containers can be replaced with unordered ones.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
Insert and search are quicker in a hashtable than in
Insert and search are quicker in a hashtable than in
a red-black tree.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>52%.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
Replace set with unordered_set at site S.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span>
@ -374,9 +374,9 @@ foo.cc:1: advice: Change "list" to "forward_list".
performance based on actual input. For instance, advise Radix Sort over
Quick Sort for a particular call context.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
See papers:
See papers:
<a class="ulink" href="http://portal.acm.org/citation.cfm?doid=1065944.1065981" target="_top">
A framework for adaptive algorithm selection in STAPL</a> and
A framework for adaptive algorithm selection in STAPL</a> and
<a class="ulink" href="http://ieeexplore.ieee.org/search/wrapper.jsp?arnumber=4228227" target="_top">
Optimizing Sorting with Machine Learning Algorithms</a>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>60%.
@ -384,7 +384,7 @@ foo.cc:1: advice: Change "list" to "forward_list".
at site S from X Sort to Y Sort.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> <code class="code">sort</code>
algorithm.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
Issue the advice if the cost model tells us that another sort algorithm
would do better on this input. Requires us to know what algorithm we
would do better on this input. Requires us to know what algorithm we
are using in our sort implementation in release mode.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Runtime(algo) for algo in [radix, quick, merge, ...]</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
@ -399,13 +399,13 @@ foo.cc:1: advice: Change "list" to "forward_list".
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>
Indirect references are hard to predict and are very expensive when they
miss in caches.</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>25%.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Insert prefetch
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span> Insert prefetch
instruction.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Vector iterator and
access operator [].
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
First, get cache line size and page size from system.
Then record iterator dereference sequences for which the value is a pointer.
For each sequence within a container, issue a warning if successive pointer
For each sequence within a container, issue a warning if successive pointer
addresses are not within cache lines and do not form a linear pattern
(otherwise they may be prefetched by hardware).
If they also step across page boundaries, make the warning stronger.
@ -417,11 +417,11 @@ foo.cc:1: advice: Change "list" to "forward_list".
</p><p>
This analysis is a little oversimplified. A better cost model could be
created by understanding the capability of the hardware prefetcher.
This model could be trained automatically by running a set of synthetic
This model could be trained automatically by running a set of synthetic
cases.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Total distance between pointer values of successive elements in vectors
of pointers.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
of pointers.</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 int zero = 0;
2 vector&lt;int*&gt; v(10000000, &amp;zero);
@ -441,14 +441,14 @@ foo.cc:7: advice: Insert prefetch instruction.
with respect to their actual traversal patterns.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span>Allocation can be tuned
to a specific traversal pattern, to result in better data locality.
See paper:
See paper:
<a class="ulink" href="http://www.springerlink.com/content/8085744l00x72662/" target="_top">
Custom Memory Allocation for Free</a>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Sample runtime reduction:</em></span>30%.
</p></li><li class="listitem"><p><span class="emphasis"><em>Recommendation:</em></span>
High scatter score N for container built at site S.
Consider changing allocation sequence or choosing a structure conscious
allocator.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Methods of all
allocator.</p></li><li class="listitem"><p><span class="emphasis"><em>To instrument:</em></span> Methods of all
containers using linked structures.</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
First, get cache line size and page size from system.
Then record the number of successive elements that are on different line
@ -502,7 +502,7 @@ the allocation sequence or switching to a structure conscious allocator.
container member accesses. Issue advice for elements referenced by
multiple threads.
See paper: <a class="ulink" href="http://portal.acm.org/citation.cfm?id=207110.207148" target="_top">
The LRPD test: speculative run-time parallelization of loops with
The LRPD test: speculative run-time parallelization of loops with
privatization and reduction parallelization</a>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Number of accesses to elements referenced from multiple threads
@ -512,7 +512,7 @@ the allocation sequence or switching to a structure conscious allocator.
</p></li></ul></div></div><div class="sect3" title="False Sharing"><div class="titlepage"><div><div><h4 class="title"><a id="manual.ext.profile_mode.analysis.mthread.false_share"></a>False Sharing</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Switch:</em></span>
<code class="code">_GLIBCXX_PROFILE_FALSE_SHARING</code>.
</p></li><li class="listitem"><p><span class="emphasis"><em>Goal:</em></span> Detect elements in the
same container which share a cache line, are written by at least one
same container which share a cache line, are written by at least one
thread, and accessed by different threads.
</p></li><li class="listitem"><p><span class="emphasis"><em>Fundamentals:</em></span> Under these assumptions,
cache protocols require
@ -523,14 +523,14 @@ the allocation sequence or switching to a structure conscious allocator.
and iterators.
</p></li><li class="listitem"><p><span class="emphasis"><em>Analysis:</em></span>
First, get the cache line size.
For each shared container, record all the associated iterator dereferences
For each shared container, record all the associated iterator dereferences
and member access methods with the thread id. Compare the address lists
across threads to detect references in two different threads to the same
cache line. Issue a warning only if the ratio to total references is
significant. Do the same for iterator dereference values if they are
across threads to detect references in two different threads to the same
cache line. Issue a warning only if the ratio to total references is
significant. Do the same for iterator dereference values if they are
pointers.</p></li><li class="listitem"><p><span class="emphasis"><em>Cost model:</em></span>
Number of accesses to same cache line from different threads.
</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p></li><li class="listitem"><p><span class="emphasis"><em>Example:</em></span>
</p><pre class="programlisting">
1 vector&lt;int&gt; v(2, 0);
2 #pragma omp parallel for shared(v, SIZE) schedule(static, 1)
@ -539,7 +539,7 @@ the allocation sequence or switching to a structure conscious allocator.
5 }
OMP_NUM_THREADS=2 ./a.out
foo.cc:1: advice: Change container structure or padding to avoid false
foo.cc:1: advice: Change container structure or padding to avoid false
sharing in multithreaded access at foo.cc:4. Detected N shared cache lines.
</pre><p>
</p></li></ul></div></div></div><div class="sect2" title="Statistics"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.analysis.statistics"></a>Statistics</h3></div></div></div><p>
@ -555,4 +555,4 @@ sharing in multithreaded access at foo.cc:4. Detected N shared cache lines.
This diagnostic will not issue any advice, but it will print statistics for
each container construction site. The statistics will contain the cost
of each operation actually performed on the container.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Developer Information </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 33. Allocators</td></tr></table></div></body></html>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_allocators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Developer Information </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 20. Allocators</td></tr></table></div></body></html>

6
libstdc++-v3/doc/html/manual/bk01pt12ch34s02.html → libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html
View file

@ -1,6 +1,6 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_containers.html" title="Chapter 34. Containers" /><link rel="prev" href="ext_containers.html" title="Chapter 34. Containers" /><link rel="next" href="bk01pt12ch34s03.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="ext_containers.html">Prev</a> </td><th width="60%" align="center">Chapter 34. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch34s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="HP/SGI"><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>
<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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_containers.html" title="Chapter 21. Containers" /><link rel="prev" href="ext_containers.html" title="Chapter 21. Containers" /><link rel="next" href="bk01pt03ch21s03.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="ext_containers.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch21s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="HP/SGI"><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:
@ -26,7 +26,7 @@
</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
</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
@ -40,4 +40,4 @@
</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="ext_containers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch34s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. 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>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_containers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch21s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. 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>

4
libstdc++-v3/doc/html/manual/bk01pt12ch34s03.html → libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html
View file

@ -1,6 +1,6 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_containers.html" title="Chapter 34. Containers" /><link rel="prev" href="bk01pt12ch34s02.html" title="HP/SGI" /><link rel="next" href="ext_utilities.html" title="Chapter 35. 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="bk01pt12ch34s02.html">Prev</a> </td><th width="60%" align="center">Chapter 34. Containers</th><td width="20%" align="right"> <a accesskey="n" href="ext_utilities.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Deprecated HP/SGI"><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>
<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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_containers.html" title="Chapter 21. Containers" /><link rel="prev" href="bk01pt03ch21s02.html" title="HP/SGI" /><link rel="next" href="ext_utilities.html" title="Chapter 22. 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="bk01pt03ch21s02.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Containers</th><td width="20%" align="right"> <a accesskey="n" href="ext_utilities.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Deprecated HP/SGI"><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,
@ -47,4 +47,4 @@
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="bk01pt12ch34s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_utilities.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 35. Utilities</td></tr></table></div></body></html>
</p></blockquote></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch21s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ext_utilities.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 22. Utilities</td></tr></table></div></body></html>

6
libstdc++-v3/doc/html/manual/bk01pt12ch41s02.html → libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_concurrency.html" title="Chapter 41. Concurrency" /><link rel="prev" href="ext_concurrency.html" title="Chapter 41. Concurrency" /><link rel="next" href="bk01pt12ch41s03.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="ext_concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 41. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch41s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Implementation"><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" title="Using Builtin Atomic Functions"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.atomic_fallbacks"></a>Using Builtin Atomic Functions</h3></div></div></div><p>The functions for atomic operations described above are either
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_concurrency.html" title="Chapter 28. Concurrency" /><link rel="prev" href="ext_concurrency.html" title="Chapter 28. Concurrency" /><link rel="next" href="bk01pt03ch28s03.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="ext_concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 28. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch28s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Implementation"><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" title="Using Builtin Atomic Functions"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.impl.atomic_fallbacks"></a>Using Builtin 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,
@ -12,7 +12,7 @@ missing reference to <code class="code">__sync_fetch_and_add_4</code>.)
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>
</p><p>
If builtins are possible for bool-sized integral types,
<code class="code">_GLIBCXX_ATOMIC_BUILTINS_1</code> will be defined.
If builtins are possible for int-sized integral types,
@ -38,4 +38,4 @@ use this layer. More detail as to the specific interface can be found in the sou
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="ext_concurrency.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_concurrency.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch41s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 41. 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>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_concurrency.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_concurrency.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch28s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 28. 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>

7
libstdc++-v3/doc/html/manual/bk01pt12ch41s03.html → libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html
View file

@ -1,6 +1,6 @@
<?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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_concurrency.html" title="Chapter 41. Concurrency" /><link rel="prev" href="bk01pt12ch41s02.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="bk01pt12ch41s02.html">Prev</a> </td><th width="60%" align="center">Chapter 41. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Use"><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:
<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.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="ext_concurrency.html" title="Chapter 28. Concurrency" /><link rel="prev" href="bk01pt03ch28s02.html" title="Implementation" /><link rel="next" href="bk01pt04.html" title="Part IV.  Appendices" /></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="bk01pt03ch28s02.html">Prev</a> </td><th width="60%" align="center">Chapter 28. Concurrency</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt04.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Use"><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;
@ -31,7 +31,6 @@ the mutex as control moves out of this block.
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="bk01pt12ch41s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_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
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch28s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ext_concurrency.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt04.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"> Part IV. 
Appendices
</td></tr></table></div></body></html>

14
libstdc++-v3/doc/html/manual/bk01pt12pr03.html → libstdc++-v3/doc/html/manual/bk01pt03pr01.html
View file

@ -1,26 +1,26 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="ext_compile_checks.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. 
<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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="extensions.html" title="Part III.  Extensions" /><link rel="next" href="ext_compile_checks.html" title="Chapter 16. 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 III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr></table><hr /></div><div class="preface"><div class="titlepage"><div><div><h2 class="title"><a id="id684983"></a></h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr></table><hr /></div><div class="preface"><div class="titlepage"><div><div><h2 class="title"><a id="id433082"></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 class="orderedlist" type="1"><li class="listitem"><p>
Non-Standard means exactly that.
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...
treat them differently, or...
</p></li><li class="listitem"><p>
You should know how to access these headers properly.
</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="ext_compile_checks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part XII. 
You should know how to access these headers properly.
</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="ext_compile_checks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part III. 
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>
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. Compile Time Checks</td></tr></table></div></body></html>

21
libstdc++-v3/doc/html/manual/bk01pt04.html Normal file
View file

@ -0,0 +1,21 @@
<?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 IV.  Appendices</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt03ch28s03.html" title="Use" /><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">Part IV. 
Appendices
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch28s03.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="appendix_contributing.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part IV.  Appendices"><div class="titlepage"><div><div><h1 class="title"><a id="appendix"></a>Part IV. 
Appendices
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="appendix"><a href="appendix_contributing.html">A.
Contributing
</a></span></dt><dd><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="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="sect1"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="sect2"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="documentation_style.html">Documentation Style</a></span></dt><dd><dl><dt><span class="sect2"><a href="documentation_style.html#doc_style.doxygen">Doxygen</a></span></dt><dt><span class="sect2"><a href="documentation_style.html#doc_style.docbook">Docbook</a></span></dt><dt><span class="sect2"><a href="documentation_style.html#doc_style.combines">Combines</a></span></dt></dl></dd><dt><span class="sect1"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B.
Porting and Maintenance
</a></span></dt><dd><dl><dt><span class="sect1"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.map">Overview: What Comes from Where</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="sect2"><a href="appendix_porting.html#build_hacking.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="sect1"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="sect2"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="sect2"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="sect1"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="sect2"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="sect2"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="sect2"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="sect2"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dt><span class="sect2"><a href="test.html#test.special">Special Topics</a></span></dt></dl></dd><dt><span class="sect1"><a href="abi.html">ABI Policy and Guidelines</a></span></dt><dd><dl><dt><span class="sect2"><a href="abi.html#abi.cxx_interface">The C++ Interface</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.versioning">Versioning</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_allowed">Allowed Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.changes_no">Prohibited Changes</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.testing">Testing</a></span></dt><dt><span class="sect2"><a href="abi.html#abi.issues">Outstanding Issues</a></span></dt></dl></dd><dt><span class="sect1"><a href="api.html">API Evolution and Deprecation History</a></span></dt><dd><dl><dt><span class="sect2"><a href="api.html#api.rel_300"><code class="constant">3.0</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_310"><code class="constant">3.1</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_320"><code class="constant">3.2</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_330"><code class="constant">3.3</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_340"><code class="constant">3.4</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_400"><code class="constant">4.0</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_410"><code class="constant">4.1</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_420"><code class="constant">4.2</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_430"><code class="constant">4.3</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_440"><code class="constant">4.4</code></a></span></dt><dt><span class="sect2"><a href="api.html#api.rel_450"><code class="constant">4.5</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="backwards.html">Backwards Compatibility</a></span></dt><dd><dl><dt><span class="sect2"><a href="backwards.html#backwards.first">First</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.second">Second</a></span></dt><dt><span class="sect2"><a href="backwards.html#backwards.third">Third</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="appendix_free.html">C.
Free Software Needs Free Documentation
</a></span></dt><dt><span class="appendix"><a href="appendix_gpl.html">D.
<acronym class="acronym">GNU</acronym> General Public License version 3
</a></span></dt><dt><span class="appendix"><a href="appendix_gfdl.html">E. GNU Free Documentation License</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="bk01pt03ch28s03.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="appendix_contributing.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"> Appendix A. 
Contributing
</td></tr></table></div></body></html>

90
libstdc++-v3/doc/html/manual/bk01pt05ch13.html
View file

@ -1,90 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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 Sensitivity" /></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" title="Chapter 13. String Classes"><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 Sensitivity</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" title="Simple Transformations"><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 simple
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>(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 Sensitivity</td></tr></table></div></body></html>

40
libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html
View file

@ -1,40 +0,0 @@
<?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 Sensitivity</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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 Sensitivity</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" title="Case Sensitivity"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="strings.string.case"></a>Case Sensitivity</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">“<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>”</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/reports/tr21/tr21-5.html" 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>

57
libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html
View file

@ -1,57 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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 Sensitivity" /><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" title="Arbitrary Character Types"><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 Sensitivity </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>

79
libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html
View file

@ -1,79 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="Tokenizing"><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.
</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
<code class="code">istringstreams</code> 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>

16
libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html
View file

@ -1,16 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="Shrink to Fit"><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="link" href="../faq.html#faq.size_equals_capacity" title="7.8.">this FAQ
entry</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>

94
libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html
View file

@ -1,94 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="CString (MFC)"><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 class="itemizedlist" type="disc"><li class="listitem"><p>The Standard <code class="code">string</code> supports all the operations
that CString does, with three exceptions.
</p></li><li class="listitem"><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 class="listitem"><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 class="itemizedlist" type="disc"><li class="listitem"><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 class="listitem"><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 class="listitem"><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 class="listitem"><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>

39
libstdc++-v3/doc/html/manual/bk01pt08ch19.html
View file

@ -1,39 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="Chapter 19. Predefined"><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" title="Iterators vs. Pointers"><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>
The following
FAQ <a class="link" href="../faq.html#faq.iterator_as_pod" title="7.1.">entry</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>

86
libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html
View file

@ -1,86 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="One Past the End"><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 class="orderedlist" type="1"><li class="listitem"><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 class="listitem"><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 class="listitem"><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>

19
libstdc++-v3/doc/html/manual/bk01pt09ch20.html
View file

@ -1,19 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="home" 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" title="Chapter 20. Mutating"><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" title="swap"><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" title="Specializations"><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>

41
libstdc++-v3/doc/html/manual/bk01pt09pr02.html
View file

@ -1,41 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; algorithm&#10; " /><link rel="home" 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"><div class="titlepage"><div><div><h2 class="title"><a id="id638172"></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 class="orderedlist" type="1"><li class="listitem"><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 class="listitem"><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="link" href="containers.html" title="Part VII.  Containers">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="link" href="iterators.html" title="Part VIII.  Iterators">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>

19
libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html
View file

@ -1,19 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics_and_c.html" title="Chapter 23. Interacting with C" /><link rel="prev" href="numerics_and_c.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="numerics_and_c.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" title="C99"><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="numerics_and_c.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics_and_c.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>

77
libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html
View file

@ -1,77 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="streambufs.html" title="Chapter 25. Stream Buffers" /><link rel="prev" href="streambufs.html" title="Chapter 25. Stream Buffers" /><link rel="next" href="stringstreams.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="streambufs.html">Prev</a> </td><th width="60%" align="center">Chapter 25. Stream Buffers</th><td width="20%" align="right"> <a accesskey="n" href="stringstreams.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Buffering"><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="streambufs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="streambufs.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="stringstreams.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>

101
libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html
View file

@ -1,101 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="fstreams.html" title="Chapter 27. File Based Streams" /><link rel="prev" href="fstreams.html" title="Chapter 27. File Based Streams" /><link rel="next" href="io_and_c.html" title="Chapter 28. Interacting with C" /></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="fstreams.html">Prev</a> </td><th width="60%" align="center">Chapter 27. File Based Streams</th><td width="20%" align="right"> <a accesskey="n" href="io_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Binary Input and Output"><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"
covers a lot of ground), 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 class="itemizedlist" type="disc"><li class="listitem"><p><span class="quote">“<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>”</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 class="listitem"><p>
<span class="quote">“<span class="quote">Build the file structure in memory, then
<code class="code">mmap()</code> the file and copy the
structure.
</span>”</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 class="listitem"><p>
<span class="quote">“<span class="quote">Use streambufs, that's what they're there for.</span>”</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.
</p><p>
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/group/comp.std.c++/browse_thread/thread/f87b4abd7954a87/946a3eb9921e382d?q=comp.std.c%2B%2B+binary+iostream#946a3eb9921e382d" target="_top">this</a>
post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
</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></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fstreams.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="fstreams.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="io_and_c.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"> Chapter 28. Interacting with C</td></tr></table></div></body></html>

49
libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html
View file

@ -1,49 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io_and_c.html" title="Chapter 28. Interacting with C" /><link rel="prev" href="io_and_c.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="io_and_c.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" title="Performance"><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="io_and_c.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io_and_c.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>

24
libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html
View file

@ -1,24 +0,0 @@
<?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.75.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="home" 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" title="Using"><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" title="Using the Debug Mode"><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" title="Using a Specific Debug Container"><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="id705570"></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" /></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></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></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></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></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></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></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></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></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></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></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></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></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="id607020"></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" /></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></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></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></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></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></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>

270
libstdc++-v3/doc/html/manual/bugs.html
View file

@ -36,317 +36,317 @@
of style. Note that we usually do not make changes to the
code until an issue has reached <a class="ulink" href="../ext/lwg-active.html#DR" target="_top">DR</a> status.
</p><div class="variablelist"><dl><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#5" target="_top">5</a>:
<span class="emphasis"><em>string::compare specification questionable</em></span>
<span class="emphasis"><em>string::compare specification questionable</em></span>
</span></dt><dd><p>This should be two overloaded functions rather than a single function.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#17" target="_top">17</a>:
<span class="emphasis"><em>Bad bool parsing</em></span>
<span class="emphasis"><em>Bad bool parsing</em></span>
</span></dt><dd><p>Apparently extracting Boolean values was messed up...
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#19" target="_top">19</a>:
<span class="emphasis"><em>"Noconv" definition too vague</em></span>
<span class="emphasis"><em>"Noconv" definition too vague</em></span>
</span></dt><dd><p>If <code class="code">codecvt::do_in</code> returns <code class="code">noconv</code> there are
no changes to the values in <code class="code">[to, to_limit)</code>.
no changes to the values in <code class="code">[to, to_limit)</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#22" target="_top">22</a>:
<span class="emphasis"><em>Member open vs flags</em></span>
<span class="emphasis"><em>Member open vs flags</em></span>
</span></dt><dd><p>Re-opening a file stream does <span class="emphasis"><em>not</em></span> clear the state flags.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#23" target="_top">23</a>:
<span class="emphasis"><em>Num_get overflow result</em></span>
<span class="emphasis"><em>Num_get overflow result</em></span>
</span></dt><dd><p>Implement the proposed resolution.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#25" target="_top">25</a>:
<span class="emphasis"><em>String operator&lt;&lt; uses width() value wrong</em></span>
<span class="emphasis"><em>String operator&lt;&lt; uses width() value wrong</em></span>
</span></dt><dd><p>Padding issues.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#48" target="_top">48</a>:
<span class="emphasis"><em>Use of non-existent exception constructor</em></span>
<span class="emphasis"><em>Use of non-existent exception constructor</em></span>
</span></dt><dd><p>An instance of <code class="code">ios_base::failure</code> is constructed instead.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#49" target="_top">49</a>:
<span class="emphasis"><em>Underspecification of ios_base::sync_with_stdio</em></span>
<span class="emphasis"><em>Underspecification of ios_base::sync_with_stdio</em></span>
</span></dt><dd><p>The return type is the <span class="emphasis"><em>previous</em></span> state of synchronization.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#50" target="_top">50</a>:
<span class="emphasis"><em>Copy constructor and assignment operator of ios_base</em></span>
<span class="emphasis"><em>Copy constructor and assignment operator of ios_base</em></span>
</span></dt><dd><p>These members functions are declared <code class="code">private</code> and are
thus inaccessible. Specifying the correct semantics of
"copying stream state" was deemed too complicated.
thus inaccessible. Specifying the correct semantics of
"copying stream state" was deemed too complicated.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#60" target="_top">60</a>:
<span class="emphasis"><em>What is a formatted input function?</em></span>
<span class="emphasis"><em>What is a formatted input function?</em></span>
</span></dt><dd><p>This DR made many widespread changes to <code class="code">basic_istream</code>
and <code class="code">basic_ostream</code> all of which have been implemented.
and <code class="code">basic_ostream</code> all of which have been implemented.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#63" target="_top">63</a>:
<span class="emphasis"><em>Exception-handling policy for unformatted output</em></span>
<span class="emphasis"><em>Exception-handling policy for unformatted output</em></span>
</span></dt><dd><p>Make the policy consistent with that of formatted input, unformatted
input, and formatted output.
input, and formatted output.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#68" target="_top">68</a>:
<span class="emphasis"><em>Extractors for char* should store null at end</em></span>
<span class="emphasis"><em>Extractors for char* should store null at end</em></span>
</span></dt><dd><p>And they do now. An editing glitch in the last item in the list of
[27.6.1.2.3]/7.
[27.6.1.2.3]/7.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#74" target="_top">74</a>:
<span class="emphasis"><em>Garbled text for codecvt::do_max_length</em></span>
<span class="emphasis"><em>Garbled text for codecvt::do_max_length</em></span>
</span></dt><dd><p>The text of the standard was gibberish. Typos gone rampant.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#75" target="_top">75</a>:
<span class="emphasis"><em>Contradiction in codecvt::length's argument types</em></span>
<span class="emphasis"><em>Contradiction in codecvt::length's argument types</em></span>
</span></dt><dd><p>Change the first parameter to <code class="code">stateT&amp;</code> and implement
the new effects paragraph.
the new effects paragraph.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#83" target="_top">83</a>:
<span class="emphasis"><em>string::npos vs. string::max_size()</em></span>
<span class="emphasis"><em>string::npos vs. string::max_size()</em></span>
</span></dt><dd><p>Safety checks on the size of the string should test against
<code class="code">max_size()</code> rather than <code class="code">npos</code>.
<code class="code">max_size()</code> rather than <code class="code">npos</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#90" target="_top">90</a>:
<span class="emphasis"><em>Incorrect description of operator&gt;&gt; for strings</em></span>
<span class="emphasis"><em>Incorrect description of operator&gt;&gt; for strings</em></span>
</span></dt><dd><p>The effect contain <code class="code">isspace(c,getloc())</code> which must be
replaced by <code class="code">isspace(c,is.getloc())</code>.
replaced by <code class="code">isspace(c,is.getloc())</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#91" target="_top">91</a>:
<span class="emphasis"><em>Description of operator&gt;&gt; and getline() for string&lt;&gt;
<span class="emphasis"><em>Description of operator&gt;&gt; and getline() for string&lt;&gt;
might cause endless loop</em></span>
</span></dt><dd><p>They behave as a formatted input function and as an unformatted
input function, respectively (except that <code class="code">getline</code> is
input function, respectively (except that <code class="code">getline</code> is
not required to set <code class="code">gcount</code>).
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#103" target="_top">103</a>:
<span class="emphasis"><em>set::iterator is required to be modifiable, but this allows
<span class="emphasis"><em>set::iterator is required to be modifiable, but this allows
modification of keys.</em></span>
</span></dt><dd><p>For associative containers where the value type is the same as
the key type, both <code class="code">iterator</code> and <code class="code">const_iterator
the key type, both <code class="code">iterator</code> and <code class="code">const_iterator
</code> are constant iterators.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#109" target="_top">109</a>:
<span class="emphasis"><em>Missing binders for non-const sequence elements</em></span>
<span class="emphasis"><em>Missing binders for non-const sequence elements</em></span>
</span></dt><dd><p>The <code class="code">binder1st</code> and <code class="code">binder2nd</code> didn't have an
<code class="code">operator()</code> taking a non-const parameter.
<code class="code">operator()</code> taking a non-const parameter.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#110" target="_top">110</a>:
<span class="emphasis"><em>istreambuf_iterator::equal not const</em></span>
<span class="emphasis"><em>istreambuf_iterator::equal not const</em></span>
</span></dt><dd><p>This was not a const member function. Note that the DR says to
replace the function with a const one; we have instead provided an
overloaded version with identical contents.
replace the function with a const one; we have instead provided an
overloaded version with identical contents.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#117" target="_top">117</a>:
<span class="emphasis"><em>basic_ostream uses nonexistent num_put member functions</em></span>
<span class="emphasis"><em>basic_ostream uses nonexistent num_put member functions</em></span>
</span></dt><dd><p><code class="code">num_put::put()</code> was overloaded on the wrong types.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#118" target="_top">118</a>:
<span class="emphasis"><em>basic_istream uses nonexistent num_get member functions</em></span>
<span class="emphasis"><em>basic_istream uses nonexistent num_get member functions</em></span>
</span></dt><dd><p>Same as 117, but for <code class="code">num_get::get()</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#129" target="_top">129</a>:
<span class="emphasis"><em>Need error indication from seekp() and seekg()</em></span>
<span class="emphasis"><em>Need error indication from seekp() and seekg()</em></span>
</span></dt><dd><p>These functions set <code class="code">failbit</code> on error now.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#130" target="_top">130</a>:
<span class="emphasis"><em>Return type of container::erase(iterator) differs for associative containers</em></span>
</span></dt><dd><p>Make member <code class="code">erase</code> return iterator for <code class="code">set</code>, <code class="code">multiset</code>, <code class="code">map</code>, <code class="code">multimap</code>.
<span class="emphasis"><em>Return type of container::erase(iterator) differs for associative containers</em></span>
</span></dt><dd><p>Make member <code class="code">erase</code> return iterator for <code class="code">set</code>, <code class="code">multiset</code>, <code class="code">map</code>, <code class="code">multimap</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#136" target="_top">136</a>:
<span class="emphasis"><em>seekp, seekg setting wrong streams?</em></span>
<span class="emphasis"><em>seekp, seekg setting wrong streams?</em></span>
</span></dt><dd><p><code class="code">seekp</code> should only set the output stream, and
<code class="code">seekg</code> should only set the input stream.
<code class="code">seekg</code> should only set the input stream.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#167" target="_top">167</a>:
<span class="emphasis"><em>Improper use of traits_type::length()</em></span>
<span class="emphasis"><em>Improper use of traits_type::length()</em></span>
</span></dt><dd><p><code class="code">op&lt;&lt;</code> with a <code class="code">const char*</code> was
calculating an incorrect number of characters to write.
calculating an incorrect number of characters to write.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#169" target="_top">169</a>:
<span class="emphasis"><em>Bad efficiency of overflow() mandated</em></span>
<span class="emphasis"><em>Bad efficiency of overflow() mandated</em></span>
</span></dt><dd><p>Grow efficiently the internal array object.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#171" target="_top">171</a>:
<span class="emphasis"><em>Strange seekpos() semantics due to joint position</em></span>
<span class="emphasis"><em>Strange seekpos() semantics due to joint position</em></span>
</span></dt><dd><p>Quite complex to summarize...
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#181" target="_top">181</a>:
<span class="emphasis"><em>make_pair() unintended behavior</em></span>
<span class="emphasis"><em>make_pair() unintended behavior</em></span>
</span></dt><dd><p>This function used to take its arguments as reference-to-const, now
it copies them (pass by value).
it copies them (pass by value).
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#195" target="_top">195</a>:
<span class="emphasis"><em>Should basic_istream::sentry's constructor ever set eofbit?</em></span>
<span class="emphasis"><em>Should basic_istream::sentry's constructor ever set eofbit?</em></span>
</span></dt><dd><p>Yes, it can, specifically if EOF is reached while skipping whitespace.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#211" target="_top">211</a>:
<span class="emphasis"><em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em></span>
<span class="emphasis"><em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em></span>
</span></dt><dd><p>If nothing is extracted into the string, <code class="code">op&gt;&gt;</code> now
sets <code class="code">failbit</code> (which can cause an exception, etc., etc.).
sets <code class="code">failbit</code> (which can cause an exception, etc., etc.).
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#214" target="_top">214</a>:
<span class="emphasis"><em>set::find() missing const overload</em></span>
<span class="emphasis"><em>set::find() missing const overload</em></span>
</span></dt><dd><p>Both <code class="code">set</code> and <code class="code">multiset</code> were missing
overloaded find, lower_bound, upper_bound, and equal_range functions
for const instances.
overloaded find, lower_bound, upper_bound, and equal_range functions
for const instances.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#231" target="_top">231</a>:
<span class="emphasis"><em>Precision in iostream?</em></span>
<span class="emphasis"><em>Precision in iostream?</em></span>
</span></dt><dd><p>For conversion from a floating-point type, <code class="code">str.precision()</code>
is specified in the conversion specification.
is specified in the conversion specification.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#233" target="_top">233</a>:
<span class="emphasis"><em>Insertion hints in associative containers</em></span>
<span class="emphasis"><em>Insertion hints in associative containers</em></span>
</span></dt><dd><p>Implement N1780, first check before then check after, insert as close
to hint as possible.
to hint as possible.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#235" target="_top">235</a>:
<span class="emphasis"><em>No specification of default ctor for reverse_iterator</em></span>
<span class="emphasis"><em>No specification of default ctor for reverse_iterator</em></span>
</span></dt><dd><p>The declaration of <code class="code">reverse_iterator</code> lists a default constructor.
However, no specification is given what this constructor should do.
However, no specification is given what this constructor should do.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#241" target="_top">241</a>:
<span class="emphasis"><em>Does unique_copy() require CopyConstructible and Assignable?</em></span>
<span class="emphasis"><em>Does unique_copy() require CopyConstructible and Assignable?</em></span>
</span></dt><dd><p>Add a helper for forward_iterator/output_iterator, fix the existing
one for input_iterator/output_iterator to not rely on Assignability.
one for input_iterator/output_iterator to not rely on Assignability.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#243" target="_top">243</a>:
<span class="emphasis"><em>get and getline when sentry reports failure</em></span>
<span class="emphasis"><em>get and getline when sentry reports failure</em></span>
</span></dt><dd><p>Store a null character only if the character array has a non-zero size.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#251" target="_top">251</a>:
<span class="emphasis"><em>basic_stringbuf missing allocator_type</em></span>
<span class="emphasis"><em>basic_stringbuf missing allocator_type</em></span>
</span></dt><dd><p>This nested typedef was originally not specified.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#253" target="_top">253</a>:
<span class="emphasis"><em>valarray helper functions are almost entirely useless</em></span>
<span class="emphasis"><em>valarray helper functions are almost entirely useless</em></span>
</span></dt><dd><p>Make the copy constructor and copy-assignment operator declarations
public in gslice_array, indirect_array, mask_array, slice_array; provide
public in gslice_array, indirect_array, mask_array, slice_array; provide
definitions.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#265" target="_top">265</a>:
<span class="emphasis"><em>std::pair::pair() effects overly restrictive</em></span>
<span class="emphasis"><em>std::pair::pair() effects overly restrictive</em></span>
</span></dt><dd><p>The default ctor would build its members from copies of temporaries;
now it simply uses their respective default ctors.
now it simply uses their respective default ctors.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#266" target="_top">266</a>:
<span class="emphasis"><em>bad_exception::~bad_exception() missing Effects clause</em></span>
<span class="emphasis"><em>bad_exception::~bad_exception() missing Effects clause</em></span>
</span></dt><dd><p>The <code class="code">bad_</code>* classes no longer have destructors (they
are trivial), since no description of them was ever given.
are trivial), since no description of them was ever given.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#271" target="_top">271</a>:
<span class="emphasis"><em>basic_iostream missing typedefs</em></span>
<span class="emphasis"><em>basic_iostream missing typedefs</em></span>
</span></dt><dd><p>The typedefs it inherits from its base classes can't be used, since
(for example) <code class="code">basic_iostream&lt;T&gt;::traits_type</code> is ambiguous.
(for example) <code class="code">basic_iostream&lt;T&gt;::traits_type</code> is ambiguous.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#275" target="_top">275</a>:
<span class="emphasis"><em>Wrong type in num_get::get() overloads</em></span>
<span class="emphasis"><em>Wrong type in num_get::get() overloads</em></span>
</span></dt><dd><p>Similar to 118.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#280" target="_top">280</a>:
<span class="emphasis"><em>Comparison of reverse_iterator to const reverse_iterator</em></span>
<span class="emphasis"><em>Comparison of reverse_iterator to const reverse_iterator</em></span>
</span></dt><dd><p>Add global functions with two template parameters.
(NB: not added for now a templated assignment operator)
(NB: not added for now a templated assignment operator)
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#292" target="_top">292</a>:
<span class="emphasis"><em>Effects of a.copyfmt (a)</em></span>
<span class="emphasis"><em>Effects of a.copyfmt (a)</em></span>
</span></dt><dd><p>If <code class="code">(this == &amp;rhs)</code> do nothing.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#300" target="_top">300</a>:
<span class="emphasis"><em>List::merge() specification incomplete</em></span>
<span class="emphasis"><em>List::merge() specification incomplete</em></span>
</span></dt><dd><p>If <code class="code">(this == &amp;x)</code> do nothing.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#303" target="_top">303</a>:
<span class="emphasis"><em>Bitset input operator underspecified</em></span>
</span></dt><dd><p>Basically, compare the input character to
<code class="code">is.widen(0)</code> and <code class="code">is.widen(1)</code>.
<span class="emphasis"><em>Bitset input operator underspecified</em></span>
</span></dt><dd><p>Basically, compare the input character to
<code class="code">is.widen(0)</code> and <code class="code">is.widen(1)</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#305" target="_top">305</a>:
<span class="emphasis"><em>Default behavior of codecvt&lt;wchar_t, char,
mbstate_t&gt;::length()</em></span>
</span></dt><dd><p>Do not specify what <code class="code">codecvt&lt;wchar_t, char,
mbstate_t&gt;::do_length</code> must return.
<span class="emphasis"><em>Default behavior of codecvt&lt;wchar_t, char,
mbstate_t&gt;::length()</em></span>
</span></dt><dd><p>Do not specify what <code class="code">codecvt&lt;wchar_t, char,
mbstate_t&gt;::do_length</code> must return.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#328" target="_top">328</a>:
<span class="emphasis"><em>Bad sprintf format modifier in
money_put&lt;&gt;::do_put()</em></span>
<span class="emphasis"><em>Bad sprintf format modifier in
money_put&lt;&gt;::do_put()</em></span>
</span></dt><dd><p>Change the format string to "%.0Lf".
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#365" target="_top">365</a>:
<span class="emphasis"><em>Lack of const-qualification in clause 27</em></span>
<span class="emphasis"><em>Lack of const-qualification in clause 27</em></span>
</span></dt><dd><p>Add const overloads of <code class="code">is_open</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#387" target="_top">387</a>:
<span class="emphasis"><em>std::complex over-encapsulated</em></span>
<span class="emphasis"><em>std::complex over-encapsulated</em></span>
</span></dt><dd><p>Add the <code class="code">real(T)</code> and <code class="code">imag(T)</code>
members; in C++0x mode, also adjust the existing
<code class="code">real()</code> and <code class="code">imag()</code> members and
free functions.
members; in C++0x mode, also adjust the existing
<code class="code">real()</code> and <code class="code">imag()</code> members and
free functions.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#389" target="_top">389</a>:
<span class="emphasis"><em>Const overload of valarray::operator[] returns
by value</em></span>
<span class="emphasis"><em>Const overload of valarray::operator[] returns
by value</em></span>
</span></dt><dd><p>Change it to return a <code class="code">const T&amp;</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#396" target="_top">396</a>:
<span class="emphasis"><em>what are characters zero and one</em></span>
<span class="emphasis"><em>what are characters zero and one</em></span>
</span></dt><dd><p>Implement the proposed resolution.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#402" target="_top">402</a>:
<span class="emphasis"><em>Wrong new expression in [some_]allocator::construct</em></span>
<span class="emphasis"><em>Wrong new expression in [some_]allocator::construct</em></span>
</span></dt><dd><p>Replace "new" with "::new".
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#408" target="_top">408</a>:
<span class="emphasis"><em>
Is vector&lt;reverse_iterator&lt;char*&gt; &gt; forbidden?
</em></span>
<span class="emphasis"><em>
Is vector&lt;reverse_iterator&lt;char*&gt; &gt; forbidden?
</em></span>
</span></dt><dd><p>Tweak the debug-mode checks in _Safe_iterator.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#409" target="_top">409</a>:
<span class="emphasis"><em>Closing an fstream should clear the error state</em></span>
<span class="emphasis"><em>Closing an fstream should clear the error state</em></span>
</span></dt><dd><p>Have <code class="code">open</code> clear the error flags.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-closed.html#431" target="_top">431</a>:
<span class="emphasis"><em>Swapping containers with unequal allocators</em></span>
<span class="emphasis"><em>Swapping containers with unequal allocators</em></span>
</span></dt><dd><p>Implement Option 3, as per N1599.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#432" target="_top">432</a>:
<span class="emphasis"><em>stringbuf::overflow() makes only one write position
<span class="emphasis"><em>stringbuf::overflow() makes only one write position
available</em></span>
</span></dt><dd><p>Implement the resolution, beyond DR 169.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#434" target="_top">434</a>:
<span class="emphasis"><em>bitset::to_string() hard to use</em></span>
<span class="emphasis"><em>bitset::to_string() hard to use</em></span>
</span></dt><dd><p>Add three overloads, taking fewer template arguments.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#438" target="_top">438</a>:
<span class="emphasis"><em>Ambiguity in the "do the right thing" clause</em></span>
<span class="emphasis"><em>Ambiguity in the "do the right thing" clause</em></span>
</span></dt><dd><p>Implement the resolution, basically cast less.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#453" target="_top">453</a>:
<span class="emphasis"><em>basic_stringbuf::seekoff need not always fail for an empty stream</em></span>
<span class="emphasis"><em>basic_stringbuf::seekoff need not always fail for an empty stream</em></span>
</span></dt><dd><p>Don't fail if the next pointer is null and newoff is zero.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#455" target="_top">455</a>:
<span class="emphasis"><em>cerr::tie() and wcerr::tie() are overspecified</em></span>
<span class="emphasis"><em>cerr::tie() and wcerr::tie() are overspecified</em></span>
</span></dt><dd><p>Initialize cerr tied to cout and wcerr tied to wcout.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#464" target="_top">464</a>:
<span class="emphasis"><em>Suggestion for new member functions in standard containers</em></span>
<span class="emphasis"><em>Suggestion for new member functions in standard containers</em></span>
</span></dt><dd><p>Add <code class="code">data()</code> to <code class="code">std::vector</code> and
<code class="code">at(const key_type&amp;)</code> to <code class="code">std::map</code>.
<code class="code">at(const key_type&amp;)</code> to <code class="code">std::map</code>.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#508" target="_top">508</a>:
<span class="emphasis"><em>Bad parameters for ranlux64_base_01</em></span>
<span class="emphasis"><em>Bad parameters for ranlux64_base_01</em></span>
</span></dt><dd><p>Fix the parameters.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-closed.html#512" target="_top">512</a>:
<span class="emphasis"><em>Seeding subtract_with_carry_01 from a single unsigned long</em></span>
<span class="emphasis"><em>Seeding subtract_with_carry_01 from a single unsigned long</em></span>
</span></dt><dd><p>Construct a <code class="code">linear_congruential</code> engine and seed with it.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-closed.html#526" target="_top">526</a>:
<span class="emphasis"><em>Is it undefined if a function in the standard changes in
<span class="emphasis"><em>Is it undefined if a function in the standard changes in
parameters?</em></span>
</span></dt><dd><p>Use &amp;value.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#538" target="_top">538</a>:
<span class="emphasis"><em>241 again: Does unique_copy() require CopyConstructible
<span class="emphasis"><em>241 again: Does unique_copy() require CopyConstructible
and Assignable?</em></span>
</span></dt><dd><p>In case of input_iterator/output_iterator rely on Assignability of
input_iterator' value_type.
input_iterator' value_type.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#539" target="_top">539</a>:
<span class="emphasis"><em>partial_sum and adjacent_difference should mention
requirements</em></span>
<span class="emphasis"><em>partial_sum and adjacent_difference should mention
requirements</em></span>
</span></dt><dd><p>We were almost doing the right thing, just use std::move
in adjacent_difference.
in adjacent_difference.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#541" target="_top">541</a>:
<span class="emphasis"><em>shared_ptr template assignment and void</em></span>
<span class="emphasis"><em>shared_ptr template assignment and void</em></span>
</span></dt><dd><p>Add an auto_ptr&lt;void&gt; specialization.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#543" target="_top">543</a>:
<span class="emphasis"><em>valarray slice default constructor</em></span>
<span class="emphasis"><em>valarray slice default constructor</em></span>
</span></dt><dd><p>Follow the straightforward proposed resolution.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#550" target="_top">550</a>:
<span class="emphasis"><em>What should the return type of pow(float,int) be?</em></span>
<span class="emphasis"><em>What should the return type of pow(float,int) be?</em></span>
</span></dt><dd><p>In C++0x mode, remove the pow(float,int), etc., signatures.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#586" target="_top">586</a>:
<span class="emphasis"><em>string inserter not a formatted function</em></span>
<span class="emphasis"><em>string inserter not a formatted function</em></span>
</span></dt><dd><p>Change it to be a formatted output function (i.e. catch exceptions).
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#596" target="_top">596</a>:
<span class="emphasis"><em>27.8.1.3 Table 112 omits "a+" and "a+b" modes</em></span>
<span class="emphasis"><em>27.8.1.3 Table 112 omits "a+" and "a+b" modes</em></span>
</span></dt><dd><p>Add the missing modes to fopen_mode.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#630" target="_top">630</a>:
<span class="emphasis"><em>arrays of valarray</em></span>
<span class="emphasis"><em>arrays of valarray</em></span>
</span></dt><dd><p>Implement the simple resolution.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#660" target="_top">660</a>:
<span class="emphasis"><em>Missing bitwise operations</em></span>
<span class="emphasis"><em>Missing bitwise operations</em></span>
</span></dt><dd><p>Add the missing operations.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#691" target="_top">691</a>:
<span class="emphasis"><em>const_local_iterator cbegin, cend missing from TR1</em></span>
<span class="emphasis"><em>const_local_iterator cbegin, cend missing from TR1</em></span>
</span></dt><dd><p>In C++0x mode add cbegin(size_type) and cend(size_type)
to the unordered containers.
to the unordered containers.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#693" target="_top">693</a>:
<span class="emphasis"><em>std::bitset::all() missing</em></span>
<span class="emphasis"><em>std::bitset::all() missing</em></span>
</span></dt><dd><p>Add it, consistently with the discussion.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#695" target="_top">695</a>:
<span class="emphasis"><em>ctype&lt;char&gt;::classic_table() not accessible</em></span>
<span class="emphasis"><em>ctype&lt;char&gt;::classic_table() not accessible</em></span>
</span></dt><dd><p>Make the member functions table and classic_table public.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#696" target="_top">696</a>:
<span class="emphasis"><em>istream::operator&gt;&gt;(int&amp;) broken</em></span>
<span class="emphasis"><em>istream::operator&gt;&gt;(int&amp;) broken</em></span>
</span></dt><dd><p>Implement the straightforward resolution.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#761" target="_top">761</a>:
<span class="emphasis"><em>unordered_map needs an at() member function</em></span>
<span class="emphasis"><em>unordered_map needs an at() member function</em></span>
</span></dt><dd><p>In C++0x mode, add at() and at() const.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#775" target="_top">775</a>:
<span class="emphasis"><em>Tuple indexing should be unsigned?</em></span>
<span class="emphasis"><em>Tuple indexing should be unsigned?</em></span>
</span></dt><dd><p>Implement the int -&gt; size_t replacements.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#776" target="_top">776</a>:
<span class="emphasis"><em>Undescribed assign function of std::array</em></span>
<span class="emphasis"><em>Undescribed assign function of std::array</em></span>
</span></dt><dd><p>In C++0x mode, remove assign, add fill.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#781" target="_top">781</a>:
<span class="emphasis"><em>std::complex should add missing C99 functions</em></span>
<span class="emphasis"><em>std::complex should add missing C99 functions</em></span>
</span></dt><dd><p>In C++0x mode, add std::proj.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#809" target="_top">809</a>:
<span class="emphasis"><em>std::swap should be overloaded for array types</em></span>
<span class="emphasis"><em>std::swap should be overloaded for array types</em></span>
</span></dt><dd><p>Add the overload.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#844" target="_top">844</a>:
<span class="emphasis"><em>complex pow return type is ambiguous</em></span>
<span class="emphasis"><em>complex pow return type is ambiguous</em></span>
</span></dt><dd><p>In C++0x mode, remove the pow(complex&lt;T&gt;, int) signature.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#853" target="_top">853</a>:
<span class="emphasis"><em>to_string needs updating with zero and one</em></span>
<span class="emphasis"><em>to_string needs updating with zero and one</em></span>
</span></dt><dd><p>Update / add the signatures.
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#865" target="_top">865</a>:
<span class="emphasis"><em>More algorithms that throw away information</em></span>
<span class="emphasis"><em>More algorithms that throw away information</em></span>
</span></dt><dd><p>The traditional HP / SGI return type and value is blessed
by the resolution of the DR.
by the resolution of the DR.
</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="license.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="status.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="setup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">License </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Setup</td></tr></table></div></body></html>

379
libstdc++-v3/doc/html/manual/codecvt.html
View file

@ -1,379 +0,0 @@
<?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>codecvt</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; codecvt&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="facets.html" title="Chapter 15. Facets aka Categories" /><link rel="prev" href="facets.html" title="Chapter 15. Facets aka Categories" /><link rel="next" href="messages.html" title="messages" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">codecvt</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="facets.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Facets aka Categories</th><td width="20%" align="right"> <a accesskey="n" href="messages.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="codecvt"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.facet.codecvt"></a>codecvt</h2></div></div></div><p>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
attempts to detail conversions between the implementation-defined wide
characters (hereafter referred to as wchar_t) and the standard type
char that is so beloved in classic <span class="quote">“<span class="quote">C</span>”</span> (which can now be
referred to as narrow characters.) This document attempts to describe
how the GNU libstdc++ implementation deals with the conversion between
wide and narrow characters, and also presents a framework for dealing
with the huge number of other encodings that iconv can convert,
including Unicode and UTF8. Design issues and requirements are
addressed, and examples of correct usage for both the required
specializations for wide and narrow characters and the
implementation-provided extended functionality are given.
</p><div class="sect2" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.req"></a>Requirements</h3></div></div></div><p>
Around page 425 of the C++ Standard, this charming heading comes into view:
</p><div class="blockquote"><blockquote class="blockquote"><p>
22.2.1.5 - Template class codecvt
</p></blockquote></div><p>
The text around the codecvt definition gives some clues:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-1- The class codecvt&lt;internT,externT,stateT&gt; is for use when
converting from one codeset to another, such as from wide characters
to multibyte characters, between wide character encodings such as
Unicode and EUC.
</em></span>
</p></blockquote></div><p>
Hmm. So, in some unspecified way, Unicode encodings and
translations between other character sets should be handled by this
class.
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-2- The stateT argument selects the pair of codesets being mapped between.
</em></span>
</p></blockquote></div><p>
Ah ha! Another clue...
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-3- The instantiations required in the Table ??
(lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and
codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
native character set. codecvt&lt;char,char,mbstate_t&gt; implements a
degenerate conversion; it does not convert at
all. codecvt&lt;wchar_t,char,mbstate_t&gt; converts between the native
character sets for tiny and wide characters. Instantiations on
mbstate_t perform conversion between encodings known to the library
implementor. Other encodings can be converted by specializing on a
user-defined stateT type. The stateT object can contain any state that
is useful to communicate to or from the specialized do_convert member.
</em></span>
</p></blockquote></div><p>
At this point, a couple points become clear:
</p><p>
One: The standard clearly implies that attempts to add non-required
(yet useful and widely used) conversions need to do so through the
third template parameter, stateT.</p><p>
Two: The required conversions, by specifying mbstate_t as the third
template parameter, imply an implementation strategy that is mostly
(or wholly) based on the underlying C library, and the functions
mcsrtombs and wcsrtombs in particular.</p></div><div class="sect2" title="Design"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.design"></a>Design</h3></div></div></div><div class="sect3" title="wchar_t Size"><div class="titlepage"><div><div><h4 class="title"><a id="codecvt.design.wchar_t_size"></a><span class="type">wchar_t</span> Size</h4></div></div></div><p>
The simple implementation detail of wchar_t's size seems to
repeatedly confound people. Many systems use a two byte,
unsigned integral type to represent wide characters, and use an
internal encoding of Unicode or UCS2. (See AIX, Microsoft NT,
Java, others.) Other systems, use a four byte, unsigned integral
type to represent wide characters, and use an internal encoding
of UCS4. (GNU/Linux systems using glibc, in particular.) The C
programming language (and thus C++) does not specify a specific
size for the type wchar_t.
</p><p>
Thus, portable C++ code cannot assume a byte size (or endianness) either.
</p></div><div class="sect3" title="Support for Unicode"><div class="titlepage"><div><div><h4 class="title"><a id="codecvt.design.unicode"></a>Support for Unicode</h4></div></div></div><p>
Probably the most frequently asked question about code conversion
is: "So dudes, what's the deal with Unicode strings?"
The dude part is optional, but apparently the usefulness of
Unicode strings is pretty widely appreciated. Sadly, this specific
encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10,
etc etc etc) are not mentioned in the C++ standard.
</p><p>
A couple of comments:
</p><p>
The thought that all one needs to convert between two arbitrary
codesets is two types and some kind of state argument is
unfortunate. In particular, encodings may be stateless. The naming
of the third parameter as stateT is unfortunate, as what is really
needed is some kind of generalized type that accounts for the
issues that abstract encodings will need. The minimum information
that is required includes:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Identifiers for each of the codesets involved in the
conversion. For example, using the iconv family of functions
from the Single Unix Specification (what used to be called
X/Open) hosted on the GNU/Linux operating system allows
bi-directional mapping between far more than the following
tantalizing possibilities:
</p><p>
(An edited list taken from <code class="code">`iconv --list`</code> on a
Red Hat 6.2/Intel system:
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16).
</pre></blockquote></div><p>
For iconv-based implementations, string literals for each of the
encodings (i.e. "UCS-2" and "UTF-8") are necessary,
although for other,
non-iconv implementations a table of enumerated values or some other
mechanism may be required.
</p></li><li class="listitem"><p>
Maximum length of the identifying string literal.
</p></li><li class="listitem"><p>
Some encodings require explicit endian-ness. As such, some kind
of endian marker or other byte-order marker will be necessary. See
"Footnotes for C/C++ developers" in Haible for more information on
UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
however implementations, most notably Microsoft, vary.)
</p></li><li class="listitem"><p>
Types representing the conversion state, for conversions involving
the machinery in the "C" library, or the conversion descriptor, for
conversions using iconv (such as the type iconv_t.) Note that the
conversion descriptor encodes more information than a simple encoding
state type.
</p></li><li class="listitem"><p>
Conversion descriptors for both directions of encoding. (i.e., both
UCS-2 to UTF-8 and UTF-8 to UCS-2.)
</p></li><li class="listitem"><p>
Something to indicate if the conversion requested if valid.
</p></li><li class="listitem"><p>
Something to represent if the conversion descriptors are valid.
</p></li><li class="listitem"><p>
Some way to enforce strict type checking on the internal and
external types. As part of this, the size of the internal and
external types will need to be known.
</p></li></ul></div></div><div class="sect3" title="Other Issues"><div class="titlepage"><div><div><h4 class="title"><a id="codecvt.design.issues"></a>Other Issues</h4></div></div></div><p>
In addition, multi-threaded and multi-locale environments also impact
the design and requirements for code conversions. In particular, they
affect the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt;
when implemented using standard "C" functions.
</p><p>
Three problems arise, one big, one of medium importance, and one small.
</p><p>
First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue.
</p><p>
Of medium concern, in the grand scope of things, is that the functions
used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise
incorrect. Yikes!
</p><p>
The last, and fundamental problem, is the assumption of a global
locale for all the "C" functions referenced above. For something like
C++ iostreams (where codecvt is explicitly used) the notion of
multiple locales is fundamental. In practice, most users may not run
into this limitation. However, as a quality of implementation issue,
the GNU C++ library would like to offer a solution that allows
multiple locales and or simultaneous usage with computationally
correct results. In short, libstdc++ is trying to offer, as an
option, a high-quality implementation, damn the additional complexity!
</p><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></div></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.impl"></a>Implementation</h3></div></div></div><p>
The two required specializations are implemented as follows:
</p><p>
<code class="code">
codecvt&lt;char, char, mbstate_t&gt;
</code>
</p><p>
This is a degenerate (i.e., does nothing) specialization. Implementing
this was a piece of cake.
</p><p>
<code class="code">
codecvt&lt;char, wchar_t, mbstate_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. As such, libstdc++ implements a partial specialization
of the codecvt class with and iconv wrapper class, encoding_state as the
third template parameter.
</p><p>
This implementation should be standards conformant. First of all, the
standard explicitly points out that instantiations on the third
template parameter, stateT, are the proper way to implement
non-required conversions. Second of all, the standard says (in Chapter
17) that partial specializations of required classes are a-ok. Third
of all, the requirements for the stateT type elsewhere in the standard
(see 21.1.2 traits typedefs) only indicate that this type be copy
constructible.
</p><p>
As such, the type encoding_state is defined as a non-templatized, POD
type to be used as the third type of a codecvt instantiation. This
type is just a wrapper class for iconv, and provides an easy interface
to iconv functionality.
</p><p>
There are two constructors for encoding_state:
</p><p>
<code class="code">
encoding_state() : __in_desc(0), __out_desc(0)
</code>
</p><p>
This default constructor sets the internal encoding to some default
(currently UCS4) and the external encoding to whatever is returned by
nl_langinfo(CODESET).
</p><p>
<code class="code">
encoding_state(const char* __int, const char* __ext)
</code>
</p><p>
This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for
either argument.
</p><p>
One of the issues with iconv is that the string literals identifying
conversions are not standardized. Because of this, the thought of
mandating and or enforcing some set of pre-determined valid
identifiers seems iffy: thus, a more practical (and non-migraine
inducing) strategy was implemented: end-users can specify any string
(subject to a pre-determined length qualifier, currently 32 bytes) for
encodings. It is up to the user to make sure that these strings are
valid on the target system.
</p><p>
<code class="code">
void
_M_init()
</code>
</p><p>
Strangely enough, this member function attempts to open conversion
descriptors for a given encoding_state object. If the conversion
descriptors are not valid, the conversion descriptors returned will
not be valid and the resulting calls to the codecvt conversion
functions will return error.
</p><p>
<code class="code">
bool
_M_good()
</code>
</p><p>
Provides a way to see if the given encoding_state object has been
properly initialized. If the string literals describing the desired
internal and external encoding are not valid, initialization will
fail, and this will return false. If the internal and external
encodings are valid, but iconv_open could not allocate conversion
descriptors, this will also return false. Otherwise, the object is
ready to convert and will return true.
</p><p>
<code class="code">
encoding_state(const encoding_state&amp;)
</code>
</p><p>
As iconv allocates memory and sets up conversion descriptors, the copy
constructor can only copy the member data pertaining to the internal
and external code conversions, and not the conversion descriptors
themselves.
</p><p>
Definitions for all the required codecvt member functions are provided
for this specialization, and usage of codecvt&lt;internal character type,
external character type, encoding_state&gt; is consistent with other
codecvt usage.
</p></div><div class="sect2" title="Use"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.use"></a>Use</h3></div></div></div><p>A conversions involving string literal.</p><pre class="programlisting">
typedef codecvt_base::result result;
typedef unsigned short unicode_t;
typedef unicode_t int_type;
typedef char ext_type;
typedef encoding_state state_type;
typedef codecvt&lt;int_type, ext_type, state_type&gt; unicode_codecvt;
const ext_type* e_lit = "black pearl jasmine tea";
int size = strlen(e_lit);
int_type i_lit_base[24] =
{ 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
25856, 24832, 2560
};
const int_type* i_lit = i_lit_base;
const ext_type* efrom_next;
const int_type* ifrom_next;
ext_type* e_arr = new ext_type[size + 1];
ext_type* eto_next;
int_type* i_arr = new int_type[size + 1];
int_type* ito_next;
// construct a locale object with the specialized facet.
locale loc(locale::classic(), new unicode_codecvt);
// sanity check the constructed locale has the specialized facet.
VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
// convert between const char* and unicode strings
unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
initialize_state(state01);
result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
i_arr, i_arr + size, ito_next);
VERIFY( r1 == codecvt_base::ok );
VERIFY( !int_traits::compare(i_arr, i_lit, size) );
VERIFY( efrom_next == e_lit + size );
VERIFY( ito_next == i_arr + size );
</pre></div><div class="sect2" title="Future"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
a. things that are sketchy, or remain unimplemented:
do_encoding, max_length and length member functions
are only weakly implemented. I have no idea how to do
this correctly, and in a generic manner. Nathan?
</p></li><li class="listitem"><p>
b. conversions involving std::string
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
how should operators != and == work for string of
different/same encoding?
</p></li><li class="listitem"><p>
what is equal? A byte by byte comparison or an
encoding then byte comparison?
</p></li><li class="listitem"><p>
conversions between narrow, wide, and unicode strings
</p></li></ul></div></li><li class="listitem"><p>
c. conversions involving std::filebuf and std::ostream
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
how to initialize the state object in a
standards-conformant manner?
</p></li><li class="listitem"><p>
how to synchronize the "C" and "C++"
conversion information?
</p></li><li class="listitem"><p>
wchar_t/char internal buffers and conversions between
internal/external buffers?
</p></li></ul></div></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.codecvt.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id686680"></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" title="Correspondence"><a id="id693504"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id612636"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id612655"></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" title="The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)"><a id="id699030"></a><p><span class="title"><i>
The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
</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.unix.org/version3/ieee_std.html" target="_top">
</a>
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id699056"></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" title="Standard C++ IOStreams and Locales"><a id="id698403"></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 class="biblioentry" title="A brief description of Normative Addendum 1"><a id="id661653"></a><p><span class="title"><i>
A brief description of Normative Addendum 1
</i>. </span><span class="author"><span class="firstname">Clive</span> <span class="surname">Feather</span>. </span><span class="pagenums">Extended Character Sets. </span><span class="biblioid">
<a class="ulink" href="http://www.lysator.liu.se/c/na1.html" target="_top">
</a>
. </span></p></div><div class="biblioentry" title="The Unicode HOWTO"><a id="id661684"></a><p><span class="title"><i>
The Unicode HOWTO
</i>. </span><span class="author"><span class="firstname">Bruno</span> <span class="surname">Haible</span>. </span><span class="biblioid">
<a class="ulink" href="http://tldp.org/HOWTO/Unicode-HOWTO.html" target="_top">
</a>
. </span></p></div><div class="biblioentry" title="UTF-8 and Unicode FAQ for Unix/Linux"><a id="id662453"></a><p><span class="title"><i>
UTF-8 and Unicode FAQ for Unix/Linux
</i>. </span><span class="author"><span class="firstname">Markus</span> <span class="surname">Khun</span>. </span><span class="biblioid">
<a class="ulink" href="http://www.cl.cam.ac.uk/~mgk25/unicode.html" target="_top">
</a>
. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="facets.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="facets.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="messages.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. Facets aka Categories </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> messages</td></tr></table></div></body></html>

25
libstdc++-v3/doc/html/manual/complex.html
View file

@ -1,25 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="generalized_numeric_operations.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="generalized_numeric_operations.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 21. Complex"><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="complex.html#numerics.complex.processing">complex Processing</a></span></dt></dl></div><p>
</p><div class="sect1" title="complex Processing"><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="generalized_numeric_operations.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>

42
libstdc++-v3/doc/html/manual/concurrency.html Normal file
View file

@ -0,0 +1,42 @@
<?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.  Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; , &#10; mutex&#10; , &#10; thread&#10; , &#10; future&#10; , &#10; condition_variable&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="atomics.html" title="Chapter 14.  Atomics" /><link rel="next" href="extensions.html" title="Part III.  Extensions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 15. 
Concurrency
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="atomics.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 15.  Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="std.concurrency"></a>Chapter 15. 
Concurrency
<a id="id397655" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="concurrency.html#std.concurrency.api">API Reference</a></span></dt></dl></div><p>
Facilities for concurrent operation, and control thereof.
</p><div class="sect1" title="API Reference"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.concurrency.api"></a>API Reference</h2></div></div></div><p>
All items are declared in one of four standard header files.
</p><p>
In header <code class="filename">mutex</code>, class
template <code class="classname">mutex</code> and variants,
class <code class="classname">once_flag</code>, and class
template <code class="classname">unique_lock</code>.
</p><p>
In header <code class="filename">condition_variable</code>,
classes <code class="classname">condition_variable</code>
and <code class="classname">condition_variable_any</code>.
</p><p>
In header <code class="filename">thread</code>,
class <code class="classname">thread</code> and
namespace <code class="code">this_thread</code>.
</p><p>
In header <code class="filename">future</code>, class
template <code class="classname">future</code> and class
template <code class="classname">shared_future</code>, class
template <code class="classname">promise</code>,
and <code class="classname">packaged_task</code>.
</p><p>
Full API details.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="atomics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="extensions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. 
Atomics
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part III. 
Extensions
</td></tr></table></div></body></html>

258
libstdc++-v3/doc/html/manual/configure.html
View file

@ -19,43 +19,43 @@
available for a given set of libstdc++ sources is to go to the
source directory and then type:<span class="command"><strong>./configure --help</strong></span>.
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">--enable-multilib</code>[default]</span></dt><dd><p>This is part of the generic multilib support for building cross
compilers. As such, targets like "powerpc-elf" will have
libstdc++ built many different ways: "-msoft-float"
and not, etc. A different libstdc++ will be built for each of
the different multilib versions. This option is on by default.
compilers. As such, targets like "powerpc-elf" will have
libstdc++ built many different ways: "-msoft-float"
and not, etc. A different libstdc++ will be built for each of
the different multilib versions. This option is on by default.
</p></dd><dt><span class="term"><code class="code">--enable-sjlj-exceptions</code></span></dt><dd><p>Forces old, set-jump/long-jump exception handling model. If
at all possible, the new, frame unwinding exception handling routines
should be used instead, as they significantly reduce both
runtime memory usage and executable size. This option can
change the library ABI.
at all possible, the new, frame unwinding exception handling routines
should be used instead, as they significantly reduce both
runtime memory usage and executable size. This option can
change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-version-specific-runtime-libs</code></span></dt><dd><p>Specify that run-time libraries should be installed in the
compiler-specific subdirectory (i.e.,
<code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
instead of <code class="code">${libdir}</code>. This option is useful if you
intend to use several versions of gcc in parallel. In addition,
libstdc++'s include files will be installed in
<code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
unless you also specify
compiler-specific subdirectory (i.e.,
<code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
instead of <code class="code">${libdir}</code>. This option is useful if you
intend to use several versions of gcc in parallel. In addition,
libstdc++'s include files will be installed in
<code class="code">${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
unless you also specify
<code class="literal">--with-gxx-include-dir=<code class="filename">dirname</code></code> during configuration.
</p></dd><dt><span class="term"><code class="code">--with-gxx-include-dir=&lt;include-files dir&gt;</code></span></dt><dd><p>Adds support for named libstdc++ include directory. For instance,
the following puts all the libstdc++ headers into a directory
called "4.4-20090404" instead of the usual
"c++/(version)".
the following puts all the libstdc++ headers into a directory
called "4.4-20090404" instead of the usual
"c++/(version)".
</p><pre class="programlisting">
--with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</pre></dd><dt><span class="term"><code class="code">--enable-cstdio</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-cstdio=stdio'</code>
(described next).
(described next).
</p></dd><dt><span class="term"><code class="code">--enable-cstdio=OPTION</code></span></dt><dd><p>Select a target-specific I/O package. At the moment, the only
choice is to use 'stdio', a generic "C" abstraction.
The default is 'stdio'. This option can change the library ABI.
choice is to use 'stdio', a generic "C" abstraction.
The default is 'stdio'. This option can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-clocale</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-clocale=generic'</code>
(described next).
(described next).
</p></dd><dt><span class="term"><code class="code">--enable-clocale=OPTION</code></span></dt><dd><p>Select a target-specific underlying locale package. The
choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
(IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
'gnu' to specify a model based on functionality from the GNU C
library (langinfo/iconv/gettext) (from <a class="ulink" href="http://sources.redhat.com/glibc/" target="_top">glibc</a>, the GNU C
library), or 'generic' to use a generic "C"
abstraction which consists of "C" locale info.
choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
(IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
'gnu' to specify a model based on functionality from the GNU C
library (langinfo/iconv/gettext) (from <a class="ulink" href="http://sources.redhat.com/glibc/" target="_top">glibc</a>, the GNU C
library), or 'generic' to use a generic "C"
abstraction which consists of "C" locale info.
</p><p>If not explicitly specified, the configure proccess tries
to guess the most suitable package from the choices above. The
default is 'generic'. On glibc-based systems of sufficient
@ -63,124 +63,124 @@
FR locale data), 'gnu' is automatically selected. This option
can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-allocator</code></span></dt><dd><p>This is an abbreviated form of
<code class="code">'--enable-libstdcxx-allocator=auto'</code> (described
next).
<code class="code">'--enable-libstdcxx-allocator=auto'</code> (described
next).
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-allocator=OPTION </code></span></dt><dd><p>Select a target-specific underlying std::allocator. The
choices are 'new' to specify a wrapper for new, 'malloc' to
specify a wrapper for malloc, 'mt' for a fixed power of two allocator,
choices are 'new' to specify a wrapper for new, 'malloc' to
specify a wrapper for malloc, 'mt' for a fixed power of two allocator,
'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator.
See this page for more information on allocator
<a class="link" href="memory.html#allocator.ext" title="Extension Allocators">extensions</a>. This option
can change the library ABI.
See this page for more information on allocator
<a class="link" href="memory.html#allocator.ext" title="Extension Allocators">extensions</a>. This option
can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-cheaders=OPTION</code></span></dt><dd><p>This allows the user to define the approach taken for C header
compatibility with C++. Options are c, c_std, and c_global.
These correspond to the source directory's include/c,
include/c_std, and include/c_global, and may also include
include/c_compatibility. The default is 'c_global'.
compatibility with C++. Options are c, c_std, and c_global.
These correspond to the source directory's include/c,
include/c_std, and include/c_global, and may also include
include/c_compatibility. The default is 'c_global'.
</p></dd><dt><span class="term"><code class="code">--enable-threads</code></span></dt><dd><p>This is an abbreviated form of <code class="code">'--enable-threads=yes'</code>
(described next).
(described next).
</p></dd><dt><span class="term"><code class="code">--enable-threads=OPTION</code></span></dt><dd><p>Select a threading library. A full description is
given in the
general <a class="ulink" href="http://gcc.gnu.org/install/configure.html" target="_top">compiler
configuration instructions</a>. This option can change the
library ABI.
given in the
general <a class="ulink" href="http://gcc.gnu.org/install/configure.html" target="_top">compiler
configuration instructions</a>. This option can change the
library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-debug</code></span></dt><dd><p>Build separate debug libraries in addition to what is normally built.
By default, the debug libraries are compiled with
<code class="code"> CXXFLAGS='-g3 -O0 -fno-inline'</code>
, are installed in <code class="code">${libdir}/debug</code>, and have the
same names and versioning information as the non-debug
libraries. This option is off by default.
By default, the debug libraries are compiled with
<code class="code"> CXXFLAGS='-g3 -O0 -fno-inline'</code>
, are installed in <code class="code">${libdir}/debug</code>, and have the
same names and versioning information as the non-debug
libraries. This option is off by default.
</p><p>Note this make command, executed in
the build directory, will do much the same thing, without the
configuration difference and without building everything twice:
<code class="code">make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
the build directory, will do much the same thing, without the
configuration difference and without building everything twice:
<code class="code">make CXXFLAGS='-g3 -O0 -fno-inline' all</code>
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-debug-flags=FLAGS</code></span></dt><dd><p>This option is only valid when <code class="code"> --enable-debug </code>
is also specified, and applies to the debug builds only. With
this option, you can pass a specific string of flags to the
compiler to use when building the debug versions of libstdc++.
FLAGS is a quoted string of options, like
is also specified, and applies to the debug builds only. With
this option, you can pass a specific string of flags to the
compiler to use when building the debug versions of libstdc++.
FLAGS is a quoted string of options, like
</p><pre class="programlisting">
--enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</pre></dd><dt><span class="term"><code class="code">--enable-cxx-flags=FLAGS</code></span></dt><dd><p>With this option, you can pass a string of -f (functionality)
flags to the compiler to use when building libstdc++. This
option can change the library ABI. FLAGS is a quoted string of
options, like
flags to the compiler to use when building libstdc++. This
option can change the library ABI. FLAGS is a quoted string of
options, like
</p><pre class="programlisting">
--enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</pre><p>
Note that the flags don't necessarily have to all be -f flags,
as shown, but usually those are the ones that will make sense
for experimentation and configure-time overriding.
Note that the flags don't necessarily have to all be -f flags,
as shown, but usually those are the ones that will make sense
for experimentation and configure-time overriding.
</p><p>The advantage of --enable-cxx-flags over setting CXXFLAGS in
the 'make' environment is that, if files are automatically
rebuilt, the same flags will be used when compiling those files
as well, so that everything matches.
the 'make' environment is that, if files are automatically
rebuilt, the same flags will be used when compiling those files
as well, so that everything matches.
</p><p>Fun flags to try might include combinations of
</p><pre class="programlisting">
-fstrict-aliasing
-fno-exceptions
-ffunction-sections
-fvtable-gc</pre><p>and opposite forms (-fno-) of the same. Tell us (the libstdc++
mailing list) if you discover more!
mailing list) if you discover more!
</p></dd><dt><span class="term"><code class="code">--enable-c99</code></span></dt><dd><p>The "long long" type was introduced in C99, along
with many other functions for wide characters, and math
classification macros, etc. If enabled, all C99 functions not
specified by the C++ standard will be put into <code class="code">namespace
__gnu_cxx</code>, and then all these names will
be injected into namespace std, so that C99 functions can be
used "as if" they were in the C++ standard (as they
will eventually be in some future revision of the standard,
without a doubt). By default, C99 support is on, assuming the
configure probes find all the necessary functions and bits
necessary. This option can change the library ABI.
with many other functions for wide characters, and math
classification macros, etc. If enabled, all C99 functions not
specified by the C++ standard will be put into <code class="code">namespace
__gnu_cxx</code>, and then all these names will
be injected into namespace std, so that C99 functions can be
used "as if" they were in the C++ standard (as they
will eventually be in some future revision of the standard,
without a doubt). By default, C99 support is on, assuming the
configure probes find all the necessary functions and bits
necessary. This option can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-wchar_t</code>[default]</span></dt><dd><p>Template specializations for the "wchar_t" type are
required for wide character conversion support. Disabling
wide character specializations may be expedient for initial
porting efforts, but builds only a subset of what is required by
ISO, and is not recommended. By default, this option is on.
This option can change the library ABI.
required for wide character conversion support. Disabling
wide character specializations may be expedient for initial
porting efforts, but builds only a subset of what is required by
ISO, and is not recommended. By default, this option is on.
This option can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-long-long </code></span></dt><dd><p>The "long long" type was introduced in C99. It is
provided as a GNU extension to C++98 in g++. This flag builds
support for "long long" into the library (specialized
templates and the like for iostreams). This option is on by default:
if enabled, users will have to either use the new-style "C"
headers by default (i.e., &lt;cmath&gt; not &lt;math.h&gt;)
or add appropriate compile-time flags to all compile lines to
allow "C" visibility of this feature (on GNU/Linux,
the flag is -D_ISOC99_SOURCE, which is added automatically via
CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
This option can change the library ABI.
provided as a GNU extension to C++98 in g++. This flag builds
support for "long long" into the library (specialized
templates and the like for iostreams). This option is on by default:
if enabled, users will have to either use the new-style "C"
headers by default (i.e., &lt;cmath&gt; not &lt;math.h&gt;)
or add appropriate compile-time flags to all compile lines to
allow "C" visibility of this feature (on GNU/Linux,
the flag is -D_ISOC99_SOURCE, which is added automatically via
CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
This option can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-fully-dynamic-string</code></span></dt><dd><p>This option enables a special version of basic_string avoiding
the optimization that allocates empty objects in static memory.
the optimization that allocates empty objects in static memory.
Mostly useful together with shared memory allocators, see PR
libstdc++/16612 for details.
</p></dd><dt><span class="term"><code class="code">--enable-concept-checks</code></span></dt><dd><p>This turns on additional compile-time checks for instantiated
library templates, in the form of specialized templates,
<a class="link" href="bk01pt03ch08.html" title="Chapter 8. Concept Checking">described here</a>. They
can help users discover when they break the rules of the STL, before
their programs run.
library templates, in the form of specialized templates,
<a class="link" href="bk01pt02ch05s02.html" title="Concept Checking">described here</a>. They
can help users discover when they break the rules of the STL, before
their programs run.
</p></dd><dt><span class="term"><code class="code">--enable-symvers[=style]</code></span></dt><dd><p>In 3.1 and later, tries to turn on symbol versioning in the
shared library (if a shared library has been
requested). Values for 'style' that are currently supported
are 'gnu', 'gnu-versioned-namespace', 'darwin', and
'darwin-export'. Both gnu- options require that a recent
version of the GNU linker be in use. Both darwin options are
equivalent. With no style given, the configure script will try
to guess correct defaults for the host system, probe to see if
additional requirements are necessary and present for
activation, and if so, will turn symbol versioning on. This
option can change the library ABI.
shared library (if a shared library has been
requested). Values for 'style' that are currently supported
are 'gnu', 'gnu-versioned-namespace', 'darwin', and
'darwin-export'. Both gnu- options require that a recent
version of the GNU linker be in use. Both darwin options are
equivalent. With no style given, the configure script will try
to guess correct defaults for the host system, probe to see if
additional requirements are necessary and present for
activation, and if so, will turn symbol versioning on. This
option can change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-visibility</code></span></dt><dd><p> In 4.2 and later, enables or disables visibility attributes.
If enabled (as by default), and the compiler seems capable of
passing the simple sanity checks thrown at it, adjusts items
in namespace std, namespace std::tr1, and namespace __gnu_cxx
so that -fvisibility options work.
If enabled (as by default), and the compiler seems capable of
passing the simple sanity checks thrown at it, adjusts items
in namespace std, namespace std::tr1, and namespace __gnu_cxx
so that -fvisibility options work.
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-pch</code></span></dt><dd><p>In 3.4 and later, tries to turn on the generation of
stdc++.h.gch, a pre-compiled file including all the standard
C++ includes. If enabled (as by default), and the compiler
seems capable of passing the simple sanity checks thrown at
it, try to build stdc++.h.gch as part of the make process.
In addition, this generated file is used later on (by appending <code class="code">
--include bits/stdc++.h </code> to CXXFLAGS) when running the
testsuite.
stdc++.h.gch, a pre-compiled file including all the standard
C++ includes. If enabled (as by default), and the compiler
seems capable of passing the simple sanity checks thrown at
it, try to build stdc++.h.gch as part of the make process.
In addition, this generated file is used later on (by appending <code class="code">
--include bits/stdc++.h </code> to CXXFLAGS) when running the
testsuite.
</p></dd><dt><span class="term"><code class="code">--disable-hosted-libstdcxx</code></span></dt><dd><p>
By default, a complete <span class="emphasis"><em>hosted</em></span> C++ library is
built. The C++ Standard also describes a
@ -188,17 +188,17 @@
minimal set of headers are provided. This option builds such an
environment.
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-time</code></span></dt><dd><p>This is an abbreviated form of
<code class="code">'--enable-libstdcxx-time=yes'</code>(described next).
<code class="code">'--enable-libstdcxx-time=yes'</code>(described next).
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-time=OPTION</code></span></dt><dd><p>Enables link-type checks for the availability of the
clock_gettime clocks, used in the implementation of [time.clock],
and of the nanosleep and sched_yield functions, used in the
implementation of [thread.thread.this] of the current C++0x draft.
The choice OPTION=yes checks for the availability of the facilities
in libc and libposix4. In case of need the latter is also linked
to libstdc++ as part of the build process. OPTION=rt also searches
(and, in case, links) librt. Note that the latter is not always
desirable because, in glibc, for example, in turn it triggers the
linking of libpthread too, which activates locking, a large overhead
for single-thread programs. OPTION=no skips the tests completely.
The default is OPTION=no.
clock_gettime clocks, used in the implementation of [time.clock],
and of the nanosleep and sched_yield functions, used in the
implementation of [thread.thread.this] of the current C++0x draft.
The choice OPTION=yes checks for the availability of the facilities
in libc and libposix4. In case of need the latter is also linked
to libstdc++ as part of the build process. OPTION=rt also searches
(and, in case, links) librt. Note that the latter is not always
desirable because, in glibc, for example, in turn it triggers the
linking of libpthread too, which activates locking, a large overhead
for single-thread programs. OPTION=no skips the tests completely.
The default is OPTION=no.
</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="setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="setup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="make.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"> Make</td></tr></table></div></body></html>

54
libstdc++-v3/doc/html/manual/containers.html
View file

@ -1,9 +1,55 @@
<?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 VII.  Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="messages.html" title="messages" /><link rel="next" href="sequences.html" title="Chapter 16. Sequences" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part VII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 9.  Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="facets.html" title="Facets" /><link rel="next" href="associative.html" title="Associative" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. 
Containers
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="messages.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="sequences.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part VII.  Containers"><div class="titlepage"><div><div><h1 class="title"><a id="manual.containers"></a>Part VII. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="facets.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="associative.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 9.  Containers"><div class="titlepage"><div><div><h2 class="title"><a id="std.containers"></a>Chapter 9. 
Containers
<a id="id611655" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="sequences.html">16. Sequences</a></span></dt><dd><dl><dt><span class="sect1"><a href="sequences.html#containers.sequences.list">list</a></span></dt><dd><dl><dt><span class="sect2"><a href="sequences.html#sequences.list.size">list::size() is O(n)</a></span></dt></dl></dd><dt><span class="sect1"><a href="vector.html">vector</a></span></dt><dd><dl><dt><span class="sect2"><a href="vector.html#sequences.vector.management">Space Overhead Management</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="associative.html">17. Associative</a></span></dt><dd><dl><dt><span class="sect1"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect1"><a href="bitset.html">bitset</a></span></dt><dd><dl><dt><span class="sect2"><a href="bitset.html#associative.bitset.size_variable">Size Variable</a></span></dt><dt><span class="sect2"><a href="bitset.html#associative.bitset.type_string">Type String</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="containers_and_c.html">18. Interacting with C</a></span></dt><dd><dl><dt><span class="sect1"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></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="messages.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="sequences.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">messages </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. Sequences</td></tr></table></div></body></html>
<a id="id485371" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="containers.html#std.containers.sequences">Sequences</a></span></dt><dd><dl><dt><span class="sect2"><a href="containers.html#containers.sequences.list">list</a></span></dt><dt><span class="sect2"><a href="containers.html#containers.sequences.vector">vector</a></span></dt></dl></dd><dt><span class="sect1"><a href="associative.html">Associative</a></span></dt><dd><dl><dt><span class="sect2"><a href="associative.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect2"><a href="associative.html#containers.associative.bitset">bitset</a></span></dt></dl></dd><dt><span class="sect1"><a href="containers_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="sect2"><a href="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></dd></dl></div><div class="sect1" title="Sequences"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.containers.sequences"></a>Sequences</h2></div></div></div><div class="sect2" title="list"><div class="titlepage"><div><div><h3 class="title"><a id="containers.sequences.list"></a>list</h3></div></div></div><div class="sect3" title="list::size() is O(n)"><div class="titlepage"><div><div><h4 class="title"><a id="sequences.list.size"></a>list::size() is O(n)</h4></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">“<span class="quote">should</span>”</span> be constant time, and
<span class="quote">“<span class="quote">should</span>”</span> does not mean the same thing as
<span class="quote">“<span class="quote">shall</span>”</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 class="sect2" title="vector"><div class="titlepage"><div><div><h3 class="title"><a id="containers.sequences.vector"></a>vector</h3></div></div></div><p>
</p><div class="sect3" title="Space Overhead Management"><div class="titlepage"><div><div><h4 class="title"><a id="sequences.vector.management"></a>Space Overhead Management</h4></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>.
</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="facets.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="associative.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Facets </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Associative</td></tr></table></div></body></html>

20
libstdc++-v3/doc/html/manual/containers_and_c.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII.  Containers" /><link rel="prev" href="bitset.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="bitset.html">Prev</a> </td><th width="60%" align="center">Part VII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Chapter 9.  Containers" /><link rel="prev" href="associative.html" title="Associative" /><link rel="next" href="iterators.html" title="Chapter 10.  Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="associative.html">Prev</a> </td><th width="60%" align="center">Chapter 9. 
Containers
</th><td width="20%" align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 18. Interacting with C"><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="containers_and_c.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></div><div class="sect1" title="Containers vs. Arrays"><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>
</th><td width="20%" align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Interacting with C"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.containers.c"></a>Interacting with C</h2></div></div></div><div class="sect2" title="Containers vs. Arrays"><div class="titlepage"><div><div><h3 class="title"><a id="containers.c.vs_array"></a>Containers vs. Arrays</h3></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
@ -18,7 +18,7 @@
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="link" href="bk01pt08ch19s02.html" title="One Past the End">past-the-end</a> element.
and the <a class="link" href="iterators.html#iterators.predefined.end" title="One Past the End">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
@ -48,27 +48,27 @@ template&lt;typename T&gt;
{ return v.begin(); }
template&lt;typename T, unsigned int sz&gt;
inline T*
inline T*
beginof(T (&amp;array)[sz]) { return array; }
// endof
template&lt;typename T&gt;
inline typename vector&lt;T&gt;::iterator
inline typename vector&lt;T&gt;::iterator
endof(vector&lt;T&gt; &amp;v)
{ return v.end(); }
template&lt;typename T, unsigned int sz&gt;
inline T*
inline T*
endof(T (&amp;array)[sz]) { return array + sz; }
// lengthof
template&lt;typename T&gt;
inline typename vector&lt;T&gt;::size_type
inline typename vector&lt;T&gt;::size_type
lengthof(vector&lt;T&gt; &amp;v)
{ return v.size(); }
template&lt;typename T, unsigned int sz&gt;
inline unsigned int
inline unsigned int
lengthof(T (&amp;)[sz]) { return sz; }
</pre><p>
Astute readers will notice two things at once: first, that the
@ -81,10 +81,10 @@ template&lt;typename T, unsigned int sz&gt;
</p><p>
Second, the line
</p><pre class="programlisting">
inline unsigned int lengthof (T (&amp;)[sz]) { return sz; }
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="bitset.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. 
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="associative.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">Associative </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. 
Iterators
</td></tr></table></div></body></html>

33
libstdc++-v3/doc/html/manual/debug.html
View file

@ -1,10 +1,10 @@
<?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>Debugging Support</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; debug&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_exceptions.html" title="Exceptions" /><link rel="next" href="support.html" title="Part II.  Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Debugging Support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="support.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Debugging Support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.debug"></a>Debugging Support</h2></div></div></div><p>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Debugging Support</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; C++&#10; , &#10; debug&#10; " /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_exceptions.html" title="Exceptions" /><link rel="next" href="bk01pt02.html" title="Part II.  Standard Contents" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Debugging Support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Debugging Support"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.debug"></a>Debugging Support</h2></div></div></div><p>
There are numerous things that can be done to improve the ease with
which C++ binaries are debugged when using the GNU tool chain. Here
are some of them.
</p><div class="sect2" title="Using g++"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compiler"></a>Using <span class="command"><strong>g++</strong></span></h3></div></div></div><p>
</p><div class="sect2" title="Using g++"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compiler"></a>Using <span class="command"><strong>g++</strong></span></h3></div></div></div><p>
Compiler flags determine how debug information is transmitted
between compilation and debug or analysis tools.
</p><p>
@ -46,13 +46,13 @@
separate directory tree, in <code class="code">(prefix)/lib/debug</code>. For
more information, look at the <a class="link" href="configure.html" title="Configure">configuration</a> section.
</p><p>
A second approach is to use the configuration flags
A second approach is to use the configuration flags
</p><pre class="programlisting">
make CXXFLAGS='-g3 -fno-inline -O0' all
</pre><p>
This quick and dirty approach is often sufficient for quick
debugging tasks, when you cannot or don't want to recompile your
application to use the <a class="link" href="debug_mode.html" title="Chapter 30. Debug Mode">debug mode</a>.</p></div><div class="sect2" title="Memory Leak Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"></a>Memory Leak Hunting</h3></div></div></div><p>
application to use the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>.</p></div><div class="sect2" title="Memory Leak Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"></a>Memory Leak Hunting</h3></div></div></div><p>
There are various third party memory tracing and debug utilities
that can be used to provide detailed memory allocation information
about C++ code. An exhaustive list of tools is not going to be
@ -111,17 +111,17 @@
int main()
{
extern void* __dso_handle __attribute__ ((__weak__));
__cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
&amp;__dso_handle ? __dso_handle : NULL);
__cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
&amp;__dso_handle ? __dso_handle : NULL);
do_test();
return 0;
}
</pre><p>
Suggested valgrind flags, given the suggestions above about setting
up the runtime environment, library, and test file, might be:
</p><pre class="programlisting">
</p><pre class="programlisting">
valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
</pre></div><div class="sect2" title="Using gdb"><div class="titlepage"><div><div><h3 class="title"><a id="debug.gdb"></a>Using <span class="command"><strong>gdb</strong></span></h3></div></div></div><p>
</pre></div><div class="sect2" title="Using gdb"><div class="titlepage"><div><div><h3 class="title"><a id="debug.gdb"></a>Using <span class="command"><strong>gdb</strong></span></h3></div></div></div><p>
</p><p>
Many options are available for gdb itself: please see <a class="ulink" href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC125" target="_top">
"GDB features for C++" </a> in the gdb documentation. Also
@ -145,7 +145,7 @@
To enable these printers, check-out the latest printers to a local
directory:
</p><pre class="programlisting">
svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
</pre><p>
Next, add the following section to your ~/.gdbinit The path must
match the location where the Python module above was checked-out.
@ -175,18 +175,17 @@
<a class="ulink" href="http://sourceware.org/gdb/" target="_top"> "GDB: The GNU Project
Debugger" </a>.
</p></div><div class="sect2" title="Tracking uncaught exceptions"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"></a>Tracking uncaught exceptions</h3></div></div></div><p>
The <a class="link" href="verbose_termination.html" title="Verbose Terminate Handler">verbose
The <a class="link" href="termination.html#support.termination.verbose" title="Verbose Terminate Handler">verbose
termination handler</a> gives information about uncaught
exceptions which are killing the program. It is described in the
linked-to page.
</p></div><div class="sect2" title="Debug Mode"><div class="titlepage"><div><div><h3 class="title"><a id="debug.debug_mode"></a>Debug Mode</h3></div></div></div><p> The <a class="link" href="debug_mode.html" title="Chapter 30. Debug Mode">Debug Mode</a>
</p></div><div class="sect2" title="Debug Mode"><div class="titlepage"><div><div><h3 class="title"><a id="debug.debug_mode"></a>Debug Mode</h3></div></div></div><p> The <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">Debug Mode</a>
has compile and run-time checks for many containers.
</p></div><div class="sect2" title="Compile Time Checking"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compile_time_checks"></a>Compile Time Checking</h3></div></div></div><p> The <a class="link" href="ext_compile_checks.html" title="Chapter 29. Compile Time Checks">Compile-Time
</p></div><div class="sect2" title="Compile Time Checking"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compile_time_checks"></a>Compile Time Checking</h3></div></div></div><p> The <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">Compile-Time
Checks</a> Extension has compile-time checks for many algorithms.
</p></div><div class="sect2" title="Profile-based Performance Analysis"><div class="titlepage"><div><div><h3 class="title"><a id="debug.profile_mode"></a>Profile-based Performance Analysis</h3></div></div></div><p> The <a class="link" href="profile_mode.html" title="Chapter 32. Profile Mode">Profile-based
Performance Analysis</a> Extension has performance checks for many
</p></div><div class="sect2" title="Profile-based Performance Analysis"><div class="titlepage"><div><div><h3 class="title"><a id="debug.profile_mode"></a>Profile-based Performance Analysis</h3></div></div></div><p> The <a class="link" href="profile_mode.html" title="Chapter 19. Profile Mode">Profile-based
Performance Analysis</a> Extension has performance checks for many
algorithms.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_exceptions.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="support.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Exceptions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part II. 
Support
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_exceptions.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="bk01pt02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Exceptions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part II. 
Standard Contents
</td></tr></table></div></body></html>

8
libstdc++-v3/doc/html/manual/debug_mode.html
View file

@ -1,9 +1,9 @@
<?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 30. Debug Mode</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_compile_checks.html" title="Chapter 29. Compile Time Checks" /><link rel="next" href="bk01pt12ch30s02.html" title="Semantics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 30. Debug Mode</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_compile_checks.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 17. Debug Mode</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks" /><link rel="next" href="bk01pt03ch17s02.html" title="Semantics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 17. Debug Mode</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_compile_checks.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch30s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 30. Debug Mode"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode"></a>Chapter 30. Debug Mode</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="debug_mode.html#manual.ext.debug_mode.intro">Intro</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch30s02.html">Semantics</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch30s03.html">Using</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch30s03.html#debug_mode.using.mode">Using the Debug Mode</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch30s03.html#debug_mode.using.specific">Using a Specific Debug Container</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch30s04.html">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch30s04.html#debug_mode.design.goals">Goals</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch30s04.html#debug_mode.design.methods">Methods</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch30s04.html#debug_mode.design.other">Other Implementations</a></span></dt></dl></dd></dl></div><div class="sect1" title="Intro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.intro"></a>Intro</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch17s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 17. Debug Mode"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.debug_mode"></a>Chapter 17. Debug Mode</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="debug_mode.html#manual.ext.debug_mode.intro">Intro</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch17s02.html">Semantics</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch17s03.html">Using</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt03ch17s03.html#debug_mode.using.mode">Using the Debug Mode</a></span></dt><dt><span class="sect2"><a href="bk01pt03ch17s03.html#debug_mode.using.specific">Using a Specific Debug Container</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt03ch17s04.html">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt03ch17s04.html#debug_mode.design.goals">Goals</a></span></dt><dt><span class="sect2"><a href="bk01pt03ch17s04.html#debug_mode.design.methods">Methods</a></span></dt><dt><span class="sect2"><a href="bk01pt03ch17s04.html#debug_mode.design.other">Other Implementations</a></span></dt></dl></dd></dl></div><div class="sect1" title="Intro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.intro"></a>Intro</h2></div></div></div><p>
By default, libstdc++ is built with efficiency in mind, and
therefore performs little or no error checking that is not
required by the C++ standard. This means that programs that
@ -15,7 +15,7 @@
library facilities, and will report errors in the use of libstdc++
as soon as they can be detected by emitting a description of the
problem to standard error and aborting the program. This debug
mode is available with GCC 3.4.0 and later versions.
mode is available with GCC 3.4.0 and later versions.
</p><p>
The libstdc++ debug mode performs checking for many areas of the
C++ standard, but the focus is on checking interactions among
@ -34,4 +34,4 @@
the same predicate that was passed
to <code class="code">set_intersection</code>; the libstdc++ debug mode will
detect an error if the sequence is not sorted or was sorted by a
different predicate.</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_compile_checks.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="bk01pt12ch30s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 29. Compile Time Checks </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Semantics</td></tr></table></div></body></html>
different predicate.</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_compile_checks.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="bk01pt03ch17s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16. Compile Time Checks </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Semantics</td></tr></table></div></body></html>

42
libstdc++-v3/doc/html/manual/diagnostics.html
View file

@ -1,9 +1,43 @@
<?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 III.  Diagnostics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="verbose_termination.html" title="Verbose Terminate Handler" /><link rel="next" href="exceptions.html" title="Chapter 7. Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part III. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5.  Diagnostics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="termination.html" title="Termination" /><link rel="next" href="bk01pt02ch05s02.html" title="Concept Checking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. 
Diagnostics
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="verbose_termination.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="exceptions.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part III.  Diagnostics"><div class="titlepage"><div><div><h1 class="title"><a id="manual.diagnostics"></a>Part III. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="termination.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch05s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 5.  Diagnostics"><div class="titlepage"><div><div><h2 class="title"><a id="std.diagnostics"></a>Chapter 5. 
Diagnostics
<a id="id622040" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="exceptions.html">7. Exceptions</a></span></dt><dd><dl><dt><span class="sect1"><a href="exceptions.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></dl></dd><dt><span class="chapter"><a href="bk01pt03ch08.html">8. Concept Checking</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="verbose_termination.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="exceptions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Verbose Terminate Handler </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Exceptions</td></tr></table></div></body></html>
<a id="id477731" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="sect2"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="sect2"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt02ch05s02.html">Concept Checking</a></span></dt></dl></div><div class="sect1" title="Exceptions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.diagnostics.exceptions"></a>Exceptions</h2></div></div></div><div class="sect2" title="API Reference"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.api"></a>API Reference</h3></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 hierarchy can be
found in the source documentation.
</p><p>
Full API details.
</p></div><div class="sect2" title="Adding Data to exception"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.data"></a>Adding Data to <code class="classname">exception</code></h3></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></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="termination.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch05s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Termination </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Concept Checking</td></tr></table></div></body></html>

76
libstdc++-v3/doc/html/manual/documentation_style.html
View file

@ -4,25 +4,29 @@
Contributing
</th><td width="20%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Documentation Style"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.doc_style"></a>Documentation Style</h2></div></div></div><div class="sect2" title="Doxygen"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.doxygen"></a>Doxygen</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><p>
Prerequisite tools are Bash 2.x,
Prerequisite tools are Bash 2.x or higher,
<a class="ulink" href="http://www.doxygen.org/" target="_top">Doxygen</a>, and
the <a class="ulink" href="http://www.gnu.org/software/coreutils/" target="_top">GNU
coreutils</a>. (GNU versions of find, xargs, and possibly
sed and grep are used, just because the GNU versions make
things very easy.)
things very easy.)
</p><p>
To generate the pretty pictures and hierarchy
graphs, the
<a class="ulink" href="http://www.graphviz.org" target="_top">Graphviz</a>
package will need to be installed.
<a class="ulink" href="http://www.graphviz.org" target="_top">Graphviz</a> package
will need to be installed. For PDF
output, <a class="ulink" href="http://www.tug.org/applications/pdftex/" target="_top">
pdflatex</a> is required.
</p></div><div class="sect3" title="Generating the Doxygen Files"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
The following Makefile rules run Doxygen to generate HTML
docs, XML docs, and the man pages.
docs, XML docs, PDF docs, and the man pages.
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf-doxygen</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p>
</p><p>
Careful observers will see that the Makefile rules simply call
@ -64,7 +68,7 @@
...not the Qt style. The intermediate *'s are preferred.
</p></li><li class="listitem"><p>
Use the triple-slash style only for one-line comments (the
<span class="quote">“<span class="quote">brief</span>”</span> mode).
<span class="quote">“<span class="quote">brief</span>”</span> mode).
</p></li><li class="listitem"><p>
This is disgusting. Don't do this.
</p></li></ol></div><p>
@ -95,7 +99,7 @@
   * @brief A model of a linear congruential random number generator.<br />
   *<br />
   * @f[<br />
   *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m <br />
   *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m<br />
   * @f]<br />
   */<br />
</p></div><p>
@ -104,7 +108,7 @@
writing Doxygen comments. Single and double quotes, and
separators in filenames are two common trouble spots. When in
doubt, consult the following table.
</p><div class="table"><a id="id645775"></a><p class="title"><b>Table A.1. HTML to Doxygen markup comparison</b></p><div class="table-contents"><table summary="HTML to Doxygen markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left">&lt;i&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;b&gt;</td><td align="left">@b word</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">@c word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;em&gt;two words or more&lt;/em&gt;</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
</p><div class="table"><a id="id389869"></a><p class="title"><b>Table A.1. HTML to Doxygen Markup Comparison</b></p><div class="table-contents"><table summary="HTML to Doxygen Markup Comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Doxygen</th></tr></thead><tbody><tr><td align="left">\</td><td align="left">\\</td></tr><tr><td align="left">"</td><td align="left">\"</td></tr><tr><td align="left">'</td><td align="left">\'</td></tr><tr><td align="left">&lt;i&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;b&gt;</td><td align="left">@b word</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">@c word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">@a word</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;em&gt;two words or more&lt;/em&gt;</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2" title="Docbook"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
Editing the DocBook sources requires an XML editor. Many
exist: some notable options
include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
@ -139,33 +143,35 @@
by a vendor package like <code class="filename">libxml2</code>.
</p><p>
For PDF output, something that transforms valid XML to PDF is
required. Possible solutions include <span class="command"><strong>xmlto</strong></span>,
<a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">Apache
FOP</a>, or <span class="command"><strong>prince</strong></span>. Other options are
listed on the DocBook web <a class="ulink" href="http://wiki.docbook.org/topic/DocBookPublishingTools" target="_top">pages</a>. Please
required. Possible solutions include
<a class="ulink" href="http://dblatex.sourceforge.net" target="_top">dblatex</a>,
<span class="command"><strong>xmlto</strong></span>, or <span class="command"><strong>prince</strong></span>. Other
options are listed on the DocBook
web <a class="ulink" href="http://wiki.docbook.org/topic/DocBookPublishingTools" target="_top">pages</a>. Please
consult the <code class="email">&lt;<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>&gt;</code> list when
preparing printed manuals for current best practice and suggestions.
preparing printed manuals for current best practice and
suggestions.
</p><p>
Make sure that the XML documentation and markup is valid for
any change. This can be done easily, with the validation rules
in the <code class="filename">Makefile</code>, which is equivalent to doing:
in the <code class="filename">Makefile</code>, which is equivalent to doing:
</p><pre class="screen">
<strong class="userinput"><code>
xmllint --noout --valid <code class="filename">xml/index.xml</code>
</code></strong>
</pre></div><div class="sect3" title="Generating the DocBook Files"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p>
The following Makefile rules generate (in order): an HTML
version of all the documentation, a PDF version of the same, a
version of all the DocBook documentation, a PDF version of the same, a
single XML document, and the result of validating the entire XML
document.
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-html-docbook</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf-docbook</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single-docbook</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate-docbook</code></strong></pre><p>
</p></div><div class="sect3" title="File Organization and Basics"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"></a>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br />
      <span class="emphasis"><em>Which files are important</em></span><br />
<br />
@ -173,11 +179,11 @@ xmllint --noout --valid <code class="filename">xml/index.xml</code>
      libstdc++-v3/doc/xml<br />
<br />
      Inside this directory, the files of importance:<br />
      spine.xml   - index to documentation set<br />
      spine.xml   - index to documentation set<br />
      manual/spine.xml  - index to manual<br />
      manual/*.xml   - individual chapters and sections of the manual<br />
      faq.xml   - index to FAQ<br />
      api.xml   - index to source level / API <br />
      api.xml   - index to source level / API<br />
<br />
      All *.txml files are template xml files, i.e., otherwise empty files with<br />
      the correct structure, suitable for filling in with new information.<br />
@ -205,7 +211,7 @@ xmllint --noout --valid <code class="filename">xml/index.xml</code>
      &lt;/chapter&gt;<br />
      &lt;/book&gt;<br />
<br />
      &lt;book&gt; <br />
      &lt;book&gt;<br />
      &lt;part&gt;<br />
      &lt;chapter&gt;<br />
      &lt;section&gt;<br />
@ -222,20 +228,21 @@ xmllint --noout --valid <code class="filename">xml/index.xml</code>
<br />
      &lt;chapter&gt;<br />
      &lt;/chapter&gt;<br />
      &lt;/part&gt;  <br />
      &lt;/part&gt;<br />
      &lt;/book&gt;<br />
<br />
      &lt;/set&gt;<br />
    </p></div></div><div class="sect3" title="Markup By Example"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><p>
Complete details on Docbook markup can be found in the DocBook Element
Reference, <a class="ulink" href="http://www.docbook.org/tdg/en/html/part2.html" target="_top">online</a>. An
incomplete reference for HTML to Docbook conversion is detailed in the
table below.
</p><div class="table"><a id="id724766"></a><p class="title"><b>Table A.2. HTML to Docbook XML markup comparison</b></p><div class="table-contents"><table summary="HTML to Docbook XML markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Docbook</th></tr></thead><tbody><tr><td align="left">&lt;p&gt;</td><td align="left">&lt;para&gt;</td></tr><tr><td align="left">&lt;pre&gt;</td><td align="left">&lt;computeroutput&gt;, &lt;programlisting&gt;,
Complete details on Docbook markup can be found in the DocBook
Element Reference,
<a class="ulink" href="http://www.docbook.org/tdg/en/html/part2.html" target="_top">online</a>.
An incomplete reference for HTML to Docbook conversion is
detailed in the table below.
</p><div class="table"><a id="id501323"></a><p class="title"><b>Table A.2. HTML to Docbook XML Markup Comparison</b></p><div class="table-contents"><table summary="HTML to Docbook XML Markup Comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">Docbook</th></tr></thead><tbody><tr><td align="left">&lt;p&gt;</td><td align="left">&lt;para&gt;</td></tr><tr><td align="left">&lt;pre&gt;</td><td align="left">&lt;computeroutput&gt;, &lt;programlisting&gt;,
&lt;literallayout&gt;</td></tr><tr><td align="left">&lt;ul&gt;</td><td align="left">&lt;itemizedlist&gt;</td></tr><tr><td align="left">&lt;ol&gt;</td><td align="left">&lt;orderedlist&gt;</td></tr><tr><td align="left">&lt;il&gt;</td><td align="left">&lt;listitem&gt;</td></tr><tr><td align="left">&lt;dl&gt;</td><td align="left">&lt;variablelist&gt;</td></tr><tr><td align="left">&lt;dt&gt;</td><td align="left">&lt;term&gt;</td></tr><tr><td align="left">&lt;dd&gt;</td><td align="left">&lt;listitem&gt;</td></tr><tr><td align="left">&lt;a href=""&gt;</td><td align="left">&lt;ulink url=""&gt;</td></tr><tr><td align="left">&lt;code&gt;</td><td align="left">&lt;literal&gt;, &lt;programlisting&gt;</td></tr><tr><td align="left">&lt;strong&gt;</td><td align="left">&lt;emphasis&gt;</td></tr><tr><td align="left">&lt;em&gt;</td><td align="left">&lt;emphasis&gt;</td></tr><tr><td align="left">"</td><td align="left">&lt;quote&gt;</td></tr></tbody></table></div></div><br class="table-break" /><p>
And examples of detailed markup for which there are no real HTML
equivalents are listed in the table below.
</p><div class="table"><a id="id631420"></a><p class="title"><b>Table A.3. Docbook XML Element Use</b></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left">&lt;structname&gt;</td><td align="left">&lt;structname&gt;char_traits&lt;/structname&gt;</td></tr><tr><td align="left">&lt;classname&gt;</td><td align="left">&lt;classname&gt;string&lt;/classname&gt;</td></tr><tr><td align="left">&lt;function&gt;</td><td align="left">
</p><div class="table"><a id="id377073"></a><p class="title"><b>Table A.3. Docbook XML Element Use</b></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left">&lt;structname&gt;</td><td align="left">&lt;structname&gt;char_traits&lt;/structname&gt;</td></tr><tr><td align="left">&lt;classname&gt;</td><td align="left">&lt;classname&gt;string&lt;/classname&gt;</td></tr><tr><td align="left">&lt;function&gt;</td><td align="left">
<p>&lt;function&gt;clear()&lt;/function&gt;</p>
<p>&lt;function&gt;fs.clear()&lt;/function&gt;</p>
</td></tr><tr><td align="left">&lt;type&gt;</td><td align="left">&lt;type&gt;long long&lt;/type&gt;</td></tr><tr><td align="left">&lt;varname&gt;</td><td align="left">&lt;varname&gt;fs&lt;/varname&gt;</td></tr><tr><td align="left">&lt;literal&gt;</td><td align="left">
@ -248,4 +255,13 @@ table below.
<p>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</p>
<p>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</p>
<p>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</p>
</td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source_code_style.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="source_design_notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Coding Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>
</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="sect2" title="Combines"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.combines"></a>Combines</h3></div></div></div><div class="sect3" title="Generating Combines and Assemblages"><div class="titlepage"><div><div><h4 class="title"><a id="combines.rules"></a>Generating Combines and Assemblages</h4></div></div></div><p>
The following Makefile rules are defaults, and are usually
aliased to variable rules.
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-man</code></strong></pre><p>
</p><p>
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="source_code_style.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="source_design_notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Coding Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>

15
libstdc++-v3/doc/html/manual/dynamic_memory.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="termination.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. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Dynamic Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Chapter 4.  Support" /><link rel="prev" href="support.html" title="Chapter 4.  Support" /><link rel="next" href="termination.html" title="Termination" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dynamic Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><th width="60%" align="center">Chapter 4. 
Support
</th><td width="20%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 5. Dynamic Memory"><div class="titlepage"><div><div><h2 class="title"><a id="manual.support.memory"></a>Chapter 5. Dynamic Memory</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Dynamic Memory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.memory"></a>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>:
@ -51,8 +51,8 @@
{
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!");
should, like, close some windows, or something.
The next time you run out, we're gonna burn!");
set_new_handler (old_handler);
return;
}
@ -65,5 +65,8 @@
}
</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="termination.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>
class defined in Sect1 19.
</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="termination.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. 
Support
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Termination</td></tr></table></div></body></html>

22
libstdc++-v3/doc/html/manual/exceptions.html
View file

@ -1,22 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="Chapter 7. Exceptions"><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="exceptions.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></dl></div><div class="sect1" title="Exception Classes"><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 hierarchy can be
found in the <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00460.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>

10
libstdc++-v3/doc/html/manual/ext_algorithms.html
View file

@ -1,9 +1,9 @@
<?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. Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_utilities.html" title="Chapter 35. Utilities" /><link rel="next" href="ext_numerics.html" title="Chapter 37. Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 36. Algorithms</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_utilities.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 23. Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_utilities.html" title="Chapter 22. Utilities" /><link rel="next" href="ext_numerics.html" title="Chapter 24. Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 23. Algorithms</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_utilities.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_numerics.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 36. Algorithms"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.algorithms"></a>Chapter 36. Algorithms</h2></div></div></div><p>25.1.6 (count, count_if) is extended with two more versions of count
</th><td width="20%" align="right"> <a accesskey="n" href="ext_numerics.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 23. Algorithms"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.algorithms"></a>Chapter 23. 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.,
@ -16,8 +16,8 @@
</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 class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">is_heap</code> tests whether or not a range is a heap.</p></li><li class="listitem"><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 (lexicographical_compare) is extended with
nondescending order.</p></li></ul></div><p>25.3.8 (lexicographical_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="ext_utilities.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="ext_numerics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 35. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. Numerics</td></tr></table></div></body></html>
_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="ext_utilities.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="ext_numerics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 22. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 24. Numerics</td></tr></table></div></body></html>

80
libstdc++-v3/doc/html/manual/ext_allocators.html
View file

@ -1,10 +1,10 @@
<?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. Allocators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="bk01pt12ch32s07.html" title="Diagnostics" /><link rel="next" href="bitmap_allocator.html" title="bitmap_allocator" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 33. Allocators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch32s07.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 20. Allocators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="bk01pt03ch19s07.html" title="Diagnostics" /><link rel="next" href="bitmap_allocator.html" title="bitmap_allocator" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 20. Allocators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s07.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 33. Allocators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator"></a>Chapter 33. Allocators</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_allocators.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></div><div class="sect1" title="mt_allocator"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.allocator.mt"></a>mt_allocator</h2></div></div></div><p>
</p><div class="sect2" title="Intro"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.intro"></a>Intro</h3></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 20. Allocators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator"></a>Chapter 20. Allocators</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_allocators.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="sect2"><a href="ext_allocators.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></div><div class="sect1" title="mt_allocator"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.allocator.mt"></a>mt_allocator</h2></div></div></div><p>
</p><div class="sect2" title="Intro"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.intro"></a>Intro</h3></div></div></div><p>
The mt allocator [hereinafter referred to simply as "the allocator"]
is a fixed size (power of two) allocator that was initially
developed specifically to suit the needs of multi threaded
@ -25,7 +25,7 @@ describing the characteristics of the memory pool, a policy class
containing this pool that links instantiation types to common or
individual pools, and a class inheriting from the policy class that is
the actual allocator.
</p><p>The datum describing pools characteristics is
</p><p>The datum describing pools characteristics is
</p><pre class="programlisting">
template&lt;bool _Thread&gt;
class __pool
@ -82,9 +82,9 @@ int main()
tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
tune_type t;
t = allocator_type::_M_get_options();
t = allocator_type::_M_get_options();
allocator_type::_M_set_options(t_opt);
t = allocator_type::_M_get_options();
t = allocator_type::_M_get_options();
allocator_type a;
allocator_type::pointer p1 = a.allocate(128);
@ -111,18 +111,18 @@ The _S_initialize() function:
allocate() to return memory directly from a new() call, and deallocate will
only do a delete() call.
</p><p>
- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
applications will:
- Calculate the number of bins needed. A bin is a specific power of two size
of bytes. I.e., by default the allocator will deal with requests of up to
128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
called). This means that there will be bins of the following sizes
(in bytes): 1, 2, 4, 8, 16, 32, 64, 128.
of bytes. I.e., by default the allocator will deal with requests of up to
128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
called). This means that there will be bins of the following sizes
(in bytes): 1, 2, 4, 8, 16, 32, 64, 128.
- Create the _S_binmap array. All requests are rounded up to the next
"large enough" bin. I.e., a request for 29 bytes will cause a block from
the "32 byte bin" to be returned to the application. The purpose of
_S_binmap is to speed up the process of finding out which bin to use.
- Create the _S_binmap array. All requests are rounded up to the next
"large enough" bin. I.e., a request for 29 bytes will cause a block from
the "32 byte bin" to be returned to the application. The purpose of
_S_binmap is to speed up the process of finding out which bin to use.
I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes).
</p><p>
- Create the _S_bin array. This array consists of bin_records. There will be
@ -130,35 +130,35 @@ The _S_initialize() function:
earlier. I.e., if _S_max_bytes = 128 there will be 8 entries.
Each bin_record is then initialized:
- bin_record-&gt;first = An array of pointers to block_records. There will be
as many block_records pointers as there are maximum number of threads
(in a ST application there is only 1 thread, in a MT application there
as many block_records pointers as there are maximum number of threads
(in a ST application there is only 1 thread, in a MT application there
are _S_max_threads).
This holds the pointer to the first free block for each thread in this
bin. I.e., if we would like to know where the first free block of size 32
for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ]
The above created block_record pointers members are now initialized to
The above created block_record pointers members are now initialized to
their initial values. I.e. _S_bin[ n ].first[ n ] = NULL;
</p><p>
- Additionally a MT application will:
- Create a list of free thread id's. The pointer to the first entry
is stored in _S_thread_freelist_first. The reason for this approach is
that the __gthread_self() call will not return a value that corresponds to
is stored in _S_thread_freelist_first. The reason for this approach is
that the __gthread_self() call will not return a value that corresponds to
the maximum number of threads allowed but rather a process id number or
something else. So what we do is that we create a list of thread_records.
This list is _S_max_threads long and each entry holds a size_t thread_id
which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads.
Each time a thread calls allocate() or deallocate() we call
Each time a thread calls allocate() or deallocate() we call
_S_get_thread_id() which looks at the value of _S_thread_key which is a
thread local storage pointer. If this is NULL we know that this is a newly
created thread and we pop the first entry from this list and saves the
pointer to this record in the _S_thread_key variable. The next time
we will get the pointer to the thread_record back and we use the
thread_record-&gt;thread_id as identification. I.e., the first thread that
pointer to this record in the _S_thread_key variable. The next time
we will get the pointer to the thread_record back and we use the
thread_record-&gt;thread_id as identification. I.e., the first thread that
calls allocate will get the first record in this list and thus be thread
number 1 and will then find the pointer to its first free 32 byte block
in _S_bin[ 5 ].first[ 1 ]
When we create the _S_thread_key we also define a destructor
When we create the _S_thread_key we also define a destructor
(_S_thread_key_destr) which means that when the thread dies, this
thread_record is returned to the front of this list and the thread id
can then be reused if a new thread is created.
@ -176,7 +176,7 @@ The _S_initialize() function:
has made 678 requests (and no deallocations...) of 32-byte blocks this
counter will read 678.
The above created arrays are now initialized with their initial values.
The above created arrays are now initialized with their initial values.
I.e. _S_bin[ n ].free[ n ] = 0;
</p><p>
- Initialize the mutex of each bin_record: The bin_record-&gt;mutex
@ -260,39 +260,39 @@ This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes):
+----------------+
</pre><p>
With this in mind we simplify things a bit for a while and say that there is
only one thread (a ST application). In this case all operations are made to
only one thread (a ST application). In this case all operations are made to
what is referred to as the global pool - thread id 0 (No thread may be
assigned this id since they span from 1 to _S_max_threads in a MT application).
</p><p>
When the application requests memory (calling allocate()) we first look at the
requested size and if this is &gt; _S_max_bytes we call new() directly and return.
</p><p>
If the requested size is within limits we start by finding out from which
If the requested size is within limits we start by finding out from which
bin we should serve this request by looking in _S_binmap.
</p><p>
A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of
this size on the freelist (0). If this is not NULL - fine, just remove the
block that _S_bin[ bin ].first[ 0 ] points to from the list,
block that _S_bin[ bin ].first[ 0 ] points to from the list,
update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data.
</p><p>
If the freelist is empty (the pointer is NULL) we must get memory from the
If the freelist is empty (the pointer is NULL) we must get memory from the
system and build us a freelist within this memory. All requests for new memory
is made in chunks of _S_chunk_size. Knowing the size of a block_record and
the bytes that this bin stores we then calculate how many blocks we can create
is made in chunks of _S_chunk_size. Knowing the size of a block_record and
the bytes that this bin stores we then calculate how many blocks we can create
within this chunk, build the list, remove the first block, update the pointer
(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data.
(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data.
</p><p>
Deallocation is equally simple; the pointer is casted back to a block_record
pointer, lookup which bin to use based on the size, add the block to the front
of the global freelist and update the pointer as needed
pointer, lookup which bin to use based on the size, add the block to the front
of the global freelist and update the pointer as needed
(_S_bin[ bin ].first[ 0 ]).
</p><p>
The decision to add deallocated blocks to the front of the freelist was made
after a set of performance measurements that showed that this is roughly 10%
faster than maintaining a set of "last pointers" as well.
</p></div><div class="sect2" title="Multiple Thread Example"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.example_multi"></a>Multiple Thread Example</h3></div></div></div><p>
In the ST example we never used the thread_id variable present in each block.
Let's start by explaining the purpose of this in a MT application.
In the ST example we never used the thread_id variable present in each block.
Let's start by explaining the purpose of this in a MT application.
</p><p>
The concept of "ownership" was introduced since many MT applications
allocate and deallocate memory to shared containers from different
@ -321,10 +321,10 @@ When the application requests memory (calling allocate()) we first
look at the requested size and if this is &gt;_S_max_bytes we call new()
directly and return.
</p><p>
If the requested size is within limits we start by finding out from which
If the requested size is within limits we start by finding out from which
bin we should serve this request by looking in _S_binmap.
</p><p>
A call to _S_get_thread_id() returns the thread id for the calling thread
A call to _S_get_thread_id() returns the thread id for the calling thread
(and if no value has been set in _S_thread_key, a new id is assigned and
returned).
</p><p>
@ -394,4 +394,4 @@ mutex to be locked) this operation is also made in chunks of blocks
a threads freelist mentioned above). The "formula" used can probably
be improved to further reduce the risk of blocks being "bounced back
and forth" between freelists.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch32s07.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="bitmap_allocator.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Diagnostics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> bitmap_allocator</td></tr></table></div></body></html>
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s07.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="bitmap_allocator.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Diagnostics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> bitmap_allocator</td></tr></table></div></body></html>

6
libstdc++-v3/doc/html/manual/ext_compile_checks.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 16. Compile Time Checks</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="bk01pt03pr01.html" title="" /><link rel="next" href="debug_mode.html" title="Chapter 17. Debug Mode" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. Compile Time Checks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03pr01.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 29. Compile Time Checks"><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>
</th><td width="20%" align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 16. Compile Time Checks"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.compile_checks"></a>Chapter 16. 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
@ -37,4 +37,4 @@
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>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03pr01.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 17. Debug Mode</td></tr></table></div></body></html>

16
libstdc++-v3/doc/html/manual/ext_concurrency.html
View file

@ -1,9 +1,9 @@
<?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 41. Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_demangling.html" title="Chapter 40. Demangling" /><link rel="next" href="bk01pt12ch41s02.html" title="Implementation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 41. Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 28. Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.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="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_demangling.html" title="Chapter 27. Demangling" /><link rel="next" href="bk01pt03ch28s02.html" title="Implementation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 28. Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_demangling.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch41s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 41. Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency"></a>Chapter 41. Concurrency</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="sect2"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch41s02.html">Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch41s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch41s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch41s03.html">Use</a></span></dt></dl></div><div class="sect1" title="Design"><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" title="Interface to Locks and Mutexes"><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
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch28s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 28. Concurrency"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency"></a>Chapter 28. Concurrency</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="ext_concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="sect2"><a href="ext_concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt03ch28s02.html">Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="sect2"><a href="bk01pt03ch28s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt03ch28s03.html">Use</a></span></dt></dl></div><div class="sect1" title="Design"><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" title="Interface to Locks and Mutexes"><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>
@ -31,7 +31,7 @@ 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" title="Interface to Atomic Functions"><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.
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>
@ -56,7 +56,7 @@ __atomic_add_dispatch
</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,
functions, depending on the circumstances. For instance,
</p><p>
<code class="code">
__exchange_and_add_dispatch
@ -67,7 +67,7 @@ Calls through to either of:
</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 class="listitem"><p><code class="code">__exchange_and_add_single</code>
</p></li><li class="listitem"><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
@ -79,13 +79,13 @@ operations.)
In addition, there are two macros
</p><p>
<code class="code">
_GLIBCXX_READ_MEM_BARRIER
_GLIBCXX_READ_MEM_BARRIER
</code>
</p><p>
<code class="code">
_GLIBCXX_WRITE_MEM_BARRIER
_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="ext_demangling.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="bk01pt12ch41s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 40. 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>
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_demangling.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="bk01pt03ch28s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 27. 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>

6
libstdc++-v3/doc/html/manual/ext_containers.html
View file

@ -1,9 +1,9 @@
<?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. Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="bk01pt12ch34s02.html" title="HP/SGI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 34. 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. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 21. Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="bitmap_allocator.html" title="bitmap_allocator" /><link rel="next" href="bk01pt03ch21s02.html" title="HP/SGI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 21. 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 III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch34s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 34. Containers"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers"></a>Chapter 34. Containers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_containers.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch34s02.html">HP/SGI</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch34s03.html">Deprecated HP/SGI</a></span></dt></dl></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch21s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 21. Containers"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers"></a>Chapter 21. Containers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_containers.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch21s02.html">HP/SGI</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch21s03.html">Deprecated HP/SGI</a></span></dt></dl></div><p>
</p><div class="sect1" title="Policy Based Data Structures"><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="bk01pt12ch34s02.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>
</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="bk01pt03ch21s02.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>

8
libstdc++-v3/doc/html/manual/ext_demangling.html
View file

@ -1,9 +1,9 @@
<?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. Demangling</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_io.html" title="Chapter 39. Input and Output" /><link rel="next" href="ext_concurrency.html" title="Chapter 41. Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 40. Demangling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_io.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 27. Demangling</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_io.html" title="Chapter 26. Input and Output" /><link rel="next" href="ext_concurrency.html" title="Chapter 28. Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. Demangling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_io.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_concurrency.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 40. Demangling"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.demangle"></a>Chapter 40. Demangling</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="ext_concurrency.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 27. Demangling"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.demangle"></a>Chapter 27. Demangling</h2></div></div></div><p>
Transforming C++ ABI identifiers (like RTTI symbols) into the
original C++ source identifiers is called
<span class="quote">“<span class="quote">demangling.</span>”</span>
@ -63,7 +63,7 @@ int main()
</p><pre class="screen">
<code class="computeroutput">
St13bad_exception =&gt; std::bad_exception : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0
</code>
</pre><p>
The demangler interface is described in the source documentation
@ -71,4 +71,4 @@ int main()
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="ext_io.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="ext_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 39. 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 41. Concurrency</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_io.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="ext_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. 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. Concurrency</td></tr></table></div></body></html>

58
libstdc++-v3/doc/html/manual/ext_io.html
View file

@ -1,9 +1,9 @@
<?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. Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_iterators.html" title="Chapter 38. Iterators" /><link rel="next" href="ext_demangling.html" title="Chapter 40. Demangling" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 39. Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_iterators.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 26. Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_iterators.html" title="Chapter 25. Iterators" /><link rel="next" href="ext_demangling.html" title="Chapter 27. Demangling" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 26. Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_iterators.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_demangling.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 39. Input and Output"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.io"></a>Chapter 39. Input and Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_io.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="ext_demangling.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 26. Input and Output"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.io"></a>Chapter 26. Input and Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ext_io.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" title="Derived filebufs"><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
@ -13,38 +13,38 @@
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 class="itemizedlist" type="disc"><li class="listitem"><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 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 class="itemizedlist" type="circle"><li class="listitem"><p><code class="code">__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE
</p></li><li class="listitem"><p><code class="code">ios_base::openmode M </code>
// same as all the other uses of openmode
</p></li><li class="listitem"><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>.
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 class="itemizedlist" type="circle"><li class="listitem"><p><code class="code">__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE
</p></li><li class="listitem"><p><code class="code">ios_base::openmode M </code>
// same as all the other uses of openmode
</p></li><li class="listitem"><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 class="listitem"><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.
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 class="listitem"><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/a00074.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.
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/a00074.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 RWLock 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="ext_iterators.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="ext_demangling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. Iterators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 40. Demangling</td></tr></table></div></body></html>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_iterators.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="ext_demangling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 25. Iterators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 27. Demangling</td></tr></table></div></body></html>

6
libstdc++-v3/doc/html/manual/ext_iterators.html
View file

@ -1,9 +1,9 @@
<?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. Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_numerics.html" title="Chapter 37. Numerics" /><link rel="next" href="ext_io.html" title="Chapter 39. Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 38. Iterators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_numerics.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 25. Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_numerics.html" title="Chapter 24. Numerics" /><link rel="next" href="ext_io.html" title="Chapter 26. Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 25. Iterators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_numerics.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_io.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 38. Iterators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.iterators"></a>Chapter 38. Iterators</h2></div></div></div><p>24.3.2 describes <code class="code">struct iterator</code>, which didn't exist in the
</th><td width="20%" align="right"> <a accesskey="n" href="ext_io.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 25. Iterators"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.iterators"></a>Chapter 25. 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:
@ -11,4 +11,4 @@
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="ext_numerics.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="ext_io.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 37. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 39. Input and Output</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext_numerics.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="ext_io.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 26. Input and Output</td></tr></table></div></body></html>

6
libstdc++-v3/doc/html/manual/ext_numerics.html
View file

@ -1,9 +1,9 @@
<?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. Numerics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="ext_algorithms.html" title="Chapter 36. Algorithms" /><link rel="next" href="ext_iterators.html" title="Chapter 38. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 37. Numerics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_algorithms.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 24. Numerics</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="ext_algorithms.html" title="Chapter 23. Algorithms" /><link rel="next" href="ext_iterators.html" title="Chapter 25. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 24. Numerics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ext_algorithms.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_iterators.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 37. Numerics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.numerics"></a>Chapter 37. Numerics</h2></div></div></div><p>26.4, the generalized numeric operations such as accumulate, are extended
</th><td width="20%" align="right"> <a accesskey="n" href="ext_iterators.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 24. Numerics"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.numerics"></a>Chapter 24. 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);
@ -17,4 +17,4 @@
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="ext_algorithms.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="ext_iterators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 36. Algorithms </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Iterators</td></tr></table></div></body></html>
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="ext_algorithms.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="ext_iterators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 23. Algorithms </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 25. Iterators</td></tr></table></div></body></html>

14
libstdc++-v3/doc/html/manual/ext_utilities.html
View file

@ -1,19 +1,19 @@
<?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. Utilities</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII.  Extensions" /><link rel="prev" href="bk01pt12ch34s03.html" title="Deprecated HP/SGI" /><link rel="next" href="ext_algorithms.html" title="Chapter 36. Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 35. Utilities</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch34s03.html">Prev</a> </td><th width="60%" align="center">Part XII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 22. Utilities</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part III.  Extensions" /><link rel="prev" href="bk01pt03ch21s03.html" title="Deprecated HP/SGI" /><link rel="next" href="ext_algorithms.html" title="Chapter 23. Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 22. Utilities</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch21s03.html">Prev</a> </td><th width="60%" align="center">Part III. 
Extensions
</th><td width="20%" align="right"> <a accesskey="n" href="ext_algorithms.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 35. Utilities"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.util"></a>Chapter 35. Utilities</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="ext_algorithms.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 22. Utilities"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.util"></a>Chapter 22. 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 class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">identity_element</code> for addition and multiplication. *
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">identity_element</code> for addition and multiplication. *
</p></li><li class="listitem"><p>The functor <code class="code">identity</code>, whose <code class="code">operator()</code>
returns the argument unchanged. *
returns the argument unchanged. *
</p></li><li class="listitem"><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 class="listitem"><p><code class="code">select1st</code> and <code class="code">select2nd</code>, to strip pairs. *
and <code class="code">compose2</code>. *
</p></li><li class="listitem"><p><code class="code">select1st</code> and <code class="code">select2nd</code>, to strip pairs. *
</p></li><li class="listitem"><p><code class="code">project1st</code> and <code class="code">project2nd</code>. * </p></li><li class="listitem"><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>,
@ -38,4 +38,4 @@ get_temporary_buffer(5, (int*)0);
</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="bk01pt12ch34s03.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="ext_algorithms.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 36. Algorithms</td></tr></table></div></body></html>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch21s03.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="ext_algorithms.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 23. Algorithms</td></tr></table></div></body></html>

8
libstdc++-v3/doc/html/manual/extensions.html
View file

File diff suppressed because one or more lines are too long

723
libstdc++-v3/doc/html/manual/facets.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Part VI.  Localization" /><link rel="prev" href="locales.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="locales.html">Prev</a> </td><th width="60%" align="center">Part VI. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Facets</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Chapter 8.  Localization" /><link rel="prev" href="localization.html" title="Chapter 8.  Localization" /><link rel="next" href="containers.html" title="Chapter 9.  Containers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Facets</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="localization.html">Prev</a> </td><th width="60%" align="center">Chapter 8. 
Localization
</th><td width="20%" align="right"> <a accesskey="n" href="codecvt.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 15. Facets aka Categories"><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="facets.html#manual.localization.facet.ctype">ctype</a></span></dt><dd><dl><dt><span class="sect2"><a href="facets.html#facet.ctype.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="facets.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" title="ctype"><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" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.impl"></a>Implementation</h3></div></div></div><div class="sect3" title="Specializations"><div class="titlepage"><div><div><h4 class="title"><a id="id602134"></a>Specializations</h4></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="containers.html">Next</a></td></tr></table><hr /></div><div class="section" title="Facets"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.localization.facet"></a>Facets</h2></div></div></div><div class="section" title="ctype"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.facet.ctype"></a>ctype</h3></div></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.impl"></a>Implementation</h4></div></div></div><div class="section" title="Specializations"><div class="titlepage"><div><div><h5 class="title"><a id="id503472"></a>Specializations</h5></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
@ -28,50 +28,725 @@ 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" title="Future"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
How to deal with the global locale issue?
</p></li><li class="listitem"><p>
</p></div></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.future"></a>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
How to deal with the global locale issue?
</p></li><li class="listitem"><p>
How to deal with different types than char, wchar_t? </p></li><li class="listitem"><p>
Overlap between codecvt/ctype: narrow/widen
</p></li><li class="listitem"><p>
Overlap between codecvt/ctype: narrow/widen
</p></li><li class="listitem"><p>
Mask typedef in codecvt_base, argument types in codecvt. what
is know about this type?
</p></li><li class="listitem"><p>
is know about this type?
</p></li><li class="listitem"><p>
Why mask* argument in codecvt?
</p></li><li class="listitem"><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 class="listitem"><p>
this class?
</p></li><li class="listitem"><p>
Get the ctype&lt;wchar_t&gt;::mask stuff under control. Need to
make some kind of static table, and not do lookup every time
somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt;
</p></li><li class="listitem"><p>
redefine mask for ctype&lt;wchar_t&gt;
</p></li><li class="listitem"><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" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id721212"></a><p><span class="title"><i>
</p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.ctype.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id379548"></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" title="Correspondence"><a id="id611041"></a><p><span class="title"><i>
</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" title="Correspondence"><a id="id449311"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id612309"></a><p><span class="title"><i>
</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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id416640"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id612328"></a><p><span class="title"><i>
</i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id416658"></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" title="The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)"><a id="id626861"></a><p><span class="title"><i>
The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
</i>. </span><span class="copyright">Copyright © 1999
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid">
</i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id497267"></a><p><span class="biblioid">
<a class="ulink" href="http://www.unix.org/version3/ieee_std.html" target="_top">
<em class="citetitle">
The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
</em>
</a>
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id626888"></a><p><span class="title"><i>
. </span><span class="copyright">Copyright © 1999
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id381518"></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" title="Standard C++ IOStreams and Locales"><a id="id655841"></a><p><span class="title"><i>
. </span></span></p></div><div class="biblioentry" title="Standard C++ IOStreams and Locales"><a id="id503670"></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="locales.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>
. </span></span></p></div></div></div><div class="section" title="codecvt"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.facet.codecvt"></a>codecvt</h3></div></div></div><p>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
attempts to detail conversions between the implementation-defined wide
characters (hereafter referred to as wchar_t) and the standard type
char that is so beloved in classic <span class="quote">“<span class="quote">C</span>”</span> (which can now be
referred to as narrow characters.) This document attempts to describe
how the GNU libstdc++ implementation deals with the conversion between
wide and narrow characters, and also presents a framework for dealing
with the huge number of other encodings that iconv can convert,
including Unicode and UTF8. Design issues and requirements are
addressed, and examples of correct usage for both the required
specializations for wide and narrow characters and the
implementation-provided extended functionality are given.
</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.req"></a>Requirements</h4></div></div></div><p>
Around page 425 of the C++ Standard, this charming heading comes into view:
</p><div class="blockquote"><blockquote class="blockquote"><p>
22.2.1.5 - Template class codecvt
</p></blockquote></div><p>
The text around the codecvt definition gives some clues:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-1- The class codecvt&lt;internT,externT,stateT&gt; is for use when
converting from one codeset to another, such as from wide characters
to multibyte characters, between wide character encodings such as
Unicode and EUC.
</em></span>
</p></blockquote></div><p>
Hmm. So, in some unspecified way, Unicode encodings and
translations between other character sets should be handled by this
class.
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-2- The stateT argument selects the pair of codesets being mapped between.
</em></span>
</p></blockquote></div><p>
Ah ha! Another clue...
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-3- The instantiations required in the Table ??
(lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and
codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
native character set. codecvt&lt;char,char,mbstate_t&gt; implements a
degenerate conversion; it does not convert at
all. codecvt&lt;wchar_t,char,mbstate_t&gt; converts between the native
character sets for tiny and wide characters. Instantiations on
mbstate_t perform conversion between encodings known to the library
implementor. Other encodings can be converted by specializing on a
user-defined stateT type. The stateT object can contain any state that
is useful to communicate to or from the specialized do_convert member.
</em></span>
</p></blockquote></div><p>
At this point, a couple points become clear:
</p><p>
One: The standard clearly implies that attempts to add non-required
(yet useful and widely used) conversions need to do so through the
third template parameter, stateT.</p><p>
Two: The required conversions, by specifying mbstate_t as the third
template parameter, imply an implementation strategy that is mostly
(or wholly) based on the underlying C library, and the functions
mcsrtombs and wcsrtombs in particular.</p></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.design"></a>Design</h4></div></div></div><div class="section" title="wchar_t Size"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.wchar_t_size"></a><span class="type">wchar_t</span> Size</h5></div></div></div><p>
The simple implementation detail of wchar_t's size seems to
repeatedly confound people. Many systems use a two byte,
unsigned integral type to represent wide characters, and use an
internal encoding of Unicode or UCS2. (See AIX, Microsoft NT,
Java, others.) Other systems, use a four byte, unsigned integral
type to represent wide characters, and use an internal encoding
of UCS4. (GNU/Linux systems using glibc, in particular.) The C
programming language (and thus C++) does not specify a specific
size for the type wchar_t.
</p><p>
Thus, portable C++ code cannot assume a byte size (or endianness) either.
</p></div><div class="section" title="Support for Unicode"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.unicode"></a>Support for Unicode</h5></div></div></div><p>
Probably the most frequently asked question about code conversion
is: "So dudes, what's the deal with Unicode strings?"
The dude part is optional, but apparently the usefulness of
Unicode strings is pretty widely appreciated. Sadly, this specific
encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10,
etc etc etc) are not mentioned in the C++ standard.
</p><p>
A couple of comments:
</p><p>
The thought that all one needs to convert between two arbitrary
codesets is two types and some kind of state argument is
unfortunate. In particular, encodings may be stateless. The naming
of the third parameter as stateT is unfortunate, as what is really
needed is some kind of generalized type that accounts for the
issues that abstract encodings will need. The minimum information
that is required includes:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Identifiers for each of the codesets involved in the
conversion. For example, using the iconv family of functions
from the Single Unix Specification (what used to be called
X/Open) hosted on the GNU/Linux operating system allows
bi-directional mapping between far more than the following
tantalizing possibilities:
</p><p>
(An edited list taken from <code class="code">`iconv --list`</code> on a
Red Hat 6.2/Intel system:
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16).
</pre></blockquote></div><p>
For iconv-based implementations, string literals for each of the
encodings (i.e. "UCS-2" and "UTF-8") are necessary,
although for other,
non-iconv implementations a table of enumerated values or some other
mechanism may be required.
</p></li><li class="listitem"><p>
Maximum length of the identifying string literal.
</p></li><li class="listitem"><p>
Some encodings require explicit endian-ness. As such, some kind
of endian marker or other byte-order marker will be necessary. See
"Footnotes for C/C++ developers" in Haible for more information on
UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
however implementations, most notably Microsoft, vary.)
</p></li><li class="listitem"><p>
Types representing the conversion state, for conversions involving
the machinery in the "C" library, or the conversion descriptor, for
conversions using iconv (such as the type iconv_t.) Note that the
conversion descriptor encodes more information than a simple encoding
state type.
</p></li><li class="listitem"><p>
Conversion descriptors for both directions of encoding. (i.e., both
UCS-2 to UTF-8 and UTF-8 to UCS-2.)
</p></li><li class="listitem"><p>
Something to indicate if the conversion requested if valid.
</p></li><li class="listitem"><p>
Something to represent if the conversion descriptors are valid.
</p></li><li class="listitem"><p>
Some way to enforce strict type checking on the internal and
external types. As part of this, the size of the internal and
external types will need to be known.
</p></li></ul></div></div><div class="section" title="Other Issues"><div class="titlepage"><div><div><h5 class="title"><a id="codecvt.design.issues"></a>Other Issues</h5></div></div></div><p>
In addition, multi-threaded and multi-locale environments also impact
the design and requirements for code conversions. In particular, they
affect the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt;
when implemented using standard "C" functions.
</p><p>
Three problems arise, one big, one of medium importance, and one small.
</p><p>
First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue.
</p><p>
Of medium concern, in the grand scope of things, is that the functions
used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise
incorrect. Yikes!
</p><p>
The last, and fundamental problem, is the assumption of a global
locale for all the "C" functions referenced above. For something like
C++ iostreams (where codecvt is explicitly used) the notion of
multiple locales is fundamental. In practice, most users may not run
into this limitation. However, as a quality of implementation issue,
the GNU C++ library would like to offer a solution that allows
multiple locales and or simultaneous usage with computationally
correct results. In short, libstdc++ is trying to offer, as an
option, a high-quality implementation, damn the additional complexity!
</p><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></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.impl"></a>Implementation</h4></div></div></div><p>
The two required specializations are implemented as follows:
</p><p>
<code class="code">
codecvt&lt;char, char, mbstate_t&gt;
</code>
</p><p>
This is a degenerate (i.e., does nothing) specialization. Implementing
this was a piece of cake.
</p><p>
<code class="code">
codecvt&lt;char, wchar_t, mbstate_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. As such, libstdc++ implements a partial specialization
of the codecvt class with and iconv wrapper class, encoding_state as the
third template parameter.
</p><p>
This implementation should be standards conformant. First of all, the
standard explicitly points out that instantiations on the third
template parameter, stateT, are the proper way to implement
non-required conversions. Second of all, the standard says (in Chapter
17) that partial specializations of required classes are a-ok. Third
of all, the requirements for the stateT type elsewhere in the standard
(see 21.1.2 traits typedefs) only indicate that this type be copy
constructible.
</p><p>
As such, the type encoding_state is defined as a non-templatized, POD
type to be used as the third type of a codecvt instantiation. This
type is just a wrapper class for iconv, and provides an easy interface
to iconv functionality.
</p><p>
There are two constructors for encoding_state:
</p><p>
<code class="code">
encoding_state() : __in_desc(0), __out_desc(0)
</code>
</p><p>
This default constructor sets the internal encoding to some default
(currently UCS4) and the external encoding to whatever is returned by
nl_langinfo(CODESET).
</p><p>
<code class="code">
encoding_state(const char* __int, const char* __ext)
</code>
</p><p>
This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for
either argument.
</p><p>
One of the issues with iconv is that the string literals identifying
conversions are not standardized. Because of this, the thought of
mandating and or enforcing some set of pre-determined valid
identifiers seems iffy: thus, a more practical (and non-migraine
inducing) strategy was implemented: end-users can specify any string
(subject to a pre-determined length qualifier, currently 32 bytes) for
encodings. It is up to the user to make sure that these strings are
valid on the target system.
</p><p>
<code class="code">
void
_M_init()
</code>
</p><p>
Strangely enough, this member function attempts to open conversion
descriptors for a given encoding_state object. If the conversion
descriptors are not valid, the conversion descriptors returned will
not be valid and the resulting calls to the codecvt conversion
functions will return error.
</p><p>
<code class="code">
bool
_M_good()
</code>
</p><p>
Provides a way to see if the given encoding_state object has been
properly initialized. If the string literals describing the desired
internal and external encoding are not valid, initialization will
fail, and this will return false. If the internal and external
encodings are valid, but iconv_open could not allocate conversion
descriptors, this will also return false. Otherwise, the object is
ready to convert and will return true.
</p><p>
<code class="code">
encoding_state(const encoding_state&amp;)
</code>
</p><p>
As iconv allocates memory and sets up conversion descriptors, the copy
constructor can only copy the member data pertaining to the internal
and external code conversions, and not the conversion descriptors
themselves.
</p><p>
Definitions for all the required codecvt member functions are provided
for this specialization, and usage of codecvt&lt;internal character type,
external character type, encoding_state&gt; is consistent with other
codecvt usage.
</p></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.use"></a>Use</h4></div></div></div><p>A conversions involving string literal.</p><pre class="programlisting">
typedef codecvt_base::result result;
typedef unsigned short unicode_t;
typedef unicode_t int_type;
typedef char ext_type;
typedef encoding_state state_type;
typedef codecvt&lt;int_type, ext_type, state_type&gt; unicode_codecvt;
const ext_type* e_lit = "black pearl jasmine tea";
int size = strlen(e_lit);
int_type i_lit_base[24] =
{ 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
25856, 24832, 2560
};
const int_type* i_lit = i_lit_base;
const ext_type* efrom_next;
const int_type* ifrom_next;
ext_type* e_arr = new ext_type[size + 1];
ext_type* eto_next;
int_type* i_arr = new int_type[size + 1];
int_type* ito_next;
// construct a locale object with the specialized facet.
locale loc(locale::classic(), new unicode_codecvt);
// sanity check the constructed locale has the specialized facet.
VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
// convert between const char* and unicode strings
unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
initialize_state(state01);
result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
i_arr, i_arr + size, ito_next);
VERIFY( r1 == codecvt_base::ok );
VERIFY( !int_traits::compare(i_arr, i_lit, size) );
VERIFY( efrom_next == e_lit + size );
VERIFY( ito_next == i_arr + size );
</pre></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.future"></a>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
a. things that are sketchy, or remain unimplemented:
do_encoding, max_length and length member functions
are only weakly implemented. I have no idea how to do
this correctly, and in a generic manner. Nathan?
</p></li><li class="listitem"><p>
b. conversions involving std::string
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
how should operators != and == work for string of
different/same encoding?
</p></li><li class="listitem"><p>
what is equal? A byte by byte comparison or an
encoding then byte comparison?
</p></li><li class="listitem"><p>
conversions between narrow, wide, and unicode strings
</p></li></ul></div></li><li class="listitem"><p>
c. conversions involving std::filebuf and std::ostream
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
how to initialize the state object in a
standards-conformant manner?
</p></li><li class="listitem"><p>
how to synchronize the "C" and "C++"
conversion information?
</p></li><li class="listitem"><p>
wchar_t/char internal buffers and conversions between
internal/external buffers?
</p></li></ul></div></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.codecvt.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id413506"></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" title="Correspondence"><a id="id410520"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id410548"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id479822"></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="id479841"></a><p><span class="biblioid">
<a class="ulink" href="http://www.opengroup.org/austin" target="_top">
<em class="citetitle">
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
</em>
</a>
. </span><span class="copyright">Copyright © 2008
The Open Group/The Institute of Electrical and Electronics
Engineers, Inc.
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id401535"></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" title="Standard C++ IOStreams and Locales"><a id="id390266"></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 class="biblioentry"><a id="id486188"></a><p><span class="biblioid">
<a class="ulink" href="http://www.lysator.liu.se/c/na1.html" target="_top">
<em class="citetitle">
A brief description of Normative Addendum 1
</em>
</a>
. </span><span class="author"><span class="firstname">Clive</span> <span class="surname">Feather</span>. </span><span class="pagenums">Extended Character Sets. </span></p></div><div class="biblioentry"><a id="id420899"></a><p><span class="biblioid">
<a class="ulink" href="http://tldp.org/HOWTO/Unicode-HOWTO.html" target="_top">
<em class="citetitle">
The Unicode HOWTO
</em>
</a>
. </span><span class="author"><span class="firstname">Bruno</span> <span class="surname">Haible</span>. </span></p></div><div class="biblioentry"><a id="id404329"></a><p><span class="biblioid">
<a class="ulink" href="http://www.cl.cam.ac.uk/~mgk25/unicode.html" target="_top">
<em class="citetitle">
UTF-8 and Unicode FAQ for Unix/Linux
</em>
</a>
. </span><span class="author"><span class="firstname">Markus</span> <span class="surname">Khun</span>. </span></p></div></div></div><div class="section" title="messages"><div class="titlepage"><div><div><h3 class="title"><a id="manual.localization.facet.messages"></a>messages</h3></div></div></div><p>
The std::messages facet implements message retrieval functionality
equivalent to Java's java.text.MessageFormat .using either GNU gettext
or IEEE 1003.1-200 functions.
</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.req"></a>Requirements</h4></div></div></div><p>
The std::messages facet is probably the most vaguely defined facet in
the standard library. It's assumed that this facility was built into
the standard library in order to convert string literals from one
locale to the other. For instance, converting the "C" locale's
<code class="code">const char* c = "please"</code> to a German-localized <code class="code">"bitte"</code>
during program execution.
</p><div class="blockquote"><blockquote class="blockquote"><p>
22.2.7.1 - Template class messages [lib.locale.messages]
</p></blockquote></div><p>
This class has three public member functions, which directly
correspond to three protected virtual member functions.
</p><p>
The public member functions are:
</p><p>
<code class="code">catalog open(const string&amp;, const locale&amp;) const</code>
</p><p>
<code class="code">string_type get(catalog, int, int, const string_type&amp;) const</code>
</p><p>
<code class="code">void close(catalog) const</code>
</p><p>
While the virtual functions are:
</p><p>
<code class="code">catalog do_open(const string&amp;, const locale&amp;) const</code>
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-1- Returns: A value that may be passed to get() to retrieve a
message, from the message catalog identified by the string name
according to an implementation-defined mapping. The result can be used
until it is passed to close(). Returns a value less than 0 if no such
catalog can be opened.
</em></span>
</p></blockquote></div><p>
<code class="code">string_type do_get(catalog, int, int, const string_type&amp;) const</code>
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-3- Requires: A catalog cat obtained from open() and not yet closed.
-4- Returns: A message identified by arguments set, msgid, and dfault,
according to an implementation-defined mapping. If no such message can
be found, returns dfault.
</em></span>
</p></blockquote></div><p>
<code class="code">void do_close(catalog) const</code>
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
-5- Requires: A catalog cat obtained from open() and not yet closed.
-6- Effects: Releases unspecified resources associated with cat.
-7- Notes: The limit on such resources, if any, is implementation-defined.
</em></span>
</p></blockquote></div></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.design"></a>Design</h4></div></div></div><p>
A couple of notes on the standard.
</p><p>
First, why is <code class="code">messages_base::catalog</code> specified as a typedef
to int? This makes sense for implementations that use
<code class="code">catopen</code>, but not for others. Fortunately, it's not heavily
used and so only a minor irritant.
</p><p>
Second, by making the member functions <code class="code">const</code>, it is
impossible to save state in them. Thus, storing away information used
in the 'open' member function for use in 'get' is impossible. This is
unfortunate.
</p><p>
The 'open' member function in particular seems to be oddly
designed. The signature seems quite peculiar. Why specify a <code class="code">const
string&amp; </code> argument, for instance, instead of just <code class="code">const
char*</code>? Or, why specify a <code class="code">const locale&amp;</code> argument that is
to be used in the 'get' member function? How, exactly, is this locale
argument useful? What was the intent? It might make sense if a locale
argument was associated with a given default message string in the
'open' member function, for instance. Quite murky and unclear, on
reflection.
</p><p>
Lastly, it seems odd that messages, which explicitly require code
conversion, don't use the codecvt facet. Because the messages facet
has only one template parameter, it is assumed that ctype, and not
codecvt, is to be used to convert between character sets.
</p><p>
It is implicitly assumed that the locale for the default message
string in 'get' is in the "C" locale. Thus, all source code is assumed
to be written in English, so translations are always from "en_US" to
other, explicitly named locales.
</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.impl"></a>Implementation</h4></div></div></div><div class="section" title="Models"><div class="titlepage"><div><div><h5 class="title"><a id="messages.impl.models"></a>Models</h5></div></div></div><p>
This is a relatively simple class, on the face of it. The standard
specifies very little in concrete terms, so generic
implementations that are conforming yet do very little are the
norm. Adding functionality that would be useful to programmers and
comparable to Java's java.text.MessageFormat takes a bit of work,
and is highly dependent on the capabilities of the underlying
operating system.
</p><p>
Three different mechanisms have been provided, selectable via
configure flags:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
generic
</p><p>
This model does very little, and is what is used by default.
</p></li><li class="listitem"><p>
gnu
</p><p>
The gnu model is complete and fully tested. It's based on the
GNU gettext package, which is part of glibc. It uses the
functions <code class="code">textdomain, bindtextdomain, gettext</code> to
implement full functionality. Creating message catalogs is a
relatively straight-forward process and is lightly documented
below, and fully documented in gettext's distributed
documentation.
</p></li><li class="listitem"><p>
ieee_1003.1-200x
</p><p>
This is a complete, though untested, implementation based on
the IEEE standard. The functions <code class="code">catopen, catgets,
catclose</code> are used to retrieve locale-specific messages
given the appropriate message catalogs that have been
constructed for their use. Note, the script <code class="code">
po2msg.sed</code> that is part of the gettext distribution can
convert gettext catalogs into catalogs that
<code class="code">catopen</code> can use.
</p></li></ul></div><p>
A new, standards-conformant non-virtual member function signature was
added for 'open' so that a directory could be specified with a given
message catalog. This simplifies calling conventions for the gnu
model.
</p></div><div class="section" title="The GNU Model"><div class="titlepage"><div><div><h5 class="title"><a id="messages.impl.gnu"></a>The GNU Model</h5></div></div></div><p>
The messages facet, because it is retrieving and converting
between characters sets, depends on the ctype and perhaps the
codecvt facet in a given locale. In addition, underlying "C"
library locale support is necessary for more than just the
<code class="code">LC_MESSAGES</code> mask: <code class="code">LC_CTYPE</code> is also
necessary. To avoid any unpleasantness, all bits of the "C" mask
(i.e. <code class="code">LC_ALL</code>) are set before retrieving messages.
</p><p>
Making the message catalogs can be initially tricky, but become
quite simple with practice. For complete info, see the gettext
documentation. Here's an idea of what is required:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Make a source file with the required string literals that need
to be translated. See <code class="code">intl/string_literals.cc</code> for
an example.
</p></li><li class="listitem"><p>
Make initial catalog (see "4 Making the PO Template File" from
the gettext docs).</p><p>
<code class="code"> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
</p></li><li class="listitem"><p>Make language and country-specific locale catalogs.</p><p>
<code class="code">cp libstdc++.pot fr_FR.po</code>
</p><p>
<code class="code">cp libstdc++.pot de_DE.po</code>
</p></li><li class="listitem"><p>
Edit localized catalogs in emacs so that strings are
translated.
</p><p>
<code class="code">emacs fr_FR.po</code>
</p></li><li class="listitem"><p>Make the binary mo files.</p><p>
<code class="code">msgfmt fr_FR.po -o fr_FR.mo</code>
</p><p>
<code class="code">msgfmt de_DE.po -o de_DE.mo</code>
</p></li><li class="listitem"><p>Copy the binary files into the correct directory structure.</p><p>
<code class="code">cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code>
</p><p>
<code class="code">cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code>
</p></li><li class="listitem"><p>Use the new message catalogs.</p><p>
<code class="code">locale loc_de("de_DE");</code>
</p><p>
<code class="code">
use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
</code>
</p></li></ul></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.use"></a>Use</h4></div></div></div><p>
A simple example using the GNU model of message conversion.
</p><pre class="programlisting">
#include &lt;iostream&gt;
#include &lt;locale&gt;
using namespace std;
void test01()
{
typedef messages&lt;char&gt;::catalog catalog;
const char* dir =
"/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
const locale loc_de("de_DE");
const messages&lt;char&gt;&amp; mssg_de = use_facet&lt;messages&lt;char&gt; &gt;(loc_de);
catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
string s01 = mssg_de.get(cat_de, 0, 0, "please");
string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
cout &lt;&lt; "please in german:" &lt;&lt; s01 &lt;&lt; '\n';
cout &lt;&lt; "thank you in german:" &lt;&lt; s02 &lt;&lt; '\n';
mssg_de.close(cat_de);
}
</pre></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.future"></a>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Things that are sketchy, or remain unimplemented:
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
_M_convert_from_char, _M_convert_to_char are in flux,
depending on how the library ends up doing character set
conversions. It might not be possible to do a real character
set based conversion, due to the fact that the template
parameter for messages is not enough to instantiate the
codecvt facet (1 supplied, need at least 2 but would prefer
3).
</p></li><li class="listitem"><p>
There are issues with gettext needing the global locale set
to extract a message. This dependence on the global locale
makes the current "gnu" model non MT-safe. Future versions
of glibc, i.e. glibc 2.3.x will fix this, and the C++ library
bits are already in place.
</p></li></ul></div></li><li class="listitem"><p>
Development versions of the GNU "C" library, glibc 2.3 will allow
a more efficient, MT implementation of std::messages, and will
allow the removal of the _M_name_messages data member. If this is
done, it will change the library ABI. The C++ parts to support
glibc 2.3 have already been coded, but are not in use: once this
version of the "C" library is released, the marked parts of the
messages implementation can be switched over to the new "C"
library functionality.
</p></li><li class="listitem"><p>
At some point in the near future, std::numpunct will probably use
std::messages facilities to implement truename/falsename
correctly. This is currently not done, but entries in
libstdc++.pot have already been made for "true" and "false" string
literals, so all that remains is the std::numpunct coding and the
configure/make hassles to make the installed library search its
own catalog. Currently the libstdc++.mo catalog is only searched
for the testsuite cases involving messages members.
</p></li><li class="listitem"><p> The following member functions:</p><p>
<code class="code">
catalog
open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
</code>
</p><p>
<code class="code">
catalog
open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
</code>
</p><p>
Don't actually return a "value less than 0 if no such catalog
can be opened" as required by the standard in the "gnu"
model. As of this writing, it is unknown how to query to see
if a specified message catalog exists using the gettext
package.
</p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="facet.messages.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id400918"></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" title="Correspondence"><a id="id508558"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id417528"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id417546"></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="id417565"></a><p><span class="biblioid">
<a class="ulink" href="http://www.opengroup.org/austin" target="_top">
<em class="citetitle">
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
</em>
</a>
. </span><span class="copyright">Copyright © 2008
The Open Group/The Institute of Electrical and Electronics
Engineers, Inc.
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id386723"></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" title="Standard C++ IOStreams and Locales"><a id="id403269"></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 class="biblioentry"><a id="id471633"></a><p><span class="biblioid">
<a class="ulink" href="http://java.sun.com/reference/api/index.html" target="_top">
<em class="citetitle">
API Specifications, Java Platform
</em>
</a>
. </span><span class="pagenums">java.util.Properties, java.text.MessageFormat,
java.util.Locale, java.util.ResourceBundle
. </span></p></div><div class="biblioentry"><a id="id471656"></a><p><span class="biblioid">
<a class="ulink" href="http://www.gnu.org/software/gettext/" target="_top">
<em class="citetitle">
GNU gettext tools, version 0.10.38, Native Language Support
Library and Tools.
</em>
</a>
. </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="localization.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="containers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. 
Localization
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9. 
Containers
</td></tr></table></div></body></html>

114
libstdc++-v3/doc/html/manual/fstreams.html
View file

@ -1,9 +1,9 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI.  Input and Output" /><link rel="prev" href="stringstreams.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="stringstreams.html">Prev</a> </td><th width="60%" align="center">Part XI. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>File Based Streams</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Chapter 13.  Input and Output" /><link rel="prev" href="stringstreams.html" title="Memory Based Streams" /><link rel="next" href="io_and_c.html" title="Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">File Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="stringstreams.html">Prev</a> </td><th width="60%" align="center">Chapter 13. 
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" title="Chapter 27. File Based Streams"><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="fstreams.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></dl></div><div class="sect1" title="Copying a File"><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>
</th><td width="20%" align="right"> <a accesskey="n" href="io_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="File Based Streams"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.io.filestreams"></a>File Based Streams</h2></div></div></div><div class="sect2" title="Copying a File"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.copying_a_file"></a>Copying a File</h3></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):
@ -22,7 +22,7 @@
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
handle formatting, nothing else. In chaptericular, 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
@ -31,13 +31,13 @@
</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
buffers. This allows polymorphic behavior on the chapter 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.
behavior, since that chaptericular &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
@ -45,8 +45,106 @@
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
</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="stringstreams.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>
</p></div><div class="sect2" title="Binary Input and Output"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.filestreams.binary"></a>Binary Input and Output</h3></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"
covers a lot of ground), 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 chapter 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 class="itemizedlist" type="disc"><li class="listitem"><p><span class="quote">“<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>”</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 class="listitem"><p>
<span class="quote">“<span class="quote">Build the file structure in memory, then
<code class="code">mmap()</code> the file and copy the
structure.
</span>”</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 class="listitem"><p>
<span class="quote">“<span class="quote">Use streambufs, that's what they're there for.</span>”</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.
</p><p>
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/group/comp.std.c++/browse_thread/thread/f87b4abd7954a87/946a3eb9921e382d?q=comp.std.c%2B%2B+binary+iostream#946a3eb9921e382d" target="_top">this</a>
post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
</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></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="stringstreams.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="io_and_c.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">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"> Interacting with C</td></tr></table></div></body></html>

15
libstdc++-v3/doc/html/manual/functors.html
View file

@ -1,15 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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="pairs.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="pairs.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 9. Functors"><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="pairs.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>

43
libstdc++-v3/doc/html/manual/fundamental_types.html
View file

@ -1,43 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" 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" title="Chapter 4. Types"><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="fundamental_types.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" title="Fundamental Types"><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 class="itemizedlist" type="disc"><li class="listitem"><p>
char
</p></li><li class="listitem"><p>
signed char
</p></li><li class="listitem"><p>
unsigned char
</p></li><li class="listitem"><p>
signed short
</p></li><li class="listitem"><p>
signed int
</p></li><li class="listitem"><p>
signed long
</p></li><li class="listitem"><p>
unsigned short
</p></li><li class="listitem"><p>
unsigned int
</p></li><li class="listitem"><p>
unsigned long
</p></li><li class="listitem"><p>
bool
</p></li><li class="listitem"><p>
wchar_t
</p></li><li class="listitem"><p>
float
</p></li><li class="listitem"><p>
double
</p></li><li class="listitem"><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>

11
libstdc++-v3/doc/html/manual/generalized_numeric_operations.html
View file

@ -1,15 +1,15 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X.  Numerics" /><link rel="prev" href="complex.html" title="Chapter 21. Complex" /><link rel="next" href="numerics_and_c.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="complex.html">Prev</a> </td><th width="60%" align="center">Part X. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Generalized Operations</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Chapter 12.  Numerics" /><link rel="prev" href="numerics.html" title="Chapter 12.  Numerics" /><link rel="next" href="numerics_and_c.html" title="Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Generalized Operations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><th width="60%" align="center">Chapter 12. 
Numerics
</th><td width="20%" align="right"> <a accesskey="n" href="numerics_and_c.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 22. Generalized Operations"><div class="titlepage"><div><div><h2 class="title"><a id="manual.numerics.generalized_ops"></a>Chapter 22. Generalized Operations</h2></div></div></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="numerics_and_c.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Generalized Operations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.numerics.generalized_ops"></a>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 class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">accumulate</code></p></li><li class="listitem"><p><code class="code">inner_product</code></p></li><li class="listitem"><p><code class="code">partial_sum</code></p></li><li class="listitem"><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><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">accumulate</code></p></li><li class="listitem"><p><code class="code">inner_product</code></p></li><li class="listitem"><p><code class="code">chapterial_sum</code></p></li><li class="listitem"><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();
@ -26,4 +26,7 @@
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="complex.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="numerics_and_c.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>
</p></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="numerics_and_c.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. 
Numerics
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Interacting with C</td></tr></table></div></body></html>

86
libstdc++-v3/doc/html/manual/internals.html
View file

@ -41,7 +41,7 @@ in <code class="code">sparc-sun-solaris2.8</code>. If the new directory is name
OS portion of the triplet (the default), then nothing needs to be changed.
</p><p>The first file to create in this directory, should be called
<code class="code">os_defines.h</code>. This file contains basic macro definitions
that are required to allow the C++ library to work with your C library.
that are required to allow the C++ library to work with your C library.
</p><p>Several libstdc++ source files unconditionally define the macro
<code class="code">_POSIX_SOURCE</code>. On many systems, defining this macro causes
large portions of the C library header files to be eliminated
@ -91,7 +91,7 @@ are exposing proper support for the related set of functions. If defined,
it must be 0 while bootstrapping the compiler/rebuilding the library.
</p><p>Finally, you should bracket the entire file in an include-guard, like
this:
</p><pre class="programlisting">
</p><pre class="programlisting">
#ifndef _GLIBCXX_OS_DEFINES
#define _GLIBCXX_OS_DEFINES
@ -131,7 +131,7 @@ upper-case, lower-case, alphabetic, etc. The <code class="code">ctype_base.h</c
file gives the type of the integer, and the values of the various bit
masks. You will have to peer at your own <code class="code">&lt;ctype.h&gt;</code> to figure out
how to define the values required by this file.
</p><p>The <code class="code">ctype_base.h</code> header file does not need include guards.
</p><p>The <code class="code">ctype_base.h</code> header file does not need include guards.
It should contain a single <code class="code">struct</code> definition called
<code class="code">ctype_base</code>. This <code class="code">struct</code> should contain two type
declarations, and one enumeration declaration, like this example, taken
@ -141,20 +141,20 @@ from the IRIX configuration:
{
typedef unsigned int mask;
typedef int* __to_type;
enum
{
space = _ISspace,
print = _ISprint,
cntrl = _IScntrl,
upper = _ISupper,
lower = _ISlower,
alpha = _ISalpha,
digit = _ISdigit,
punct = _ISpunct,
xdigit = _ISxdigit,
alnum = _ISalnum,
graph = _ISgraph
space = _ISspace,
print = _ISprint,
cntrl = _IScntrl,
upper = _ISupper,
lower = _ISlower,
alpha = _ISalpha,
digit = _ISdigit,
punct = _ISpunct,
xdigit = _ISxdigit,
alnum = _ISalnum,
graph = _ISgraph
};
};
</pre><p>The <code class="code">mask</code> type is the type of the elements in the table. If your
@ -176,14 +176,14 @@ function that must be written is the <code class="code">ctype&lt;char&gt;::ctype
constructor. Here is the IRIX example:
</p><pre class="programlisting">
ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
size_t __refs = 0)
size_t __refs = 0)
: _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
_M_toupper(NULL),
_M_tolower(NULL),
_M_ctable(NULL),
_M_table(!__table
? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
: __table)
_M_toupper(NULL),
_M_tolower(NULL),
_M_ctable(NULL),
_M_table(!__table
? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
: __table)
{ }
</pre><p>There are two parts of this that you might choose to alter. The first,
and most important, is the line involving <code class="code">__libc_attr</code>. That is
@ -199,7 +199,7 @@ lower-case, and vice versa. Here are the IRIX versions:
char
ctype&lt;char&gt;::do_toupper(char __c) const
{ return _toupper(__c); }
char
ctype&lt;char&gt;::do_tolower(char __c) const
{ return _tolower(__c); }
@ -215,21 +215,21 @@ machinery to do that on your system:
ctype&lt;char&gt;::do_toupper(char* __low, const char* __high) const
{
while (__low &lt; __high)
{
*__low = do_toupper(*__low);
++__low;
}
{
*__low = do_toupper(*__low);
++__low;
}
return __high;
}
const char*
ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
{
while (__low &lt; __high)
{
*__low = do_tolower(*__low);
++__low;
}
{
*__low = do_tolower(*__low);
++__low;
}
return __high;
}
</pre><p>You must also provide the <code class="code">ctype_inline.h</code> file, which
@ -244,7 +244,7 @@ properties; they are analogous to the functions like <code class="code">isalpha<
ctype&lt;char&gt;::
is(mask __m, char __c) const throw()
{ return (_M_table)[(unsigned char)(__c)] &amp; __m; }
</pre><p>The <code class="code">_M_table</code> is the table passed in above, in the constructor.
</pre><p>The <code class="code">_M_table</code> is the table passed in above, in the constructor.
This is the table that contains the bitmasks for each character. The
implementation here should work on all systems.
</p><p>The next function is:
@ -254,7 +254,7 @@ implementation here should work on all systems.
is(const char* __low, const char* __high, mask* __vec) const throw()
{
while (__low &lt; __high)
*__vec++ = (_M_table)[(unsigned char)(*__low++)];
*__vec++ = (_M_table)[(unsigned char)(*__low++)];
return __high;
}
</pre><p>This function is similar; it copies the masks for all the characters
@ -267,16 +267,16 @@ from <code class="code">__low</code> up until <code class="code">__high</code> i
scan_is(mask __m, const char* __low, const char* __high) const throw()
{
while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
++__low;
++__low;
return __low;
}
const char*
ctype&lt;char&gt;::
scan_not(mask __m, const char* __low, const char* __high) const throw()
{
while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
++__low;
++__low;
return __low;
}
</pre></div><div class="sect2" title="Thread Safety"><div class="titlepage"><div><div><h3 class="title"><a id="internals.thread_safety"></a>Thread Safety</h3></div></div></div><p>The C++ library string functionality requires a couple of atomic
@ -312,7 +312,7 @@ type, and two functions.
</p><p>The type is <code class="code">_Atomic_word</code>. Here is the version used on IRIX:
</p><pre class="programlisting">
typedef long _Atomic_word;
</pre><p>This type must be a signed integral type supporting atomic operations.
</pre><p>This type must be a signed integral type supporting atomic operations.
If you're using the OS approach, use the same type used by your system's
primitives. Otherwise, use the type for which your CPU provides atomic
primitives.
@ -327,7 +327,7 @@ must be equivalent to those provided here, but using atomic operations:
*__mem += __val;
return __result;
}
static inline void
__attribute__ ((__unused__))
__atomic_add (_Atomic_word* __mem, int __val)
@ -335,18 +335,18 @@ must be equivalent to those provided here, but using atomic operations:
*__mem += __val;
}
</pre></div><div class="sect2" title="Numeric Limits"><div class="titlepage"><div><div><h3 class="title"><a id="internals.numeric_limits"></a>Numeric Limits</h3></div></div></div><p>The C++ library requires information about the fundamental data types,
such as the minimum and maximum representable values of each type.
such as the minimum and maximum representable values of each type.
You can define each of these values individually, but it is usually
easiest just to indicate how many bits are used in each of the data
types and let the library do the rest. For information about the
macros to define, see the top of <code class="code">include/bits/std_limits.h</code>.
</p><p>If you need to define any macros, you can do so in <code class="code">os_defines.h</code>.
</p><p>If you need to define any macros, you can do so in <code class="code">os_defines.h</code>.
However, if all operating systems for your CPU are likely to use the
same values, you can provide a CPU-specific file instead so that you
do not have to provide the same definitions for each operating system.
do not have to provide the same definitions for each operating system.
To take that approach, create a new file called <code class="code">cpu_limits.h</code> in
your CPU configuration directory (see <a class="link" href="internals.html#internals.cpu" title="CPU">CPU</a>).
</p></div><div class="sect2" title="Libtool"><div class="titlepage"><div><div><h3 class="title"><a id="internals.libtool"></a>Libtool</h3></div></div></div><p>The C++ library is compiled, archived and linked with libtool.
</p></div><div class="sect2" title="Libtool"><div class="titlepage"><div><div><h3 class="title"><a id="internals.libtool"></a>Libtool</h3></div></div></div><p>The C++ library is compiled, archived and linked with libtool.
Explaining the full workings of libtool is beyond the scope of this
document, but there are a few, particular bits that are necessary for
porting.

2
libstdc++-v3/doc/html/manual/intro.html
View file

File diff suppressed because one or more lines are too long

120
libstdc++-v3/doc/html/manual/io.html
View file

@ -1,9 +1,121 @@
<?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 XI.  Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt10ch23s02.html" title="C99" /><link rel="next" href="iostream_objects.html" title="Chapter 24. Iostream Objects" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part XI. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 13.  Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="numerics_and_c.html" title="Interacting with C" /><link rel="next" href="streambufs.html" title="Stream Buffers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. 
Input and Output
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch23s02.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="iostream_objects.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part XI.  Input and Output"><div class="titlepage"><div><div><h1 class="title"><a id="manual.io"></a>Part XI. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 13.  Input and Output"><div class="titlepage"><div><div><h2 class="title"><a id="std.io"></a>Chapter 13. 
Input and Output
<a id="id592157" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="iostream_objects.html">24. Iostream Objects</a></span></dt><dt><span class="chapter"><a href="streambufs.html">25. Stream Buffers</a></span></dt><dd><dl><dt><span class="sect1"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch25s02.html">Buffering</a></span></dt></dl></dd><dt><span class="chapter"><a href="stringstreams.html">26. Memory Based Streams</a></span></dt><dd><dl><dt><span class="sect1"><a href="stringstreams.html#manual.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="chapter"><a href="fstreams.html">27. File Based Streams</a></span></dt><dd><dl><dt><span class="sect1"><a href="fstreams.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></dl></dd><dt><span class="chapter"><a href="io_and_c.html">28. Interacting with C</a></span></dt><dd><dl><dt><span class="sect1"><a href="io_and_c.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></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch23s02.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="iostream_objects.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">C99 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 24. Iostream Objects</td></tr></table></div></body></html>
<a id="id497027" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="io.html#std.io.objects">Iostream Objects</a></span></dt><dt><span class="sect1"><a href="streambufs.html">Stream Buffers</a></span></dt><dd><dl><dt><span class="sect2"><a href="streambufs.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="sect2"><a href="streambufs.html#io.streambuf.buffering">Buffering</a></span></dt></dl></dd><dt><span class="sect1"><a href="stringstreams.html">Memory Based Streams</a></span></dt><dd><dl><dt><span class="sect2"><a href="stringstreams.html#std.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></dd><dt><span class="sect1"><a href="fstreams.html">File Based Streams</a></span></dt><dd><dl><dt><span class="sect2"><a href="fstreams.html#std.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="sect2"><a href="fstreams.html#std.io.filestreams.binary">Binary Input and Output</a></span></dt></dl></dd><dt><span class="sect1"><a href="io_and_c.html">Interacting with C</a></span></dt><dd><dl><dt><span class="sect2"><a href="io_and_c.html#std.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="sect2"><a href="io_and_c.html#std.io.c.sync">Performance</a></span></dt></dl></dd></dl></div><div class="sect1" title="Iostream Objects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.io.objects"></a>Iostream Objects</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to
only include the headers you really need. Many people simply include
&lt;iostream&gt; when they don't need to -- and that can <span class="emphasis"><em>penalize
your runtime as well.</em></span> Here are some tips on which header to use
for which situations, starting with the simplest.
</p><p><span class="emphasis"><em>&lt;iosfwd&gt;</em></span> should be included whenever you simply
need the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as
"ofstream" or "basic_streambuf". Like the name
implies, these are forward declarations. (A word to all you fellow
old school programmers: trying to forward declare classes like
"class istream;" won't work. Look in the iosfwd header if
you'd like to know why.) For example,
</p><pre class="programlisting">
#include &lt;iosfwd&gt;
class MyClass
{
....
std::ifstream&amp; input_file;
};
extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
</pre><p><span class="emphasis"><em>&lt;ios&gt;</em></span> declares the base classes for the entire
I/O stream hierarchy, std::ios_base and std::basic_ios&lt;charT&gt;, the
counting types std::streamoff and std::streamsize, the file
positioning type std::fpos, and the various manipulators like
std::hex, std::fixed, std::noshowbase, and so forth.
</p><p>The ios_base class is what holds the format flags, the state flags,
and the functions which change them (setf(), width(), precision(),
etc). You can also store extra data and register callback functions
through ios_base, but that has been historically underused. Anything
which doesn't depend on the type of characters stored is consolidated
here.
</p><p>The template class basic_ios is the highest template class in the
hierarchy; it is the first one depending on the character type, and
holds all general state associated with that type: the pointer to the
polymorphic stream buffer, the facet information, etc.
</p><p><span class="emphasis"><em>&lt;streambuf&gt;</em></span> declares the template class
basic_streambuf, and two standard instantiations, streambuf and
wstreambuf. If you need to work with the vastly useful and capable
stream buffer classes, e.g., to create a new form of storage
transport, this header is the one to include.
</p><p><span class="emphasis"><em>&lt;istream&gt;</em></span>/<span class="emphasis"><em>&lt;ostream&gt;</em></span> are
the headers to include when you are using the &gt;&gt;/&lt;&lt;
interface, or any of the other abstract stream formatting functions.
For example,
</p><pre class="programlisting">
#include &lt;istream&gt;
std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
{
return os &lt;&lt; c.data1() &lt;&lt; c.data2();
}
</pre><p>The std::istream and std::ostream classes are the abstract parents of
the various concrete implementations. If you are only using the
interfaces, then you only need to use the appropriate interface header.
</p><p><span class="emphasis"><em>&lt;iomanip&gt;</em></span> provides "extractors and inserters
that alter information maintained by class ios_base and its derived
classes," such as std::setprecision and std::setw. If you need
to write expressions like <code class="code">os &lt;&lt; setw(3);</code> or
<code class="code">is &gt;&gt; setbase(8);</code>, you must include &lt;iomanip&gt;.
</p><p><span class="emphasis"><em>&lt;sstream&gt;</em></span>/<span class="emphasis"><em>&lt;fstream&gt;</em></span>
declare the six stringstream and fstream classes. As they are the
standard concrete descendants of istream and ostream, you will already
know about them.
</p><p>Finally, <span class="emphasis"><em>&lt;iostream&gt;</em></span> provides the eight standard
global objects (cin, cout, etc). To do this correctly, this header
also provides the contents of the &lt;istream&gt; and &lt;ostream&gt;
headers, but nothing else. The contents of this header look like
</p><pre class="programlisting">
#include &lt;ostream&gt;
#include &lt;istream&gt;
namespace std
{
extern istream cin;
extern ostream cout;
....
// this is explained below
<span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name
}
</pre><p>Now, the runtime penalty mentioned previously: the global objects
must be initialized before any of your own code uses them; this is
guaranteed by the standard. Like any other global object, they must
be initialized once and only once. This is typically done with a
construct like the one above, and the nested class ios_base::Init is
specified in the standard for just this reason.
</p><p>How does it work? Because the header is included before any of your
code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of
your objects. (Global objects are built in the order in which they
are declared, and destroyed in reverse order.) The first time the
constructor runs, the eight stream objects are set up.
</p><p>The <code class="code">static</code> keyword means that each object file compiled
from a source file containing &lt;iostream&gt; will have its own
private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order
of construction across object files (it's one of those pesky NP
problems that make life so interesting), so one copy in each object
file means that the stream objects are guaranteed to be set up before
any of your code which uses them could run, thereby meeting the
requirements of the standard.
</p><p>The penalty, of course, is that after the first copy of
<span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wasted
processor time. The time spent is merely for an increment-and-test
inside a function call, but over several dozen or hundreds of object
files, that time can add up. (It's not in a tight loop, either.)
</p><p>The lesson? Only include &lt;iostream&gt; when you need to use one of
the standard objects in that source file; you'll pay less startup
time. Only include the header files you need to in general; your
compile times will go down when there's less parsing work to do.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="numerics_and_c.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Interacting with C </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Stream Buffers</td></tr></table></div></body></html>

54
libstdc++-v3/doc/html/manual/io_and_c.html
View file

@ -1,11 +1,57 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI.  Input and Output" /><link rel="prev" href="bk01pt11ch27s02.html" title="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="bk01pt11ch27s02.html">Prev</a> </td><th width="60%" align="center">Part XI. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Chapter 13.  Input and Output" /><link rel="prev" href="fstreams.html" title="File Based Streams" /><link rel="next" href="atomics.html" title="Chapter 14.  Atomics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="fstreams.html">Prev</a> </td><th width="60%" align="center">Chapter 13. 
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" title="Chapter 28. Interacting with C"><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="io_and_c.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" title="Using FILE* and file descriptors"><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="ext_io.html" title="Chapter 39. Input and Output">extensions</a> for using
</th><td width="20%" align="right"> <a accesskey="n" href="atomics.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Interacting with C"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.io.c"></a>Interacting with C</h2></div></div></div><div class="sect2" title="Using FILE* and file descriptors"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.c.FILE"></a>Using FILE* and file descriptors</h3></div></div></div><p>
See the <a class="link" href="ext_io.html" title="Chapter 26. 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="bk01pt11ch27s02.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">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>
</p></div><div class="sect2" title="Performance"><div class="titlepage"><div><div><h3 class="title"><a id="std.io.c.sync"></a>Performance</h3></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 counterchapters). File stream
objects that you declare yourself have no such requirement and are fully
buffered.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="fstreams.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="atomics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">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"> Chapter 14. 
Atomics
</td></tr></table></div></body></html>

119
libstdc++-v3/doc/html/manual/iostream_objects.html
View file

@ -1,119 +0,0 @@
<?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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI.  Input and Output" /><link rel="prev" href="io.html" title="Part XI.  Input and Output" /><link rel="next" href="streambufs.html" title="Chapter 25. Stream Buffers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 24. Iostream Objects</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Part XI. 
Input and Output
</th><td width="20%" align="right"> <a accesskey="n" href="streambufs.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 24. Iostream Objects"><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="streambufs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part XI. 
Input and Output
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 25. Stream Buffers</td></tr></table></div></body></html>

129
libstdc++-v3/doc/html/manual/iterators.html
View file

@ -1,9 +1,130 @@
<?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 VIII.  Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bitset.html" title="bitset" /><link rel="next" href="bk01pt08ch19.html" title="Chapter 19. Predefined" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part VIII. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 10.  Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="containers_and_c.html" title="Interacting with C" /><link rel="next" href="algorithms.html" title="Chapter 11.  Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. 
Iterators
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bitset.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt08ch19.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part VIII.  Iterators"><div class="titlepage"><div><div><h1 class="title"><a id="manual.iterators"></a>Part VIII. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="containers_and_c.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 10.  Iterators"><div class="titlepage"><div><div><h2 class="title"><a id="std.iterators"></a>Chapter 10. 
Iterators
<a id="id678897" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="bk01pt08ch19.html">19. Predefined</a></span></dt><dd><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></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bitset.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="bk01pt08ch19.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"> Chapter 19. Predefined</td></tr></table></div></body></html>
<a id="id424800" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="iterators.html#std.iterators.predefined">Predefined</a></span></dt><dd><dl><dt><span class="sect2"><a href="iterators.html#iterators.predefined.vs_pointers">Iterators vs. Pointers</a></span></dt><dt><span class="sect2"><a href="iterators.html#iterators.predefined.end">One Past the End</a></span></dt></dl></dd></dl></div><div class="sect1" title="Predefined"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.iterators.predefined"></a>Predefined</h2></div></div></div><div class="sect2" title="Iterators vs. Pointers"><div class="titlepage"><div><div><h3 class="title"><a id="iterators.predefined.vs_pointers"></a>Iterators vs. Pointers</h3></div></div></div><p>
The following
FAQ <a class="link" href="../faq.html#faq.iterator_as_pod" title="7.1.">entry</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 sect1 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 class="sect2" title="One Past the End"><div class="titlepage"><div><div><h3 class="title"><a id="iterators.predefined.end"></a>One Past the End</h3></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 class="orderedlist" type="1"><li class="listitem"><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 class="listitem"><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 class="listitem"><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 chapter 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></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="containers_and_c.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="algorithms.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Interacting with C </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. 
Algorithms
</td></tr></table></div></body></html>

4
libstdc++-v3/doc/html/manual/license.html
View file

@ -2,7 +2,7 @@
<!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.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="status.html" title="Chapter 1. Status" /><link rel="prev" href="status.html" title="Chapter 1. Status" /><link rel="next" href="bugs.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="status.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td width="20%" align="right"> <a accesskey="n" href="bugs.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="License"><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.
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>.
@ -94,7 +94,7 @@ requirements of the license of GCC.<br />
<a class="link" href="appendix_gfdl.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>
</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

428
libstdc++-v3/doc/html/manual/locales.html
View file

@ -1,428 +0,0 @@
<?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 14. Locales</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Part VI.  Localization" /><link rel="prev" href="localization.html" title="Part VI.  Localization" /><link rel="next" href="facets.html" title="Chapter 15. Facets aka Categories" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. Locales</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="localization.html">Prev</a> </td><th width="60%" align="center">Part VI. 
Localization
</th><td width="20%" align="right"> <a accesskey="n" href="facets.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 14. Locales"><div class="titlepage"><div><div><h2 class="title"><a id="manual.localization.locales"></a>Chapter 14. Locales</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="locales.html#manual.localization.locales.locale">locale</a></span></dt><dd><dl><dt><span class="sect2"><a href="locales.html#locales.locale.req">Requirements</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.design">Design</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.future">Future</a></span></dt></dl></dd></dl></div><div class="sect1" title="locale"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.locales.locale"></a>locale</h2></div></div></div><p>
Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</p><div class="sect2" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.req"></a>Requirements</h3></div></div></div><p>
Class locale is non-templatized and has two distinct types nested
inside of it:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
class facet
22.1.1.1.2 Class locale::facet
</em></span>
</p></blockquote></div><p>
Facets actually implement locale functionality. For instance, a facet
called numpunct is the data object that can be used to query for the
thousands separator in the locale.
</p><p>
Literally, a facet is strictly defined:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Containing the following public data member:
</p><p>
<code class="code">static locale::id id;</code>
</p></li><li class="listitem"><p>
Derived from another facet:
</p><p>
<code class="code">class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code>
</p></li></ul></div><p>
Of interest in this class are the memory management options explicitly
specified as an argument to facet's constructor. Each constructor of a
facet class takes a std::size_t __refs argument: if __refs == 0, the
facet is deleted when the locale containing it is destroyed. If __refs
== 1, the facet is not destroyed, even when it is no longer
referenced.
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
class id
22.1.1.1.3 - Class locale::id
</em></span>
</p></blockquote></div><p>
Provides an index for looking up specific facets.
</p></div><div class="sect2" title="Design"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.design"></a>Design</h3></div></div></div><p>
The major design challenge is fitting an object-orientated and
non-global locale design on top of POSIX and other relevant standards,
which include the Single Unix (nee X/Open.)
</p><p>
Because C and earlier versions of POSIX fall down so completely,
portability is an issue.
</p></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.impl"></a>Implementation</h3></div></div></div><div class="sect3" title="Interacting with &quot;C&quot; locales"><div class="titlepage"><div><div><h4 class="title"><a id="locale.impl.c"></a>Interacting with "C" locales</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<code class="code">`locale -a`</code> displays available locales.
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
af_ZA
ar_AE
ar_AE.utf8
ar_BH
ar_BH.utf8
ar_DZ
ar_DZ.utf8
ar_EG
ar_EG.utf8
ar_IN
ar_IQ
ar_IQ.utf8
ar_JO
ar_JO.utf8
ar_KW
ar_KW.utf8
ar_LB
ar_LB.utf8
ar_LY
ar_LY.utf8
ar_MA
ar_MA.utf8
ar_OM
ar_OM.utf8
ar_QA
ar_QA.utf8
ar_SA
ar_SA.utf8
ar_SD
ar_SD.utf8
ar_SY
ar_SY.utf8
ar_TN
ar_TN.utf8
ar_YE
ar_YE.utf8
be_BY
be_BY.utf8
bg_BG
bg_BG.utf8
br_FR
bs_BA
C
ca_ES
ca_ES@euro
ca_ES.utf8
ca_ES.utf8@euro
cs_CZ
cs_CZ.utf8
cy_GB
da_DK
da_DK.iso885915
da_DK.utf8
de_AT
de_AT@euro
de_AT.utf8
de_AT.utf8@euro
de_BE
de_BE@euro
de_BE.utf8
de_BE.utf8@euro
de_CH
de_CH.utf8
de_DE
de_DE@euro
de_DE.utf8
de_DE.utf8@euro
de_LU
de_LU@euro
de_LU.utf8
de_LU.utf8@euro
el_GR
el_GR.utf8
en_AU
en_AU.utf8
en_BW
en_BW.utf8
en_CA
en_CA.utf8
en_DK
en_DK.utf8
en_GB
en_GB.iso885915
en_GB.utf8
en_HK
en_HK.utf8
en_IE
en_IE@euro
en_IE.utf8
en_IE.utf8@euro
en_IN
en_NZ
en_NZ.utf8
en_PH
en_PH.utf8
en_SG
en_SG.utf8
en_US
en_US.iso885915
en_US.utf8
en_ZA
en_ZA.utf8
en_ZW
en_ZW.utf8
es_AR
es_AR.utf8
es_BO
es_BO.utf8
es_CL
es_CL.utf8
es_CO
es_CO.utf8
es_CR
es_CR.utf8
es_DO
es_DO.utf8
es_EC
es_EC.utf8
es_ES
es_ES@euro
es_ES.utf8
es_ES.utf8@euro
es_GT
es_GT.utf8
es_HN
es_HN.utf8
es_MX
es_MX.utf8
es_NI
es_NI.utf8
es_PA
es_PA.utf8
es_PE
es_PE.utf8
es_PR
es_PR.utf8
es_PY
es_PY.utf8
es_SV
es_SV.utf8
es_US
es_US.utf8
es_UY
es_UY.utf8
es_VE
es_VE.utf8
et_EE
et_EE.utf8
eu_ES
eu_ES@euro
eu_ES.utf8
eu_ES.utf8@euro
fa_IR
fi_FI
fi_FI@euro
fi_FI.utf8
fi_FI.utf8@euro
fo_FO
fo_FO.utf8
fr_BE
fr_BE@euro
fr_BE.utf8
fr_BE.utf8@euro
fr_CA
fr_CA.utf8
fr_CH
fr_CH.utf8
fr_FR
fr_FR@euro
fr_FR.utf8
fr_FR.utf8@euro
fr_LU
fr_LU@euro
fr_LU.utf8
fr_LU.utf8@euro
ga_IE
ga_IE@euro
ga_IE.utf8
ga_IE.utf8@euro
gl_ES
gl_ES@euro
gl_ES.utf8
gl_ES.utf8@euro
gv_GB
gv_GB.utf8
he_IL
he_IL.utf8
hi_IN
hr_HR
hr_HR.utf8
hu_HU
hu_HU.utf8
id_ID
id_ID.utf8
is_IS
is_IS.utf8
it_CH
it_CH.utf8
it_IT
it_IT@euro
it_IT.utf8
it_IT.utf8@euro
iw_IL
iw_IL.utf8
ja_JP.eucjp
ja_JP.utf8
ka_GE
kl_GL
kl_GL.utf8
ko_KR.euckr
ko_KR.utf8
kw_GB
kw_GB.utf8
lt_LT
lt_LT.utf8
lv_LV
lv_LV.utf8
mi_NZ
mk_MK
mk_MK.utf8
mr_IN
ms_MY
ms_MY.utf8
mt_MT
mt_MT.utf8
nl_BE
nl_BE@euro
nl_BE.utf8
nl_BE.utf8@euro
nl_NL
nl_NL@euro
nl_NL.utf8
nl_NL.utf8@euro
nn_NO
nn_NO.utf8
no_NO
no_NO.utf8
oc_FR
pl_PL
pl_PL.utf8
POSIX
pt_BR
pt_BR.utf8
pt_PT
pt_PT@euro
pt_PT.utf8
pt_PT.utf8@euro
ro_RO
ro_RO.utf8
ru_RU
ru_RU.koi8r
ru_RU.utf8
ru_UA
ru_UA.utf8
se_NO
sk_SK
sk_SK.utf8
sl_SI
sl_SI.utf8
sq_AL
sq_AL.utf8
sr_YU
sr_YU@cyrillic
sr_YU.utf8
sr_YU.utf8@cyrillic
sv_FI
sv_FI@euro
sv_FI.utf8
sv_FI.utf8@euro
sv_SE
sv_SE.iso885915
sv_SE.utf8
ta_IN
te_IN
tg_TJ
th_TH
th_TH.utf8
tl_PH
tr_TR
tr_TR.utf8
uk_UA
uk_UA.utf8
ur_PK
uz_UZ
vi_VN
vi_VN.tcvn
wa_BE
wa_BE@euro
yi_US
zh_CN
zh_CN.gb18030
zh_CN.gbk
zh_CN.utf8
zh_HK
zh_HK.utf8
zh_TW
zh_TW.euctw
zh_TW.utf8
</pre></blockquote></div></li><li class="listitem"><p>
<code class="code">`locale`</code> displays environmental variables that
impact how locale("") will be deduced.
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
LANG=en_US
LC_CTYPE="en_US"
LC_NUMERIC="en_US"
LC_TIME="en_US"
LC_COLLATE="en_US"
LC_MONETARY="en_US"
LC_MESSAGES="en_US"
LC_PAPER="en_US"
LC_NAME="en_US"
LC_ADDRESS="en_US"
LC_TELEPHONE="en_US"
LC_MEASUREMENT="en_US"
LC_IDENTIFICATION="en_US"
LC_ALL=
</pre></blockquote></div></li></ul></div><p>
From Josuttis, p. 697-698, which says, that "there is only *one*
relation (of the C++ locale mechanism) to the C locale mechanism: the
global C locale is modified if a named C++ locale object is set as the
global locale" (emphasis Paolo), that is:
</p><pre class="programlisting">std::locale::global(std::locale(""));</pre><p>affects the C functions as if the following call was made:</p><pre class="programlisting">std::setlocale(LC_ALL, "");</pre><p>
On the other hand, there is *no* vice versa, that is, calling
setlocale has *no* whatsoever on the C++ locale mechanism, in
particular on the working of locale(""), which constructs the locale
object from the environment of the running program, that is, in
practice, the set of LC_ALL, LANG, etc. variable of the shell.
</p></div></div><div class="sect2" title="Future"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Locale initialization: at what point does _S_classic, _S_global
get initialized? Can named locales assume this initialization
has already taken place?
</p></li><li class="listitem"><p>
Document how named locales error check when filling data
members. I.e., a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention?
</p></li><li class="listitem"><p>
Explain how locale aliasing happens. When does "de_DE" use "de"
information? What is the rule for locales composed of just an
ISO language code (say, "de") and locales with both an ISO
language code and ISO country code (say, "de_DE").
</p></li><li class="listitem"><p>
What should non-required facet instantiations do? If the
generic implementation is provided, then how to end-users
provide specializations?
</p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id645730"></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" title="Correspondence"><a id="id610693"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id638635"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id617195"></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" title="The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)"><a id="id617213"></a><p><span class="title"><i>
The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
</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.unix.org/version3/ieee_std.html" target="_top">
</a>
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id713713"></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" title="Standard C++ IOStreams and Locales"><a id="id653680"></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="localization.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="facets.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VI. 
Localization
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Facets aka Categories</td></tr></table></div></body></html>

438
libstdc++-v3/doc/html/manual/localization.html
View file

@ -1,9 +1,439 @@
<?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 VI.  Localization</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01pt05ch13s06.html" title="CString (MFC)" /><link rel="next" href="locales.html" title="Chapter 14. Locales" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part VI. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 8.  Localization</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02.html" title="Part II.  Standard Contents" /><link rel="prev" href="strings.html" title="Chapter 7.  Strings" /><link rel="next" href="facets.html" title="Facets" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. 
Localization
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt05ch13s06.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="locales.html">Next</a></td></tr></table><hr /></div><div class="part" title="Part VI.  Localization"><div class="titlepage"><div><div><h1 class="title"><a id="manual.localization"></a>Part VI. 
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="strings.html">Prev</a> </td><th width="60%" align="center">Part II. 
Standard Contents
</th><td width="20%" align="right"> <a accesskey="n" href="facets.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 8.  Localization"><div class="titlepage"><div><div><h2 class="title"><a id="std.localization"></a>Chapter 8. 
Localization
<a id="id655346" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="locales.html">14. Locales</a></span></dt><dd><dl><dt><span class="sect1"><a href="locales.html#manual.localization.locales.locale">locale</a></span></dt><dd><dl><dt><span class="sect2"><a href="locales.html#locales.locale.req">Requirements</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.design">Design</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="locales.html#locales.locale.future">Future</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="facets.html">15. Facets aka Categories</a></span></dt><dd><dl><dt><span class="sect1"><a href="facets.html#manual.localization.facet.ctype">ctype</a></span></dt><dd><dl><dt><span class="sect2"><a href="facets.html#facet.ctype.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="facets.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></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt05ch13s06.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="locales.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CString (MFC) </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. Locales</td></tr></table></div></body></html>
<a id="id443947" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="localization.html#std.localization.locales">Locales</a></span></dt><dd><dl><dt><span class="section"><a href="localization.html#std.localization.locales.locale">locale</a></span></dt></dl></dd><dt><span class="section"><a href="facets.html">Facets</a></span></dt><dd><dl><dt><span class="section"><a href="facets.html#std.localization.facet.ctype">ctype</a></span></dt><dt><span class="section"><a href="facets.html#std.localization.facet.codecvt">codecvt</a></span></dt><dt><span class="section"><a href="facets.html#manual.localization.facet.messages">messages</a></span></dt></dl></dd></dl></div><div class="section" title="Locales"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.localization.locales"></a>Locales</h2></div></div></div><div class="section" title="locale"><div class="titlepage"><div><div><h3 class="title"><a id="std.localization.locales.locale"></a>locale</h3></div></div></div><p>
Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.req"></a>Requirements</h4></div></div></div><p>
Class locale is non-templatized and has two distinct types nested
inside of it:
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
class facet
22.1.1.1.2 Class locale::facet
</em></span>
</p></blockquote></div><p>
Facets actually implement locale functionality. For instance, a facet
called numpunct is the data object that can be used to query for the
thousands separator in the locale.
</p><p>
Literally, a facet is strictly defined:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Containing the following public data member:
</p><p>
<code class="code">static locale::id id;</code>
</p></li><li class="listitem"><p>
Derived from another facet:
</p><p>
<code class="code">class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code>
</p></li></ul></div><p>
Of interest in this class are the memory management options explicitly
specified as an argument to facet's constructor. Each constructor of a
facet class takes a std::size_t __refs argument: if __refs == 0, the
facet is deleted when the locale containing it is destroyed. If __refs
== 1, the facet is not destroyed, even when it is no longer
referenced.
</p><div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>
class id
22.1.1.1.3 - Class locale::id
</em></span>
</p></blockquote></div><p>
Provides an index for looking up specific facets.
</p></div><div class="section" title="Design"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.design"></a>Design</h4></div></div></div><p>
The major design challenge is fitting an object-orientated and
non-global locale design on top of POSIX and other relevant standards,
which include the Single Unix (nee X/Open.)
</p><p>
Because C and earlier versions of POSIX fall down so completely,
portability is an issue.
</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.impl"></a>Implementation</h4></div></div></div><div class="section" title="Interacting with &quot;C&quot; locales"><div class="titlepage"><div><div><h5 class="title"><a id="locale.impl.c"></a>Interacting with "C" locales</h5></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
<code class="code">`locale -a`</code> displays available locales.
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
af_ZA
ar_AE
ar_AE.utf8
ar_BH
ar_BH.utf8
ar_DZ
ar_DZ.utf8
ar_EG
ar_EG.utf8
ar_IN
ar_IQ
ar_IQ.utf8
ar_JO
ar_JO.utf8
ar_KW
ar_KW.utf8
ar_LB
ar_LB.utf8
ar_LY
ar_LY.utf8
ar_MA
ar_MA.utf8
ar_OM
ar_OM.utf8
ar_QA
ar_QA.utf8
ar_SA
ar_SA.utf8
ar_SD
ar_SD.utf8
ar_SY
ar_SY.utf8
ar_TN
ar_TN.utf8
ar_YE
ar_YE.utf8
be_BY
be_BY.utf8
bg_BG
bg_BG.utf8
br_FR
bs_BA
C
ca_ES
ca_ES@euro
ca_ES.utf8
ca_ES.utf8@euro
cs_CZ
cs_CZ.utf8
cy_GB
da_DK
da_DK.iso885915
da_DK.utf8
de_AT
de_AT@euro
de_AT.utf8
de_AT.utf8@euro
de_BE
de_BE@euro
de_BE.utf8
de_BE.utf8@euro
de_CH
de_CH.utf8
de_DE
de_DE@euro
de_DE.utf8
de_DE.utf8@euro
de_LU
de_LU@euro
de_LU.utf8
de_LU.utf8@euro
el_GR
el_GR.utf8
en_AU
en_AU.utf8
en_BW
en_BW.utf8
en_CA
en_CA.utf8
en_DK
en_DK.utf8
en_GB
en_GB.iso885915
en_GB.utf8
en_HK
en_HK.utf8
en_IE
en_IE@euro
en_IE.utf8
en_IE.utf8@euro
en_IN
en_NZ
en_NZ.utf8
en_PH
en_PH.utf8
en_SG
en_SG.utf8
en_US
en_US.iso885915
en_US.utf8
en_ZA
en_ZA.utf8
en_ZW
en_ZW.utf8
es_AR
es_AR.utf8
es_BO
es_BO.utf8
es_CL
es_CL.utf8
es_CO
es_CO.utf8
es_CR
es_CR.utf8
es_DO
es_DO.utf8
es_EC
es_EC.utf8
es_ES
es_ES@euro
es_ES.utf8
es_ES.utf8@euro
es_GT
es_GT.utf8
es_HN
es_HN.utf8
es_MX
es_MX.utf8
es_NI
es_NI.utf8
es_PA
es_PA.utf8
es_PE
es_PE.utf8
es_PR
es_PR.utf8
es_PY
es_PY.utf8
es_SV
es_SV.utf8
es_US
es_US.utf8
es_UY
es_UY.utf8
es_VE
es_VE.utf8
et_EE
et_EE.utf8
eu_ES
eu_ES@euro
eu_ES.utf8
eu_ES.utf8@euro
fa_IR
fi_FI
fi_FI@euro
fi_FI.utf8
fi_FI.utf8@euro
fo_FO
fo_FO.utf8
fr_BE
fr_BE@euro
fr_BE.utf8
fr_BE.utf8@euro
fr_CA
fr_CA.utf8
fr_CH
fr_CH.utf8
fr_FR
fr_FR@euro
fr_FR.utf8
fr_FR.utf8@euro
fr_LU
fr_LU@euro
fr_LU.utf8
fr_LU.utf8@euro
ga_IE
ga_IE@euro
ga_IE.utf8
ga_IE.utf8@euro
gl_ES
gl_ES@euro
gl_ES.utf8
gl_ES.utf8@euro
gv_GB
gv_GB.utf8
he_IL
he_IL.utf8
hi_IN
hr_HR
hr_HR.utf8
hu_HU
hu_HU.utf8
id_ID
id_ID.utf8
is_IS
is_IS.utf8
it_CH
it_CH.utf8
it_IT
it_IT@euro
it_IT.utf8
it_IT.utf8@euro
iw_IL
iw_IL.utf8
ja_JP.eucjp
ja_JP.utf8
ka_GE
kl_GL
kl_GL.utf8
ko_KR.euckr
ko_KR.utf8
kw_GB
kw_GB.utf8
lt_LT
lt_LT.utf8
lv_LV
lv_LV.utf8
mi_NZ
mk_MK
mk_MK.utf8
mr_IN
ms_MY
ms_MY.utf8
mt_MT
mt_MT.utf8
nl_BE
nl_BE@euro
nl_BE.utf8
nl_BE.utf8@euro
nl_NL
nl_NL@euro
nl_NL.utf8
nl_NL.utf8@euro
nn_NO
nn_NO.utf8
no_NO
no_NO.utf8
oc_FR
pl_PL
pl_PL.utf8
POSIX
pt_BR
pt_BR.utf8
pt_PT
pt_PT@euro
pt_PT.utf8
pt_PT.utf8@euro
ro_RO
ro_RO.utf8
ru_RU
ru_RU.koi8r
ru_RU.utf8
ru_UA
ru_UA.utf8
se_NO
sk_SK
sk_SK.utf8
sl_SI
sl_SI.utf8
sq_AL
sq_AL.utf8
sr_YU
sr_YU@cyrillic
sr_YU.utf8
sr_YU.utf8@cyrillic
sv_FI
sv_FI@euro
sv_FI.utf8
sv_FI.utf8@euro
sv_SE
sv_SE.iso885915
sv_SE.utf8
ta_IN
te_IN
tg_TJ
th_TH
th_TH.utf8
tl_PH
tr_TR
tr_TR.utf8
uk_UA
uk_UA.utf8
ur_PK
uz_UZ
vi_VN
vi_VN.tcvn
wa_BE
wa_BE@euro
yi_US
zh_CN
zh_CN.gb18030
zh_CN.gbk
zh_CN.utf8
zh_HK
zh_HK.utf8
zh_TW
zh_TW.euctw
zh_TW.utf8
</pre></blockquote></div></li><li class="listitem"><p>
<code class="code">`locale`</code> displays environmental variables that
impact how locale("") will be deduced.
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
LANG=en_US
LC_CTYPE="en_US"
LC_NUMERIC="en_US"
LC_TIME="en_US"
LC_COLLATE="en_US"
LC_MONETARY="en_US"
LC_MESSAGES="en_US"
LC_PAPER="en_US"
LC_NAME="en_US"
LC_ADDRESS="en_US"
LC_TELEPHONE="en_US"
LC_MEASUREMENT="en_US"
LC_IDENTIFICATION="en_US"
LC_ALL=
</pre></blockquote></div></li></ul></div><p>
From Josuttis, p. 697-698, which says, that "there is only *one*
relation (of the C++ locale mechanism) to the C locale mechanism: the
global C locale is modified if a named C++ locale object is set as the
global locale" (emphasis Paolo), that is:
</p><pre class="programlisting">std::locale::global(std::locale(""));</pre><p>affects the C functions as if the following call was made:</p><pre class="programlisting">std::setlocale(LC_ALL, "");</pre><p>
On the other hand, there is *no* vice versa, that is, calling
setlocale has *no* whatsoever on the C++ locale mechanism, in
particular on the working of locale(""), which constructs the locale
object from the environment of the running program, that is, in
practice, the set of LC_ALL, LANG, etc. variable of the shell.
</p></div></div><div class="section" title="Future"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.future"></a>Future</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
Locale initialization: at what point does _S_classic, _S_global
get initialized? Can named locales assume this initialization
has already taken place?
</p></li><li class="listitem"><p>
Document how named locales error check when filling data
members. I.e., a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention?
</p></li><li class="listitem"><p>
Explain how locale aliasing happens. When does "de_DE" use "de"
information? What is the rule for locales composed of just an
ISO language code (say, "de") and locales with both an ISO
language code and ISO country code (say, "de_DE").
</p></li><li class="listitem"><p>
What should non-required facet instantiations do? If the
generic implementation is provided, then how to end-users
provide specializations?
</p></li></ul></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="locales.locale.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="The GNU C Library"><a id="id395802"></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" title="Correspondence"><a id="id400950"></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" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id404652"></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" title="ISO/IEC 9899:1999 Programming languages - C"><a id="id404670"></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="id404688"></a><p><span class="biblioid">
<a class="ulink" href="http://www.opengroup.org/austin" target="_top">
<em class="citetitle">
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
</em>
</a>
. </span><span class="copyright">Copyright © 2008
The Open Group/The Institute of Electrical and Electronics
Engineers, Inc.
. </span></p></div><div class="biblioentry" title="The C++ Programming Language, Special Edition"><a id="id381600"></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" title="Standard C++ IOStreams and Locales"><a id="id492267"></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><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="bk01pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="facets.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. 
Strings
 </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Facets</td></tr></table></div></body></html>

511
libstdc++-v3/doc/html/manual/memory.html
View file

@ -1,15 +1,15 @@
<?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 11. Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV.  Utilities" /><link rel="prev" href="pairs.html" title="Chapter 10. Pairs" /><link rel="next" href="auto_ptr.html" title="auto_ptr" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pairs.html">Prev</a> </td><th width="60%" align="center">Part IV. 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10; ISO C++&#10; , &#10; library&#10; " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Chapter 6.  Utilities" /><link rel="prev" href="pairs.html" title="Pairs" /><link rel="next" href="traits.html" title="Traits" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pairs.html">Prev</a> </td><th width="60%" align="center">Chapter 6. 
Utilities
</th><td width="20%" align="right"> <a accesskey="n" href="auto_ptr.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 11. Memory"><div class="titlepage"><div><div><h2 class="title"><a id="manual.util.memory"></a>Chapter 11. Memory</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="memory.html#manual.util.memory.allocator">Allocators</a></span></dt><dd><dl><dt><span class="sect2"><a href="memory.html#allocator.req">Requirements</a></span></dt><dt><span class="sect2"><a href="memory.html#allocator.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="memory.html#allocator.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="memory.html#allocator.using">Using a Specific Allocator</a></span></dt><dt><span class="sect2"><a href="memory.html#allocator.custom">Custom Allocators</a></span></dt><dt><span class="sect2"><a href="memory.html#allocator.ext">Extension Allocators</a></span></dt></dl></dd><dt><span class="sect1"><a href="auto_ptr.html">auto_ptr</a></span></dt><dd><dl><dt><span class="sect2"><a href="auto_ptr.html#auto_ptr.limitations">Limitations</a></span></dt><dt><span class="sect2"><a href="auto_ptr.html#auto_ptr.using">Use in Containers</a></span></dt></dl></dd><dt><span class="sect1"><a href="shared_ptr.html">shared_ptr</a></span></dt><dd><dl><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.req">Requirements</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.using">Use</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.ack">Acknowledgments</a></span></dt></dl></dd></dl></div><p>
</th><td width="20%" align="right"> <a accesskey="n" href="traits.html">Next</a></td></tr></table><hr /></div><div class="section" title="Memory"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.util.memory"></a>Memory</h2></div></div></div><p>
Memory contains three general areas. First, function and operator
calls via <code class="function">new</code> and <code class="function">delete</code>
operator or member function calls. Second, allocation via
<code class="classname">allocator</code>. And finally, smart pointer and
intelligent pointer abstractions.
</p><div class="sect1" title="Allocators"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.util.memory.allocator"></a>Allocators</h2></div></div></div><p>
</p><div class="section" title="Allocators"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.allocator"></a>Allocators</h3></div></div></div><p>
Memory management for Standard Library entities is encapsulated in a
class template called <code class="classname">allocator</code>. The
<code class="classname">allocator</code> abstraction is used throughout the
@ -17,7 +17,7 @@
algorithms, and parts of iostreams. This class, and base classes of
it, are the superset of available free store (<span class="quote">“<span class="quote">heap</span>”</span>)
management classes.
</p><div class="sect2" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.req"></a>Requirements</h3></div></div></div><p>
</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.req"></a>Requirements</h4></div></div></div><p>
The C++ standard only gives a few directives in this area:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
When you add elements to a container, and the container must
@ -32,9 +32,9 @@
container-of-T is <code class="classname">allocator&lt;T&gt;</code>.
</p></li><li class="listitem"><p>
The interface of the <code class="classname">allocator&lt;T&gt;</code> class is
extremely simple. It has about 20 public declarations (nested
typedefs, member functions, etc), but the two which concern us most
are:
extremely simple. It has about 20 public declarations (nested
typedefs, member functions, etc), but the two which concern us most
are:
</p><pre class="programlisting">
T* allocate (size_type n, const void* hint = 0);
void deallocate (T* p, size_type n);
@ -43,18 +43,18 @@
functions is a <span class="emphasis"><em>count</em></span> of the number of
<span class="type">T</span>'s to allocate space for, <span class="emphasis"><em>not their
total size</em></span>.
(This is a simplification; the real signatures use nested typedefs.)
(This is a simplification; the real signatures use nested typedefs.)
</p></li><li class="listitem"><p>
The storage is obtained by calling <code class="function">::operator
new</code>, but it is unspecified when or how
often this function is called. The use of the
often this function is called. The use of the
<code class="varname">hint</code> is unspecified, but intended as an
aid to locality if an implementation so
desires. <code class="constant">[20.4.1.1]/6</code>
</p></li></ul></div><p>
</p></li></ul></div><p>
Complete details can be found in the C++ standard, look in
<code class="constant">[20.4 Memory]</code>.
</p></div><div class="sect2" title="Design Issues"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.design_issues"></a>Design Issues</h3></div></div></div><p>
</p></div><div class="section" title="Design Issues"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.design_issues"></a>Design Issues</h4></div></div></div><p>
The easiest way of fulfilling the requirements is to call
<code class="function">operator new</code> each time a container needs
memory, and to call <code class="function">operator delete</code> each time
@ -67,7 +67,7 @@
while <code class="classname">__gnu_cxx::malloc_allocator</code>
implements much the same thing, only with the C language functions
<code class="function">std::malloc</code> and <code class="function">free</code>.
</p><p>
</p><p>
Another approach is to use intelligence within the allocator
class to cache allocations. This extra machinery can take a variety
of forms: a bitmap index, an index into an exponentially increasing
@ -93,33 +93,33 @@
or loading and unloading shared objects in memory. As such, using
caching allocators on systems that do not support
<code class="function">abi::__cxa_atexit</code> is not recommended.
</p></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.impl"></a>Implementation</h3></div></div></div><div class="sect3" title="Interface Design"><div class="titlepage"><div><div><h4 class="title"><a id="id630442"></a>Interface Design</h4></div></div></div><p>
</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.impl"></a>Implementation</h4></div></div></div><div class="section" title="Interface Design"><div class="titlepage"><div><div><h5 class="title"><a id="id444984"></a>Interface Design</h5></div></div></div><p>
The only allocator interface that
is supported is the standard C++ interface. As such, all STL
containers have been adjusted, and all external allocators have
been modified to support this change.
</p><p>
been modified to support this change.
</p><p>
The class <code class="classname">allocator</code> just has typedef,
constructor, and rebind members. It inherits from one of the
high-speed extension allocators, covered below. Thus, all
allocation and deallocation depends on the base class.
</p><p>
</p><p>
The base class that <code class="classname">allocator</code> is derived from
may not be user-configurable.
</p></div><div class="sect3" title="Selecting Default Allocation Policy"><div class="titlepage"><div><div><h4 class="title"><a id="id637894"></a>Selecting Default Allocation Policy</h4></div></div></div><p>
</p></div><div class="section" title="Selecting Default Allocation Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id399970"></a>Selecting Default Allocation Policy</h5></div></div></div><p>
It's difficult to pick an allocation strategy that will provide
maximum utility, without excessively penalizing some behavior. In
fact, it's difficult just deciding which typical actions to measure
for speed.
</p><p>
</p><p>
Three synthetic benchmarks have been created that provide data
that is used to compare different C++ allocators. These tests are:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Insertion.
Insertion.
</p><p>
Over multiple iterations, various STL container
objects have elements inserted to some maximum amount. A variety
of allocators are tested.
of allocators are tested.
Test source for <a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup" target="_top">sequence</a>
and <a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup" target="_top">associative</a>
containers.
@ -128,22 +128,22 @@
</p><p>
This test shows the ability of the allocator to reclaim memory
on a per-thread basis, as well as measuring thread contention
for memory resources.
Test source
for memory resources.
Test source
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup" target="_top">here</a>.
</p></li><li class="listitem"><p>
A threaded producer/consumer model.
</p><p>
Test source for
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup" target="_top">sequence</a>
and
and
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup" target="_top">associative</a>
containers.
</p></li></ol></div><p>
The current default choice for
<code class="classname">allocator</code> is
<code class="classname">__gnu_cxx::new_allocator</code>.
</p></div><div class="sect3" title="Disabling Memory Caching"><div class="titlepage"><div><div><h4 class="title"><a id="id629596"></a>Disabling Memory Caching</h4></div></div></div><p>
</p></div><div class="section" title="Disabling Memory Caching"><div class="titlepage"><div><div><h5 class="title"><a id="id392037"></a>Disabling Memory Caching</h5></div></div></div><p>
In use, <code class="classname">allocator</code> may allocate and
deallocate using implementation-specified strategies and
heuristics. Because of this, every call to an allocator object's
@ -151,13 +151,13 @@
call the global operator new. This situation is also duplicated
for calls to the <code class="function">deallocate</code> member
function.
</p><p>
This can be confusing.
</p><p>
</p><p>
This can be confusing.
</p><p>
In particular, this can make debugging memory errors more
difficult, especially when using third party tools like valgrind or
debug versions of <code class="function">new</code>.
</p><p>
</p><p>
There are various ways to solve this problem. One would be to use
a custom allocator that just called operators
<code class="function">new</code> and <code class="function">delete</code>
@ -179,7 +179,7 @@
environment, it likely means that you linked against objects
built against the older library (objects which might still using the
cached allocations...).
</p></div></div><div class="sect2" title="Using a Specific Allocator"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.using"></a>Using a Specific Allocator</h3></div></div></div><p>
</p></div></div><div class="section" title="Using a Specific Allocator"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.using"></a>Using a Specific Allocator</h4></div></div></div><p>
You can specify different memory management schemes on a
per-container basis, by overriding the default
<span class="type">Allocator</span> template parameter. For example, an easy
@ -190,16 +190,16 @@
Likewise, a debugging form of whichever allocator is currently in use:
</p><pre class="programlisting">
std::deque &lt;int, __gnu_cxx::debug_allocator&lt;std::allocator&lt;int&gt; &gt; &gt; debug_deque;
</pre></div><div class="sect2" title="Custom Allocators"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.custom"></a>Custom Allocators</h3></div></div></div><p>
</pre></div><div class="section" title="Custom Allocators"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.custom"></a>Custom Allocators</h4></div></div></div><p>
Writing a portable C++ allocator would dictate that the interface
would look much like the one specified for
<code class="classname">allocator</code>. Additional member functions, but
not subtractions, would be permissible.
</p><p>
</p><p>
Probably the best place to start would be to copy one of the
extension allocators: say a simple one like
extension allocators: say a simple one like
<code class="classname">new_allocator</code>.
</p></div><div class="sect2" title="Extension Allocators"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.ext"></a>Extension Allocators</h3></div></div></div><p>
</p></div><div class="section" title="Extension Allocators"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.ext"></a>Extension Allocators</h4></div></div></div><p>
Several other allocators are provided as part of this
implementation. The location of the extension allocators and their
names have changed, but in all cases, functionality is
@ -237,7 +237,7 @@
startup. For usage examples, please consult the testsuite.
</p></li><li class="listitem"><p>
<code class="classname">debug_allocator</code>
</p><p>
</p><p>
A wrapper around an arbitrary allocator A. It passes on
slightly increased size requests to A, and uses the extra
memory to store size information. When a pointer is passed
@ -246,13 +246,13 @@
guarantee they match.
</p></li><li class="listitem"><p>
<code class="classname">throw_allocator</code>
</p><p>
</p><p>
Includes memory tracking and marking abilities as well as hooks for
throwing exceptions at configurable intervals (including random,
all, none).
all, none).
</p></li><li class="listitem"><p>
<code class="classname">__pool_alloc</code>
</p><p>
</p><p>
A high-performance, single pool allocator. The reusable
memory is shared among identical instantiations of this type.
It calls through <code class="function">::operator new</code> to
@ -261,7 +261,7 @@
size, then the pool is bypassed, and the allocate/deallocate
request is passed to <code class="function">::operator new</code>
directly.
</p><p>
</p><p>
Older versions of this class take a boolean template
parameter, called <code class="varname">thr</code>, and an integer template
parameter, called <code class="varname">inst</code>.
@ -308,39 +308,422 @@
A high-performance allocator that uses a bit-map to keep track
of the used and unused memory locations. It has its own
documentation, found <a class="link" href="bitmap_allocator.html" title="bitmap_allocator">here</a>.
</p></li></ol></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id616986"></a><p><span class="title"><i>
ISO/IEC 14882:1998 Programming languages - C++
</p></li></ol></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id449438"></a><p><span class="title"><i>
ISO/IEC 14882:1998 Programming languages - C++
</i>. </span>
isoc++_1998
<span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry" title="The Standard Librarian: What Are Allocators Good"><a id="id617001"></a><p><span class="title"><i>The Standard Librarian: What Are Allocators Good
</i>. </span>
austernm
<span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername">
C/C++ Users Journal
. </span></span><span class="biblioid">
<a class="ulink" href="http://www.cuj.com/documents/s=8000/cujcexp1812austern/" target="_top">
<span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry"><a id="id449453"></a><p><span class="biblioid">
<a class="ulink" href="http://www.drdobbs.com/cpp/184403759" target="_top">
<em class="citetitle">
The Standard Librarian: What Are Allocators Good For?
</em>
</a>
. </span></p></div><div class="biblioentry" title="The Hoard Memory Allocator"><a id="id658988"></a><p><span class="title"><i>The Hoard Memory Allocator</i>. </span>
emeryb
<span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="biblioid">
. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername">
C/C++ Users Journal
. </span></span></p></div><div class="biblioentry"><a id="id396647"></a><p><span class="biblioid">
<a class="ulink" href="http://www.cs.umass.edu/~emery/hoard/" target="_top">
<em class="citetitle">
The Hoard Memory Allocator
</em>
</a>
. </span></p></div><div class="biblioentry" title="Reconsidering Custom Memory Allocation"><a id="id620190"></a><p><span class="title"><i>Reconsidering Custom Memory Allocation</i>. </span>
bergerzorn
<span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span><span class="biblioid">
. </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span></p></div><div class="biblioentry"><a id="id410436"></a><p><span class="biblioid">
<a class="ulink" href="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf" target="_top">
<em class="citetitle">
Reconsidering Custom Memory Allocation
</em>
</a>
. </span></p></div><div class="biblioentry" title="Allocator Types"><a id="id598997"></a><p><span class="title"><i>Allocator Types</i>. </span>
kreftlanger
<span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="publisher"><span class="publishername">
C/C++ Users Journal
. </span></span><span class="biblioid">
. </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span></p></div><div class="biblioentry"><a id="id507492"></a><p><span class="biblioid">
<a class="ulink" href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html" target="_top">
<em class="citetitle">
Allocator Types
</em>
</a>
. </span></p></div><div class="biblioentry" title="The C++ Programming Language"><a id="id683391"></a><p><span class="title"><i>The C++ Programming Language</i>. </span>
tcpl
<span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername">
. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="publisher"><span class="publishername">
C/C++ Users Journal
. </span></span></p></div><div class="biblioentry" title="The C++ Programming Language"><a id="id394630"></a><p><span class="title"><i>The C++ Programming Language</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername">
Addison Wesley
. </span></span></p></div><div class="biblioentry" title="Yalloc: A Recycling C++ Allocator"><a id="id704594"></a><p><span class="title"><i>Yalloc: A Recycling C++ Allocator</i>. </span>
yenf
<span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span><span class="copyright">Copyright © . </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="pairs.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="auto_ptr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. Pairs </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> auto_ptr</td></tr></table></div></body></html>
. </span></span></p></div><div class="biblioentry" title="Yalloc: A Recycling C++ Allocator"><a id="id444446"></a><p><span class="title"><i>Yalloc: A Recycling C++ Allocator</i>. </span><span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span></p></div></div></div><div class="section" title="auto_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.auto_ptr"></a>auto_ptr</h3></div></div></div><div class="section" title="Limitations"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.limitations"></a>Limitations</h4></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="section" title="Use in Containers"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.using"></a>Use in Containers</h4></div></div></div><p>
</p><p>All of the <a class="link" href="containers.html" title="Chapter 9.  Containers">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">“<span class="quote">undefined</span>”</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="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">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="section" title="shared_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.shared_ptr"></a>shared_ptr</h3></div></div></div><p>
The shared_ptr class template stores a pointer, usually obtained via new,
and implements shared ownership semantics.
</p><div class="section" title="Requirements"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.req"></a>Requirements</h4></div></div></div><p>
</p><p>
The standard deliberately doesn't require a reference-counted
implementation, allowing other techniques such as a
circular-linked-list.
</p><p>
At the time of writing the C++0x working paper doesn't mention how
threads affect shared_ptr, but it is likely to follow the existing
practice set by <code class="classname">boost::shared_ptr</code>. The
shared_ptr in libstdc++ is derived from Boost's, so the same rules
apply.
</p><p>
</p></div><div class="section" title="Design Issues"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.design_issues"></a>Design Issues</h4></div></div></div><p>
The <code class="classname">shared_ptr</code> code is kindly donated to GCC by the Boost
project and the original authors of the code. The basic design and
algorithms are from Boost, the notes below describe details specific to
the GCC implementation. Names have been uglified in this implementation,
but the design should be recognisable to anyone familiar with the Boost
1.32 shared_ptr.
</p><p>
The basic design is an abstract base class, <code class="code">_Sp_counted_base</code> that
does the reference-counting and calls virtual functions when the count
drops to zero.
Derived classes override those functions to destroy resources in a context
where the correct dynamic type is known. This is an application of the
technique known as type erasure.
</p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.impl"></a>Implementation</h4></div></div></div><div class="section" title="Class Hierarchy"><div class="titlepage"><div><div><h5 class="title"><a id="id412343"></a>Class Hierarchy</h5></div></div></div><p>
A <code class="classname">shared_ptr&lt;T&gt;</code> contains a pointer of
type <span class="type">T*</span> and an object of type
<code class="classname">__shared_count</code>. The shared_count contains a
pointer of type <span class="type">_Sp_counted_base*</span> which points to the
object that maintains the reference-counts and destroys the managed
resource.
</p><div class="variablelist"><dl><dt><span class="term"><code class="classname">_Sp_counted_base&lt;Lp&gt;</code></span></dt><dd><p>
The base of the hierarchy is parameterized on the lock policy alone.
_Sp_counted_base doesn't depend on the type of pointer being managed,
it only maintains the reference counts and calls virtual functions when
the counts drop to zero. The managed object is destroyed when the last
strong reference is dropped, but the _Sp_counted_base itself must exist
until the last weak reference is dropped.
</p></dd><dt><span class="term"><code class="classname">_Sp_counted_base_impl&lt;Ptr, Deleter, Lp&gt;</code></span></dt><dd><p>
Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span>
and a deleter of type <code class="code">Deleter</code>. <code class="code">_Sp_deleter</code> is
used when the user doesn't supply a custom deleter. Unlike Boost's, this
default deleter is not "checked" because GCC already issues a warning if
<code class="function">delete</code> is used with an incomplete type.
This is the only derived type used by <code class="classname">shared_ptr&lt;Ptr&gt;</code>
and it is never used by <code class="classname">shared_ptr</code>, which uses one of
the following types, depending on how the shared_ptr is constructed.
</p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr&lt;Ptr, Lp&gt;</code></span></dt><dd><p>
Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span>,
which is passed to <code class="function">delete</code> when the last reference is dropped.
This is the simplest form and is used when there is no custom deleter or
allocator.
</p></dd><dt><span class="term"><code class="classname">_Sp_counted_deleter&lt;Ptr, Deleter, Alloc&gt;</code></span></dt><dd><p>
Inherits from _Sp_counted_ptr and adds support for custom deleter and
allocator. Empty Base Optimization is used for the allocator. This class
is used even when the user only provides a custom deleter, in which case
<code class="classname">allocator</code> is used as the allocator.
</p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr_inplace&lt;Tp, Alloc, Lp&gt;</code></span></dt><dd><p>
Used by <code class="code">allocate_shared</code> and <code class="code">make_shared</code>.
Contains aligned storage to hold an object of type <span class="type">Tp</span>,
which is constructed in-place with placement <code class="function">new</code>.
Has a variadic template constructor allowing any number of arguments to
be forwarded to <span class="type">Tp</span>'s constructor.
Unlike the other <code class="classname">_Sp_counted_*</code> classes, this one is parameterized on the
type of object, not the type of pointer; this is purely a convenience
that simplifies the implementation slightly.
</p></dd></dl></div></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h5 class="title"><a id="id401193"></a>Thread Safety</h5></div></div></div><p>
The interface of <code class="classname">tr1::shared_ptr</code> was extended for C++0x
with support for rvalue-references and the other features from
N2351. As with other libstdc++ headers shared by TR1 and C++0x,
boost_shared_ptr.h uses conditional compilation, based on the macros
<code class="constant">_GLIBCXX_INCLUDE_AS_CXX0X</code> and
<code class="constant">_GLIBCXX_INCLUDE_AS_TR1</code>, to enable and disable
features.
</p><p>
C++0x-only features are: rvalue-ref/move support, allocator support,
aliasing constructor, make_shared &amp; allocate_shared. Additionally,
the constructors taking <code class="classname">auto_ptr</code> parameters are
deprecated in C++0x mode.
</p><p>
The
<a class="ulink" href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety" target="_top">Thread
Safety</a> section of the Boost shared_ptr documentation says "shared_ptr
objects offer the same level of thread safety as built-in types."
The implementation must ensure that concurrent updates to separate shared_ptr
instances are correct even when those instances share a reference count e.g.
</p><pre class="programlisting">
shared_ptr&lt;A&gt; a(new A);
shared_ptr&lt;A&gt; b(a);
// Thread 1 // Thread 2
a.reset(); b.reset();
</pre><p>
The dynamically-allocated object must be destroyed by exactly one of the
threads. Weak references make things even more interesting.
The shared state used to implement shared_ptr must be transparent to the
user and invariants must be preserved at all times.
The key pieces of shared state are the strong and weak reference counts.
Updates to these need to be atomic and visible to all threads to ensure
correct cleanup of the managed resource (which is, after all, shared_ptr's
job!)
On multi-processor systems memory synchronisation may be needed so that
reference-count updates and the destruction of the managed resource are
race-free.
</p><p>
The function <code class="function">_Sp_counted_base::_M_add_ref_lock()</code>, called when
obtaining a shared_ptr from a weak_ptr, has to test if the managed
resource still exists and either increment the reference count or throw
<code class="classname">bad_weak_ptr</code>.
In a multi-threaded program there is a potential race condition if the last
reference is dropped (and the managed resource destroyed) between testing
the reference count and incrementing it, which could result in a shared_ptr
pointing to invalid memory.
</p><p>
The Boost shared_ptr (as used in GCC) features a clever lock-free
algorithm to avoid the race condition, but this relies on the
processor supporting an atomic <span class="emphasis"><em>Compare-And-Swap</em></span>
instruction. For other platforms there are fall-backs using mutex
locks. Boost (as of version 1.35) includes several different
implementations and the preprocessor selects one based on the
compiler, standard library, platform etc. For the version of
shared_ptr in libstdc++ the compiler and library are fixed, which
makes things much simpler: we have an atomic CAS or we don't, see Lock
Policy below for details.
</p></div><div class="section" title="Selecting Lock Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id394558"></a>Selecting Lock Policy</h5></div></div></div><p>
</p><p>
There is a single <code class="classname">_Sp_counted_base</code> class,
which is a template parameterized on the enum
<span class="type">__gnu_cxx::_Lock_policy</span>. The entire family of classes is
parameterized on the lock policy, right up to
<code class="classname">__shared_ptr</code>, <code class="classname">__weak_ptr</code> and
<code class="classname">__enable_shared_from_this</code>. The actual
<code class="classname">std::shared_ptr</code> class inherits from
<code class="classname">__shared_ptr</code> with the lock policy parameter
selected automatically based on the thread model and platform that
libstdc++ is configured for, so that the best available template
specialization will be used. This design is necessary because it would
not be conforming for <code class="classname">shared_ptr</code> to have an
extra template parameter, even if it had a default value. The
available policies are:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
<span class="type">_S_Atomic</span>
</p><p>
Selected when GCC supports a builtin atomic compare-and-swap operation
on the target processor (see <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html" target="_top">Atomic
Builtins</a>.) The reference counts are maintained using a lock-free
algorithm and GCC's atomic builtins, which provide the required memory
synchronisation.
</p></li><li class="listitem"><p>
<span class="type">_S_Mutex</span>
</p><p>
The _Sp_counted_base specialization for this policy contains a mutex,
which is locked in add_ref_lock(). This policy is used when GCC's atomic
builtins aren't available so explicit memory barriers are needed in places.
</p></li><li class="listitem"><p>
<span class="type">_S_Single</span>
</p><p>
This policy uses a non-reentrant add_ref_lock() with no locking. It is
used when libstdc++ is built without <code class="literal">--enable-threads</code>.
</p></li></ol></div><p>
For all three policies, reference count increments and
decrements are done via the functions in
<code class="filename">ext/atomicity.h</code>, which detect if the program
is multi-threaded. If only one thread of execution exists in
the program then less expensive non-atomic operations are used.
</p></div><div class="section" title="Dual C++0x and TR1 Implementation"><div class="titlepage"><div><div><h5 class="title"><a id="id382919"></a>Dual C++0x and TR1 Implementation</h5></div></div></div><p>
The classes derived from <code class="classname">_Sp_counted_base</code> (see Class Hierarchy
below) and <code class="classname">__shared_count</code> are implemented separately for C++0x
and TR1, in <code class="filename">bits/boost_sp_shared_count.h</code> and
<code class="filename">tr1/boost_sp_shared_count.h</code> respectively. All other classes
including <code class="classname">_Sp_counted_base</code> are shared by both implementations.
</p><p>
The TR1 implementation is considered relatively stable, so is unlikely to
change unless bug fixes require it. If the code that is common to both
C++0x and TR1 modes needs to diverge further then it might be necessary to
duplicate additional classes and only make changes to the C++0x versions.
</p></div><div class="section" title="Related functions and classes"><div class="titlepage"><div><div><h5 class="title"><a id="id479578"></a>Related functions and classes</h5></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="code">dynamic_pointer_cast</code>, <code class="code">static_pointer_cast</code>,
<code class="code">const_pointer_cast</code></span></dt><dd><p>
As noted in N2351, these functions can be implemented non-intrusively using
the alias constructor. However the aliasing constructor is only available
in C++0x mode, so in TR1 mode these casts rely on three non-standard
constructors in shared_ptr and __shared_ptr.
In C++0x mode these constructors and the related tag types are not needed.
</p></dd><dt><span class="term"><code class="code">enable_shared_from_this</code></span></dt><dd><p>
The clever overload to detect a base class of type
<code class="code">enable_shared_from_this</code> comes straight from Boost.
There is an extra overload for <code class="code">__enable_shared_from_this</code> to
work smoothly with <code class="code">__shared_ptr&lt;Tp, Lp&gt;</code> using any lock
policy.
</p></dd><dt><span class="term"><code class="code">make_shared</code>, <code class="code">allocate_shared</code></span></dt><dd><p>
<code class="code">make_shared</code> simply forwards to <code class="code">allocate_shared</code>
with <code class="code">std::allocator</code> as the allocator.
Although these functions can be implemented non-intrusively using the
alias constructor, if they have access to the implementation then it is
possible to save storage and reduce the number of heap allocations. The
newly constructed object and the _Sp_counted_* can be allocated in a single
block and the standard says implementations are "encouraged, but not required,"
to do so. This implementation provides additional non-standard constructors
(selected with the type <code class="code">_Sp_make_shared_tag</code>) which create an
object of type <code class="code">_Sp_counted_ptr_inplace</code> to hold the new object.
The returned <code class="code">shared_ptr&lt;A&gt;</code> needs to know the address of the
new <code class="code">A</code> object embedded in the <code class="code">_Sp_counted_ptr_inplace</code>,
but it has no way to access it.
This implementation uses a "covert channel" to return the address of the
embedded object when <code class="code">get_deleter&lt;_Sp_make_shared_tag&gt;()</code>
is called. Users should not try to use this.
As well as the extra constructors, this implementation also needs some
members of _Sp_counted_deleter to be protected where they could otherwise
be private.
</p></dd></dl></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.using"></a>Use</h4></div></div></div><div class="section" title="Examples"><div class="titlepage"><div><div><h5 class="title"><a id="id386678"></a>Examples</h5></div></div></div><p>
Examples of use can be found in the testsuite, under
<code class="filename">testsuite/tr1/2_general_utilities/shared_ptr</code>.
</p></div><div class="section" title="Unresolved Issues"><div class="titlepage"><div><div><h5 class="title"><a id="id386695"></a>Unresolved Issues</h5></div></div></div><p>
The resolution to C++ Standard Library issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674" target="_top">674</a>,
"shared_ptr interface changes for consistency with N1856" will
need to be implemented after it is accepted into the working
paper. Issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743" target="_top">743</a>
might also require changes.
</p><p>
The <span class="type">_S_single</span> policy uses atomics when used in MT
code, because it uses the same dispatcher functions that check
<code class="function">__gthread_active_p()</code>. This could be
addressed by providing template specialisations for some members
of <code class="classname">_Sp_counted_base&lt;_S_single&gt;</code>.
</p><p>
Unlike Boost, this implementation does not use separate classes
for the pointer+deleter and pointer+deleter+allocator cases in
C++0x mode, combining both into _Sp_counted_deleter and using
<code class="classname">allocator</code> when the user doesn't specify
an allocator. If it was found to be beneficial an additional
class could easily be added. With the current implementation,
the _Sp_counted_deleter and __shared_count constructors taking a
custom deleter but no allocator are technically redundant and
could be removed, changing callers to always specify an
allocator. If a separate pointer+deleter class was added the
__shared_count constructor would be needed, so it has been kept
for now.
</p><p>
The hack used to get the address of the managed object from
<code class="function">_Sp_counted_ptr_inplace::_M_get_deleter()</code>
is accessible to users. This could be prevented if
<code class="function">get_deleter&lt;_Sp_make_shared_tag&gt;()</code>
always returned NULL, since the hack only needs to work at a
lower level, not in the public API. This wouldn't be difficult,
but hasn't been done since there is no danger of accidental
misuse: users already know they are relying on unsupported
features if they refer to implementation details such as
_Sp_make_shared_tag.
</p><p>
tr1::_Sp_deleter could be a private member of tr1::__shared_count but it
would alter the ABI.
</p><p>
Exposing the alias constructor in TR1 mode could simplify the
*_pointer_cast functions. Constructor could be private in TR1
mode, with the cast functions as friends.
</p></div></div><div class="section" title="Acknowledgments"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.ack"></a>Acknowledgments</h4></div></div></div><p>
The original authors of the Boost shared_ptr, which is really nice
code to work with, Peter Dimov in particular for his help and
invaluable advice on thread safety. Phillip Jordan and Paolo
Carlini for the lock policy implementation.
</p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id411149"></a><p><span class="biblioid">
<a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" target="_top">
<em class="citetitle">
Improving shared_ptr for C++0x, Revision 2
</em>
</a>
. </span><span class="subtitle">
N2351
. </span></p></div><div class="biblioentry"><a id="id413900"></a><p><span class="biblioid">
<a class="ulink" href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" target="_top">
<em class="citetitle">
C++ Standard Library Active Issues List
</em>
</a>
. </span><span class="subtitle">
N2456
. </span></p></div><div class="biblioentry"><a id="id470749"></a><p><span class="biblioid">
<a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" target="_top">
<em class="citetitle">
Working Draft, Standard for Programming Language C++
</em>
</a>
. </span><span class="subtitle">
N2461
. </span></p></div><div class="biblioentry"><a id="id470771"></a><p><span class="biblioid">
<a class="ulink" href="http://boost.org/libs/smart_ptr/shared_ptr.htm" target="_top">shared_ptr
<em class="citetitle">
Boost C++ Libraries documentation, shared_ptr
</em>
</a>
. </span><span class="subtitle">
N2461
. </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="pairs.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="traits.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Pairs </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Traits</td></tr></table></div></body></html>

Some files were not shown because too many files have changed in this diff Show more