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

Makefile: Use more portable shell wildcard.

Browse source 
2002-09-05  Jonathan Wakely  <jw@kayari.org>

	* docs/html/Makefile:  Use more portable shell wildcard.
	* docs/html/makedoc.awk:  Nest elements correctly for XHTML conversion.
	* docs/html/configopts.html, docs/html/documentation.html,
	docs/html/explanations.html, docs/html/install.html,
	docs/html/17_intro/contribute.html, docs/html/17_intro/howto.html,
	docs/html/17_intro/license.html, docs/html/18_support/howto.html,
	docs/html/19_diagnostics/howto.html, docs/html/20_util/howto.html,
	docs/html/21_strings/howto.html, docs/html/22_locale/codecvt.html,
	docs/html/22_locale/ctype.html, docs/html/22_locale/howto.html,
	docs/html/22_locale/locale.html, docs/html/22_locale/messages.html,
	docs/html/23_containers/howto.html, docs/html/24_iterators/howto.html,
	docs/html/25_algorithms/howto.html, docs/html/26_numerics/howto.html,
	docs/html/27_io/howto.html, docs/html/ext/howto.html,
	docs/html/ext/sgiexts.html, docs/html/faq/index.html:  Convert
	to XHTML.
	* docs/html/faq/index.txt:  Regenerate.

From-SVN: r56845
This commit is contained in:
Jonathan Wakely 2002-09-05 15:47:54 +00:00 • committed by Phil Edwards
parent 3578cf6341
commit 64a6f97186
28 changed files with 1505 additions and 1199 deletions
Download patch file Download diff file Expand all files Collapse all files

19
libstdc++-v3/ChangeLog
View file

@ -1,3 +1,22 @@
2002-09-05 Jonathan Wakely <jw@kayari.org>
* docs/html/Makefile: Use more portable shell wildcard.
* docs/html/makedoc.awk: Nest elements correctly for XHTML conversion.
* docs/html/configopts.html, docs/html/documentation.html,
docs/html/explanations.html, docs/html/install.html,
docs/html/17_intro/contribute.html, docs/html/17_intro/howto.html,
docs/html/17_intro/license.html, docs/html/18_support/howto.html,
docs/html/19_diagnostics/howto.html, docs/html/20_util/howto.html,
docs/html/21_strings/howto.html, docs/html/22_locale/codecvt.html,
docs/html/22_locale/ctype.html, docs/html/22_locale/howto.html,
docs/html/22_locale/locale.html, docs/html/22_locale/messages.html,
docs/html/23_containers/howto.html, docs/html/24_iterators/howto.html,
docs/html/25_algorithms/howto.html, docs/html/26_numerics/howto.html,
docs/html/27_io/howto.html, docs/html/ext/howto.html,
docs/html/ext/sgiexts.html, docs/html/faq/index.html: Convert
to XHTML.
* docs/html/faq/index.txt: Regenerate.
2002-09-05 Jakub Jelinek <jakub@redhat.com> 2002-09-05 Jakub Jelinek <jakub@redhat.com>
* config/locale/gnu/ctype_members.cc (ctype<wchar_t>::do_widen(char)): * config/locale/gnu/ctype_members.cc (ctype<wchar_t>::do_widen(char)):

41
libstdc++-v3/docs/html/17_intro/contribute.html
View file

@ -1,19 +1,18 @@
<!--990301 slightly modified version of the GCC contribute.html file-->
<html> <html>
<head> <head>
<title>How to contribute</title> <title>How to contribute</title>
</head> </head>
<!--#include virtual="/include/header-subpages.html"--> <!--990301 slightly modified version of the GCC contribute.html file-->
<!-- #include virtual="/include/header-subpages.html"-->
<body>
<h2>How to contribute</h2> <h2>How to contribute</h2>
<p> <p>
The Standard C++ Library v3, or libstc++-2.90.x, follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given write access to the CVS repository. First time submitors and all other potential contributors should follow this procedure: The Standard C++ Library v3, or libstc++-2.90.x, follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given write access to the CVS repository. First time submitors and all other potential contributors should follow this procedure:
</p>
<p> <hr />
<hr>
<h4>ONE : read the documentation</h4> <h4>ONE : read the documentation</h4>
<p>
<p>
<ul> <ul>
<li> Get and read the relevant sections of the C++ language <li> Get and read the relevant sections of the C++ language
specification. Copies of the full ISO 14882 standard are available on specification. Copies of the full ISO 14882 standard are available on
@ -27,25 +26,30 @@ and their web-site is right
<a href="http://www.ansi.org">here.</a> <a href="http://www.ansi.org">here.</a>
(And if you've already registered with them, clicking this link will take you to directly to the place where you can (And if you've already registered with them, clicking this link will take you to directly to the place where you can
<a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy the standard on-line.)</a> <a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy the standard on-line.)</a>
</li>
<li> The library working group bugs, and known defects, can be obtained at these web sites: <li> The library working group bugs, and known defects, can be obtained at these web sites:
<a href="http://www.dkuug.dk/jtc1/sc22/wg21/">http://www.dkuug.dk/jtc1/sc22/wg21 </a> <a href="http://www.dkuug.dk/jtc1/sc22/wg21/">http://www.dkuug.dk/jtc1/sc22/wg21 </a>
and <a href="http://www.comeaucomputing.com/iso/">http://www.comeaucomputing.com/iso/</a> and <a href="http://www.comeaucomputing.com/iso/">http://www.comeaucomputing.com/iso/</a>
</li>
<li> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <a href="http://reality.sgi.com/austern_mti/std-c++/faq.html"> here </a>. <li> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <a href="http://reality.sgi.com/austern_mti/std-c++/faq.html"> here </a>.
</li>
<li> Peruse the <a href="http://www.gnu.ai.mit.edu/prep/standards_toc.html">GNU Coding Standards</a>, and chuckle when you hit the part about "Using Languages Other Than C." <li> Peruse the <a href="http://www.gnu.ai.mit.edu/prep/standards_toc.html">GNU Coding Standards</a>, and chuckle when you hit the part about "Using Languages Other Than C."
</li>
<li> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <a href="C++STYLE"> here. </a> <li> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <a href="C++STYLE"> here. </a>
</li>
<li> And last but certainly not least, read the library-specific information found <a href="../documentation.html"> here.</a> <li> And last but certainly not least, read the library-specific information found <a href="../documentation.html"> here.</a>
</li>
</ul> </ul>
<p> <hr />
<hr>
<h4>TWO : copyright assignment</h4> <h4>TWO : copyright assignment</h4>
<p> <p>
Small changes can be accepted without a copyright assignment form on Small changes can be accepted without a copyright assignment form on
@ -56,40 +60,43 @@ to fill out appropriate disclaimer forms as well. Here is the <a href="libstdc++
Please contact <a href="mailto:benjamin@cygnus.com">Benjamin Please contact <a href="mailto:benjamin@cygnus.com">Benjamin
Kosnik</a> if you are confused about the assignment or have general Kosnik</a> if you are confused about the assignment or have general
licensing questions. licensing questions.
</p>
<p> <hr />
<hr>
<h4>THREE : submitting patches</h4> <h4>THREE : submitting patches</h4>
<p>
<p>
Every patch must have several pieces of information before it can be Every patch must have several pieces of information before it can be
properly evaluated. Ideally (and to ensure the fastest possible properly evaluated. Ideally (and to ensure the fastest possible
response from the maintainers) it would have all of these pieces: response from the maintainers) it would have all of these pieces:
<p> </p>
<ul> <ul>
<li> A description of the bug and how your patch fixes this bug. For <li> A description of the bug and how your patch fixes this bug. For
new features a description of the feature and your implementation. new features a description of the feature and your implementation. </li>
<li> A ChangeLog entry as plaintext; see the various ChangeLog files <li> A ChangeLog entry as plaintext; see the various ChangeLog files
for format and content. If using you are using emacs as your editor, for format and content. If using you are using emacs as your editor,
simply position the insertion point at the beginning of your change simply position the insertion point at the beginning of your change
and hit CX-4a to bring up the appropriate ChangeLog and hit CX-4a to bring up the appropriate ChangeLog
entry. See--magic! Similar functionality also exists for vi. entry. See--magic! Similar functionality also exists for vi. </li>
<li> A testsuite submission or sample program that will easily and <li> A testsuite submission or sample program that will easily and
simply show the existing error or test new functionality. simply show the existing error or test new functionality. </li>
<li> The patch itself. If you are accessing the CVS repository at <li> The patch itself. If you are accessing the CVS repository at
Cygnus, use "cvs update; cvs diff -c3p NEW"; else, use "diff -c3p OLD Cygnus, use "cvs update; cvs diff -c3p NEW"; else, use "diff -c3p OLD
NEW" ... If your version of diff does not support these options, then NEW" ... If your version of diff does not support these options, then
get the latest version of GNU diff. get the latest version of GNU diff. </li>
<li> When you have all these pieces, bundle them up in a mail message <li> 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 and send it to libstdc++@gcc.gnu.org. All patches and related
discussion should be sent to the libstdc++ mailinglist. discussion should be sent to the libstdc++ mailinglist. </li>
</ul> </ul>
</body>
</html>

72
libstdc++-v3/docs/html/17_intro/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17."> <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 17</title> <title>libstdc++-v3 HOWTO: Chapter 17</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -21,18 +20,18 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#2">The Standard C++ header files</a> <li><a href="#2">The Standard C++ header files</a></li>
<li><a href="#3">The Standard C++ library and multithreading</a> <li><a href="#3">The Standard C++ library and multithreading</a></li>
<li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a> <li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></li>
<li><a href="porting-howto.html">Porting HOWTO</a> <li><a href="porting-howto.html">Porting HOWTO</a></li>
<li><a href="#5">Behavior specific to libstdc++-v3</a> <li><a href="#5">Behavior specific to libstdc++-v3</a></li>
<li><a href="#6">Preprocessor macros controlling the library</a> <li><a href="#6">Preprocessor macros controlling the library</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -51,7 +50,7 @@
all compile and run. all compile and run.
</p> </p>
<hr> <hr />
<h2><a name="3">The Standard C++ library and multithreading</a></h2> <h2><a name="3">The Standard C++ library and multithreading</a></h2>
<p>This section discusses issues surrounding the proper compilation <p>This section discusses issues surrounding the proper compilation
of multithreaded applications which use the Standard C++ of multithreaded applications which use the Standard C++
@ -129,16 +128,17 @@
relevant message in the thread; from there you can use relevant message in the thread; from there you can use
&quot;Thread Next&quot; to move down the thread. This farm is in &quot;Thread Next&quot; to move down the thread. This farm is in
latest-to-oldest order. latest-to-oldest order.
</p>
<ul> <ul>
<li>Our threading expert Loren gives a breakdown of <li>Our threading expert Loren gives a breakdown of
<a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
six situations involving threads</a> for the 3.0 release series. six situations involving threads</a> for the 3.0 release series.</li>
<li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
This message</a> inspired a recent updating of issues with threading This message</a> inspired a recent updating of issues with threading
and the SGI STL library. It also contains some example and the SGI STL library. It also contains some example
POSIX-multithreaded STL code. POSIX-multithreaded STL code.</li>
</ul> </ul>
(A large selection of links to older messages has been removed; many <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 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 with work people with access to the backup tapes have been too swamped with work
to restore them. Many of the points have been superseded anyhow.) to restore them. Many of the points have been superseded anyhow.)
@ -150,7 +150,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></h2> <h2><a name="4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a></h2>
<p>The new-style headers are fully supported in libstdc++-v3. The compiler <p>The new-style headers are fully supported in libstdc++-v3. The compiler
itself fully supports namespaces, including <code>std::</code>. itself fully supports namespaces, including <code>std::</code>.
@ -164,16 +164,18 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">Behavior specific to libstdc++-v3</a></h2> <h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
<p>The ISO standard defines the following phrase: <p>The ISO standard defines the following phrase:
</p>
<blockquote><dl> <blockquote><dl>
<dt><code>[1.3.5] implementation-defined behavior</code> <dt><code>[1.3.5] implementation-defined behavior</code></dt>
<dd>behavior, for a well-formed program construct and correct data, that <dd>behavior, for a well-formed program construct and correct data, that
depends on the implementation <strong>and that each implementation depends on the implementation <strong>and that each implementation
shall document</strong>. shall document</strong>.
</dd>
</dl></blockquote> </dl></blockquote>
We do so here, for the C++ library only. Behavior of the compiler, <p>We do so here, for the C++ library only. Behavior of the compiler,
linker, runtime loader, and other elements of &quot;the linker, runtime loader, and other elements of &quot;the
implementation&quot; are documented elsewhere. Everything listed in implementation&quot; are documented elsewhere. Everything listed in
Annex B, Implemenation Qualities, are also part of the compiler, not Annex B, Implemenation Qualities, are also part of the compiler, not
@ -196,10 +198,10 @@
sections, libstdc++-v3 has zero control over what the cleanup code hands sections, libstdc++-v3 has zero control over what the cleanup code hands
back to the runtime loader. Talk to the compiler people. :-) back to the runtime loader. Talk to the compiler people. :-)
</p> </p>
<p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br> <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br />
<strong>[18.5.2]/5</strong> (bad_cast),<br> <strong>[18.5.2]/5</strong> (bad_cast),<br />
<strong>[18.5.3]/5</strong> (bad_typeid),<br> <strong>[18.5.3]/5</strong> (bad_typeid),<br />
<strong>[18.6.1]/8</strong> (exception),<br> <strong>[18.6.1]/8</strong> (exception),<br />
<strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code> <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
member function of class <code>std::exception</code>, and these other member function of class <code>std::exception</code>, and these other
classes publicly derived from it, simply returns the name of the classes publicly derived from it, simply returns the name of the
@ -225,10 +227,10 @@
have any allocators which compare non-equal, so we can't describe how have any allocators which compare non-equal, so we can't describe how
they behave. they behave.
</p> </p>
<p><strong>[21.1.3.1]/3,4</strong>,<br> <p><strong>[21.1.3.1]/3,4</strong>,<br />
<strong>[21.1.3.2]/2</strong>,<br> <strong>[21.1.3.2]/2</strong>,<br />
<strong>[23.*]'s foo::iterator</strong>,<br> <strong>[23.*]'s foo::iterator</strong>,<br />
<strong>[27.*]'s foo::*_type</strong>,<br> <strong>[27.*]'s foo::*_type</strong>,<br />
<strong>others...</strong> <strong>others...</strong>
Nope, these types are called implementation-defined because you Nope, these types are called implementation-defined because you
shouldn't be taking advantage of their underlying types. Listing them shouldn't be taking advantage of their underlying types. Listing them
@ -257,7 +259,7 @@
than the minimum required. I don't think we're currently taking than the minimum required. I don't think we're currently taking
advantage of this yet. advantage of this yet.
</p> </p>
<p><strong>[27.7.1.3]/16</strong>,<br> <p><strong>[27.7.1.3]/16</strong>,<br />
<strong>[27.8.1.4]/10</strong> <strong>[27.8.1.4]/10</strong>
The effects of <code>pubsetbuf/setbuf</code> are described The effects of <code>pubsetbuf/setbuf</code> are described
<a href="../27_io/howto.html#2">in this chapter</a>. <a href="../27_io/howto.html#2">in this chapter</a>.
@ -269,7 +271,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="6">Preprocessor macros controlling the library</a></h2> <h2><a name="6">Preprocessor macros controlling the library</a></h2>
<p>Some of the semantics of the libstdc++-v3 implementation are <p>Some of the semantics of the libstdc++-v3 implementation are
controlled by preprocessor macros, both during build/installation and controlled by preprocessor macros, both during build/installation and
@ -297,6 +299,7 @@
The default state of the symbol is listed. &quot;Configurable&quot; The default state of the symbol is listed. &quot;Configurable&quot;
(or &quot;Not configurable&quot;) means that the symbol is initially (or &quot;Not configurable&quot;) means that the symbol is initially
chosen (or not) based on --enable/--disable options at configure time. chosen (or not) based on --enable/--disable options at configure time.
</p>
<dl> <dl>
<dt><code>_GLIBCPP_DEPRECATED</code></dt> <dt><code>_GLIBCPP_DEPRECATED</code></dt>
<dd>Undefined by default. Not configurable. Turning this on enables <dd>Undefined by default. Not configurable. Turning this on enables
@ -329,7 +332,6 @@
</dd> </dd>
--> -->
</dl> </dl>
</p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
@ -338,7 +340,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="license.html">license.html</a> for copying conditions. See <a href="license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

31
libstdc++-v3/docs/html/17_intro/license.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, license, licence"> <meta name="KEYWORDS" content="libstdc++, license, licence" />
<meta name="DESCRIPTION" content="Copying restrictions for libstdc++."> <meta name="DESCRIPTION" content="Copying restrictions for libstdc++." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 copying</title> <title>libstdc++-v3 copying</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -21,7 +20,7 @@
writing this page is a programmer, not a lawyer. writing this page is a programmer, not a lawyer.
</p> </p>
<hr> <hr />
<h2>The Code: Runtime GPL</h2> <h2>The Code: Runtime GPL</h2>
@ -29,7 +28,8 @@
<a href="COPYING">GNU General Public License</a>, with the so-called <a href="COPYING">GNU General Public License</a>, with the so-called
&quot;runtime exception,&quot; as follows (or see any header or &quot;runtime exception,&quot; as follows (or see any header or
implementation file): implementation file):
<pre> </p>
<pre>
As a special exception, you may use this file as part of a free software As a special exception, you may use this file as part of a free software
library without restriction. Specifically, if other files instantiate library without restriction. Specifically, if other files instantiate
templates or use macros or inline functions from this file, or you compile templates or use macros or inline functions from this file, or you compile
@ -38,8 +38,7 @@
the GNU General Public License. This exception does not however the GNU General Public License. This exception does not however
invalidate any other reasons why the executable file might be covered by invalidate any other reasons why the executable file might be covered by
the GNU General Public License. the GNU General Public License.
</pre> </pre>
</p>
<p>Hopefully that text is self-explanatory. If it isn't, you need to speak <p>Hopefully that text is self-explanatory. If it isn't, you need to speak
to your lawyer, or the Free Software Foundation. to your lawyer, or the Free Software Foundation.
@ -50,14 +49,14 @@
http://gcc.gnu.org/ml/libstdc++/2000-q2/subjects.html#00050 http://gcc.gnu.org/ml/libstdc++/2000-q2/subjects.html#00050
--> -->
<p><strong>Q: So any program which uses libstdc++ falls under the GPL?</strong> <p><strong>Q: So any program which uses libstdc++ falls under the GPL?</strong>
<br>A: <strong>No.</strong> The special exception permits use of the <br />A: <strong>No.</strong> The special exception permits use of the
library in proprietary applications. library in proprietary applications.
</p> </p>
<p><strong>Q: How is that different from the GNU {Lesser,Library} <p><strong>Q: How is that different from the GNU {Lesser,Library}
GPL?</strong> GPL?</strong>
<!-- Quoting Jason Merrill from the thread above: --> <!-- Quoting Jason Merrill from the thread above: -->
<br>A: The LGPL requires that users be able to replace the LGPL code with a <br />A: The LGPL requires that users be able to replace the LGPL code with a
modified version; this is trivial if the library in question is a C modified version; this is trivial if the library in question is a C
shared library. But there's no way to make that work with C++, where shared library. But there's no way to make that work with C++, where
much of the library consists of inline functions and templates, which much of the library consists of inline functions and templates, which
@ -68,11 +67,11 @@
<p><strong>Q: I see. So, what restrictions <em>are</em> there on <p><strong>Q: I see. So, what restrictions <em>are</em> there on
programs that use the library?</strong> programs that use the library?</strong>
<br>A: None. We encourage such programs to be released as open source, <br />A: None. We encourage such programs to be released as open source,
but we won't punish you or sue you if you choose otherwise. but we won't punish you or sue you if you choose otherwise.
</p> </p>
<hr> <hr />
<h2>The Docs: FDL</h2> <h2>The Docs: FDL</h2>
@ -92,7 +91,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
Comments and suggestions about this page are welcome, and may be sent to Comments and suggestions about this page are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.

99
libstdc++-v3/docs/html/18_support/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 18</title> <title>libstdc++-v3 HOWTO: Chapter 18</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -24,17 +23,17 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Types</a> <li><a href="#1">Types</a></li>
<li><a href="#2">Implementation properties</a> <li><a href="#2">Implementation properties</a></li>
<li><a href="#3">Start and Termination</a> <li><a href="#3">Start and Termination</a></li>
<li><a href="#4">Dynamic memory management</a> <li><a href="#4">Dynamic memory management</a></li>
<li><a href="#5">RTTI, the ABI, and demangling</a> <li><a href="#5">RTTI, the ABI, and demangling</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -55,12 +54,13 @@
always a pointer.) always a pointer.)
</p> </p>
<p>In his book <p>In his book
<a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&ptype=0"><em>Effective C++</em></a>, <a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&amp;ptype=0"><em>Effective C++</em></a>,
Scott Meyers points out that the best way to solve this problem is to 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 not overload on pointer-vs-integer types to begin with. He also
offers a way to make your own magic NULL that will match pointers offers a way to make your own magic NULL that will match pointers
before it matches integers: before it matches integers:
<pre> </p>
<pre>
const // this is a const object... const // this is a const object...
class { class {
public: public:
@ -77,7 +77,8 @@
// taken (see Item 27)... // taken (see Item 27)...
} NULL; // and whose name is NULL } NULL; // and whose name is NULL
</pre>(Cribbed from the published version of </pre>
<p>(Cribbed from the published version of
<a href="http://www.awlonline.com/cseng/meyerscddemo/">the <a href="http://www.awlonline.com/cseng/meyerscddemo/">the
Effective C++ CD</a>, reproduced here with permission.) Effective C++ CD</a>, reproduced here with permission.)
</p> </p>
@ -93,7 +94,7 @@
print this stuff, it prompted him to run this code through current print this stuff, it prompted him to run this code through current
compilers to see what the state of the art is with respect to member compilers to see what the state of the art is with respect to member
template functions. He posted template functions. He posted
<a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&CONTEXT=964036823.871301239">an <a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&amp;CONTEXT=964036823.871301239">an
article to Usenet</a> after discovering that the code above is not article to Usenet</a> after discovering that the code above is not
valid! Even though it has no data members, it still needs a valid! Even though it has no data members, it still needs a
user-defined constructor (which means that the class needs a type name user-defined constructor (which means that the class needs a type name
@ -105,14 +106,14 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Implementation properties</a></h2> <h2><a name="2">Implementation properties</a></h2>
<p>
<h3><code>&lt;limits&gt;</code></h3> <h3><code>&lt;limits&gt;</code></h3>
This header mainly defines traits classes to give access to various <p>This header mainly defines traits classes to give access to various
implementation defined-aspects of the fundamental types. The implementation defined-aspects of the fundamental types. The
traits classes -- fourteen in total -- are all specilizations of the traits classes -- fourteen in total -- are all specilizations of the
template class <code>numeric_limits</code> defined as follows: template class <code>numeric_limits</code> defined as follows:
</p>
<pre> <pre>
template&lt;typename T&gt; struct class { template&lt;typename T&gt; struct class {
static const bool is_specialized; static const bool is_specialized;
@ -150,12 +151,11 @@
static const bool tinyness_before; static const bool tinyness_before;
static const float_round_style round_style; static const float_round_style round_style;
};</pre> };</pre>
</p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Start and Termination</a></h2> <h2><a name="3">Start and Termination</a></h2>
<p>Not many changes here to <code>&lt;cstdlib&gt;</code> (the old stdlib.h). <p>Not many changes here to <code>&lt;cstdlib&gt;</code> (the old stdlib.h).
You should note that the <code>abort()</code> function does not call You should note that the <code>abort()</code> function does not call
@ -166,11 +166,14 @@
</p> </p>
<p>The good old <code>exit()</code> function can be a bit funky, too, until <p>The good old <code>exit()</code> function can be a bit funky, too, until
you look closer. Basically, three points to remember are: you look closer. Basically, three points to remember are:
</p>
<ol> <ol>
<li>Static objects are destroyed in reverse order of their creation. <li>Static objects are destroyed in reverse order of their creation.
</li>
<li>Functions registered with <code>atexit()</code> are called in <li>Functions registered with <code>atexit()</code> are called in
reverse order of registration, once per registration call. reverse order of registration, once per registration call.
(This isn't actually new.) (This isn't actually new.)
</li>
<li>The previous two actions are &quot;interleaved,&quot; that is, <li>The previous two actions are &quot;interleaved,&quot; that is,
given this pseudocode: given this pseudocode:
<pre> <pre>
@ -181,12 +184,13 @@
atexit(f1); atexit(f1);
static Thing obj2; static Thing obj2;
atexit(f2); atexit(f2);
</pre>then at a call of <code>exit()</code>, f2 will be called, then </pre>
then at a call of <code>exit()</code>, f2 will be called, then
obj2 will be destroyed, then f1 will be called, and finally obj1 obj2 will be destroyed, then f1 will be called, and finally obj1
will be destroyed. If f1 or f2 allow an exception to propagate will be destroyed. If f1 or f2 allow an exception to propagate
out of them, Bad Things happen. out of them, Bad Things happen.
</li>
</ol> </ol>
</p>
<p>Note also that <code>atexit()</code> is only required to store 32 <p>Note also that <code>atexit()</code> is only required to store 32
functions, and the compiler/library might already be using some of functions, and the compiler/library might already be using some of
those slots. If you think you may run out, we recommend using those slots. If you think you may run out, we recommend using
@ -196,21 +200,22 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">Dynamic memory management</a></h2> <h2><a name="4">Dynamic memory management</a></h2>
<p>There are six flavors each of <code>new</code> and <code>delete</code>, so <p>There are six flavors each of <code>new</code> and <code>delete</code>, so
make certain that you're using the right ones! Here are quickie make certain that you're using the right ones! Here are quickie
descriptions of <code>new</code>: descriptions of <code>new</code>:
<ul> </p>
<li>single object form, throwing a <code>bad_alloc</code> on errors; <ul>
this is what most people are used to using <li>single object form, throwing a <code>bad_alloc</code> on errors;
<li>single object &quot;nothrow&quot; form, returning NULL on errors this is what most people are used to using</li>
<li>array new, throwing <code>bad_alloc</code> on errors <li>single object &quot;nothrow&quot; form, returning NULL on errors</li>
<li>array nothrow new, returning NULL on errors <li>array new, throwing <code>bad_alloc</code> on errors</li>
<li>placement new, which does nothing (like it's supposed to) <li>array nothrow new, returning NULL on errors</li>
<li>placement array new, which also does nothing <li>placement new, which does nothing (like it's supposed to)</li>
</ul> <li>placement array new, which also does nothing</li>
They are distinguished by the parameters that you pass to them, like </ul>
<p>They are distinguished by the parameters that you pass to them, like
any other overloaded function. The six flavors of <code>delete</code> any other overloaded function. The six flavors of <code>delete</code>
are distinguished the same way, but none of them are allowed to throw are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (They match up for an exception under any circumstances anyhow. (They match up for
@ -225,7 +230,8 @@
<code>bad_alloc</code> exception (or, technically, some class derived <code>bad_alloc</code> exception (or, technically, some class derived
from it). You can change this by writing your own function (called a from it). You can change this by writing your own function (called a
new-handler) and then registering it with <code>set_new_handler()</code>: new-handler) and then registering it with <code>set_new_handler()</code>:
<pre> </p>
<pre>
typedef void (*PFV)(void); typedef void (*PFV)(void);
static char* safety; static char* safety;
@ -247,8 +253,7 @@
old_handler = set_new_handler (&amp;my_new_handler); old_handler = set_new_handler (&amp;my_new_handler);
... ...
} }
</pre> </pre>
</p>
<p><code>bad_alloc</code> is derived from the base <code>exception</code> <p><code>bad_alloc</code> is derived from the base <code>exception</code>
class defined in Chapter 19. class defined in Chapter 19.
</p> </p>
@ -256,7 +261,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">RTTI, the ABI, and demangling</a></h2> <h2><a name="5">RTTI, the ABI, and demangling</a></h2>
<p>If you have read the <a href="../documentation.html#4">source <p>If you have read the <a href="../documentation.html#4">source
documentation</a> for <code> namespace abi </code> then you are aware documentation</a> for <code> namespace abi </code> then you are aware
@ -271,7 +276,8 @@
<p>Probably the only times you'll be interested in demangling at runtime <p>Probably the only times you'll be interested in demangling at runtime
are when you're seeing <code>typeid</code> strings in RTTI, or when are when you're seeing <code>typeid</code> strings in RTTI, or when
you're handling the runtime-support exception classes. For example: you're handling the runtime-support exception classes. For example:
<pre> </p>
<pre>
#include &lt;exception&gt; #include &lt;exception&gt;
#include &lt;iostream&gt; #include &lt;iostream&gt;
#include &lt;cxxabi.h&gt; #include &lt;cxxabi.h&gt;
@ -304,11 +310,12 @@ int main()
free(realname); free(realname);
return 0; return 0;
}</pre></p> }</pre>
<p>With GCC 3.1 and later, this prints<pre> <p>With GCC 3.1 and later, this prints
St13bad_exception =&gt; std::bad_exception : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0</pre>
</p> </p>
<pre>
St13bad_exception =&gt; std::bad_exception : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0 </pre>
<p>The demangler interface is described in the source documentation <p>The demangler interface is described in the source documentation
linked to above. It is actually written in C, so you don't need to linked to above. It is actually written in C, so you don't need to
be writing C++ in order to demangle C++. (That also means we have to be writing C++ in order to demangle C++. (That also means we have to
@ -322,7 +329,7 @@ int main()
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

48
libstdc++-v3/docs/html/19_diagnostics/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 19</title> <title>libstdc++-v3 HOWTO: Chapter 19</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -20,16 +19,16 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Adding data to exceptions</a> <li><a href="#1">Adding data to exceptions</a></li>
<li><a href="#2">Exception class hierarchy diagram</a> <li><a href="#2">Exception class hierarchy diagram</a></li>
<li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a> <li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a></li>
<li><a href="#4">Verbose <code>terminate</code></a> <li><a href="#4">Verbose <code>terminate</code></a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -56,7 +55,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Exception class hierarchy diagram</a></h2> <h2><a name="2">Exception class hierarchy diagram</a></h2>
<p>At one point we were going to make up a PDF of the exceptions <p>At one point we were going to make up a PDF of the exceptions
hierarchy, akin to the one done for the I/O class hierarchy. hierarchy, akin to the one done for the I/O class hierarchy.
@ -72,7 +71,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2> <h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2>
<p>Better taste! Less fat! Literally!</p> <p>Better taste! Less fat! Literally!</p>
<p>In 1999, SGI added <em>concept checkers</em> to their implementation <p>In 1999, SGI added <em>concept checkers</em> to their implementation
@ -89,7 +88,7 @@
were found in it on more than one occasion. were found in it on more than one occasion.
</p> </p>
<p>The primary author of the checking code, Jeremy Siek, had already <p>The primary author of the checking code, Jeremy Siek, had already
started work on a replcement implementation. The new code has been started work on a replacement implementation. The new code has been
formally reviewed and accepted into formally reviewed and accepted into
<a href="http://www.boost.org/libs/concept_check/concept_check.htm">the <a href="http://www.boost.org/libs/concept_check/concept_check.htm">the
Boost libraries</a>, and we are pleased to incorporate it into the Boost libraries</a>, and we are pleased to incorporate it into the
@ -109,12 +108,13 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">Verbose <code>terminate</code></a></h2> <h2><a name="4">Verbose <code>terminate</code></a></h2>
<p>If you are having difficulty with uncaught exceptions and want a <p>If you are having difficulty with uncaught exceptions and want a
little bit of help debugging the causes of the core dumps, you can little bit of help debugging the causes of the core dumps, you can
make use of a GNU extension in GCC 3.1 and later: make use of a GNU extension in GCC 3.1 and later:
<pre> </p>
<pre>
#include &lt;exception&gt; #include &lt;exception&gt;
int main() int main()
@ -123,7 +123,6 @@
... ...
throw <em>anything</em>; throw <em>anything</em>;
}</pre> }</pre>
</p>
<p>The <code> __verbose_terminate_handler </code> function obtains the name <p>The <code> __verbose_terminate_handler </code> function obtains the name
of the current exception, attempts to demangle it, and prints it to of the current exception, attempts to demangle it, and prints it to
stderr. If the exception is derived from <code> std::exception </code> stderr. If the exception is derived from <code> std::exception </code>
@ -133,7 +132,8 @@
without returning; this one calls abort. without returning; this one calls abort.
</p> </p>
<p>For example: <p>For example:
<pre> </p>
<pre>
#include &lt;exception&gt; #include &lt;exception&gt;
#include &lt;stdexcept&gt; #include &lt;stdexcept&gt;
@ -151,9 +151,9 @@
else else
throw argc; throw argc;
}</pre> }</pre>
</p>
<p>In GCC 3.1 and later, this gives <p>In GCC 3.1 and later, this gives
<pre> </p>
<pre>
% ./a.out % ./a.out
terminate called after throwing a `int' terminate called after throwing a `int'
Aborted Aborted
@ -162,7 +162,7 @@
what(): argc is greater than 5! what(): argc is greater than 5!
Aborted Aborted
%</pre> %</pre>
The 'Aborted' line comes from the call to abort(), of course. <p>The 'Aborted' line comes from the call to abort(), of course.
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
@ -171,7 +171,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

96
libstdc++-v3/docs/html/20_util/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 20</title> <title>libstdc++-v3 HOWTO: Chapter 20</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -19,16 +18,16 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1"><code>auto_ptr</code> is not omnipotent</a> <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li>
<li><a href="#2"><code>auto_ptr</code> inside container classes</a> <li><a href="#2"><code>auto_ptr</code> inside container classes</a></li>
<li><a href="#3">Functors</a> <li><a href="#3">Functors</a></li>
<li><a href="#4">Pairs</a> <li><a href="#4">Pairs</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -47,7 +46,8 @@
</p> </p>
<p>AP <em>is</em> meant to prevent nasty leaks in the presence of <p>AP <em>is</em> meant to prevent nasty leaks in the presence of
exceptions. That's <em>all</em>. This code is AP-friendly: exceptions. That's <em>all</em>. This code is AP-friendly:
<pre> </p>
<pre>
// not a recommend naming scheme, but good for web-based FAQs // not a recommend naming scheme, but good for web-based FAQs
typedef std::auto_ptr&lt;MyClass&gt; APMC; typedef std::auto_ptr&lt;MyClass&gt; APMC;
@ -62,21 +62,24 @@
function_taking_MyClass_pointer (ap.get()); function_taking_MyClass_pointer (ap.get());
} }
</pre>When an exception gets thrown, the instance of MyClass that's </pre>
<p>When an exception gets thrown, the instance of MyClass that's
been created on the heap will be <code>delete</code>'d as the stack is been created on the heap will be <code>delete</code>'d as the stack is
unwound past <code>func()</code>. unwound past <code>func()</code>.
</p> </p>
<p>Changing that code as follows is <em>not</em> AP-friendly: <p>Changing that code as follows is <em>not</em> AP-friendly:
<pre> </p>
<pre>
APMC ap (new MyClass[22]); APMC ap (new MyClass[22]);
</pre>You will get the same problems as you would without the use </pre>
<p>You will get the same problems as you would without the use
of AP: of AP:
<pre> </p>
<pre>
char* array = new char[10]; // array new... char* array = new char[10]; // array new...
... ...
delete array; // ...but single-object delete delete array; // ...but single-object delete
</pre> </pre>
</p>
<p>AP cannot tell whether the pointer you've passed at creation points <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 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 to die. AP is trivial to write, however, so you could write your
@ -87,18 +90,19 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2> <h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2>
<p>All of the <a href="../23_containers/howto.html">containers</a> <p>All of the <a href="../23_containers/howto.html">containers</a>
described in the standard library require their contained types described in the standard library require their contained types
to have, among other things, a copy constructor like this: to have, among other things, a copy constructor like this:
<pre> </p>
<pre>
struct My_Type struct My_Type
{ {
My_Type (My_Type const&amp;); My_Type (My_Type const&amp;);
}; };
</pre> </pre>
Note the const keyword; the object being copied shouldn't change. <p>Note the const keyword; the object being copied shouldn't change.
The template class <code>auto_ptr</code> (called AP here) does not The template class <code>auto_ptr</code> (called AP here) does not
meet this requirement. Creating a new AP by copying an existing meet this requirement. Creating a new AP by copying an existing
one transfers ownership of the pointed-to object, which means that one transfers ownership of the pointed-to object, which means that
@ -113,7 +117,8 @@
<a href="../19_diagnostics/howto.html#3">concept checks</a> built <a href="../19_diagnostics/howto.html#3">concept checks</a> built
in to this implementation will issue an error if you try to in to this implementation will issue an error if you try to
compile code like this: compile code like this:
<pre> </p>
<pre>
#include &lt;vector&gt; #include &lt;vector&gt;
#include &lt;memory&gt; #include &lt;memory&gt;
@ -121,14 +126,14 @@
{ {
std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int; std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int;
} }
</pre> </pre>
Should you try this with the checks enabled, you will see an error. <p>Should you try this with the checks enabled, you will see an error.
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Functors</a></h2> <h2><a name="3">Functors</a></h2>
<p>If you don't know what functors are, you're not alone. Many people <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 get slightly the wrong idea. In the interest of not reinventing
@ -141,7 +146,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">Pairs</a></h2> <h2><a name="4">Pairs</a></h2>
<p>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to <p>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to
carry around a pair of objects. One is of type T1, and another of carry around a pair of objects. One is of type T1, and another of
@ -151,16 +156,20 @@
</p> </p>
<p>Construction is simple. The default ctor initializes each member <p>Construction is simple. The default ctor initializes each member
with its respective default ctor. The other simple ctor, with its respective default ctor. The other simple ctor,
<pre> </p>
<pre>
pair (const T1&amp; x, const T2&amp; y); pair (const T1&amp; x, const T2&amp; y);
</pre>does what you think it does, <code>first</code> getting <code>x</code> </pre>
<p>does what you think it does, <code>first</code> getting <code>x</code>
and <code>second</code> getting <code>y</code>. and <code>second</code> getting <code>y</code>.
</p> </p>
<p>There is a copy constructor, but it requires that your compiler <p>There is a copy constructor, but it requires that your compiler
handle member function templates: handle member function templates:
<pre> </p>
<pre>
template &lt;class U, class V&gt; pain (const pair&lt;U,V&gt;&amp; p); template &lt;class U, class V&gt; pain (const pair&lt;U,V&gt;&amp; p);
</pre>The compiler will convert as necessary from U to T1 and from </pre>
<p>The compiler will convert as necessary from U to T1 and from
V to T2 in order to perform the respective initializations. V to T2 in order to perform the respective initializations.
</p> </p>
<p>The comparison operators are done for you. Equality <p>The comparison operators are done for you. Equality
@ -170,24 +179,25 @@
<code>operator==</code> functions (for types like MyClass) or builtin <code>operator==</code> functions (for types like MyClass) or builtin
comparisons (for types like int, char, etc). comparisons (for types like int, char, etc).
</p> </p>
<a name="pairlt"> <p><a name="pairlt">
<p>The less-than operator is a bit odd the first time you see it. It The less-than operator is a bit odd the first time you see it. It
is defined as evaluating to: is defined as evaluating to:
<pre> </a>
</p>
<pre>
x.first &lt; y.first || x.first &lt; y.first ||
( !(y.first &lt; x.first) &amp;&amp; x.second &lt; y.second ) ( !(y.first &lt; x.first) &amp;&amp; x.second &lt; y.second )
</pre> </pre>
The other operators are not defined using the <code>rel_ops</code> <p>The other operators are not defined using the <code>rel_ops</code>
functions above, but their semantics are the same. functions above, but their semantics are the same.
</p> </p>
</a>
<p>Finally, there is a template function called <code>make_pair</code> <p>Finally, there is a template function called <code>make_pair</code>
that takes two references-to-const objects and returns an that takes two references-to-const objects and returns an
instance of a pair instantiated on their respective types: instance of a pair instantiated on their respective types:
<pre>
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre>
</p> </p>
<pre>
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
@ -197,7 +207,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

103
libstdc++-v3/docs/html/21_strings/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 21</title> <title>libstdc++-v3 HOWTO: Chapter 21</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -18,17 +17,17 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">MFC's CString</a> <li><a href="#1">MFC's CString</a></li>
<li><a href="#2">A case-insensitive string class</a> <li><a href="#2">A case-insensitive string class</a></li>
<li><a href="#3">Breaking a C++ string into tokens</a> <li><a href="#3">Breaking a C++ string into tokens</a></li>
<li><a href="#4">Simple transformations</a> <li><a href="#4">Simple transformations</a></li>
<li><a href="#5">Making strings of arbitrary character types</a> <li><a href="#5">Making strings of arbitrary character types</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -43,24 +42,29 @@
<p>Things are not as bad as they seem. In <p>Things are not as bad as they seem. In
<a href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this <a href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this
message</a>, Joe Buck points out a few very important things: message</a>, Joe Buck points out a few very important things:
</p>
<ul> <ul>
<li>The Standard <code>string</code> supports all the operations <li>The Standard <code>string</code> supports all the operations
that CString does, with three exceptions. that CString does, with three exceptions.
</li>
<li>Two of those exceptions (whitespace trimming and case <li>Two of those exceptions (whitespace trimming and case
conversion) are trivial to implement. In fact, we do so conversion) are trivial to implement. In fact, we do so
on this page. on this page.
</li>
<li>The third is <code>CString::Format</code>, which allows formatting <li>The third is <code>CString::Format</code>, which allows formatting
in the style of <code>sprintf</code>. This deserves some mention: in the style of <code>sprintf</code>. This deserves some mention:
</li>
</ul> </ul>
</p> <p><a name="1.1internal"> <!-- Coming from Chapter 27 -->
<a name="1.1internal"> <!-- Coming from Chapter 27 --> The old libg++ library had a function called form(), which did much
<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 the same thing. But for a Standard solution, you should use the
stringstream classes. These are the bridge between the iostream stringstream classes. These are the bridge between the iostream
hierarchy and the string class, and they operate with regular hierarchy and the string class, and they operate with regular
streams seamlessly because they inherit from the iostream streams seamlessly because they inherit from the iostream
hierarchy. An quick example: hierarchy. An quick example:
<pre> </a>
</p>
<pre>
#include &lt;iostream&gt; #include &lt;iostream&gt;
#include &lt;string&gt; #include &lt;string&gt;
#include &lt;sstream&gt; #include &lt;sstream&gt;
@ -80,10 +84,10 @@
return output_stream.str(); return output_stream.str();
} </pre> } </pre>
</p></a>
<p>A serious problem with CString is a design bug in its memory <p>A serious problem with CString is a design bug in its memory
allocation. Specifically, quoting from that same message: allocation. Specifically, quoting from that same message:
<pre> </p>
<pre>
CString suffers from a common programming error that results in CString suffers from a common programming error that results in
poor performance. Consider the following code: poor performance. Consider the following code:
@ -104,22 +108,25 @@
If you replace CString with string in the above function, the If you replace CString with string in the above function, the
performance is O(n). performance is O(n).
</pre> </pre>
</p>
<p>Joe Buck also pointed out some other things to keep in mind when <p>Joe Buck also pointed out some other things to keep in mind when
comparing CString and the Standard string class: comparing CString and the Standard string class:
</p>
<ul> <ul>
<li>CString permits access to its internal representation; coders <li>CString permits access to its internal representation; coders
who exploited that may have problems moving to <code>string</code>. who exploited that may have problems moving to <code>string</code>.
</li>
<li>Microsoft ships the source to CString (in the files <li>Microsoft ships the source to CString (in the files
MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation
bug and rebuild your MFC libraries. bug and rebuild your MFC libraries.
<em><B>Note:</B> It looks like the the CString shipped with <em><strong>Note:</strong> It looks like the the CString shipped
VC++6.0 has fixed this, although it may in fact have been one with VC++6.0 has fixed this, although it may in fact have been
of the VC++ SPs that did it.</em> one of the VC++ SPs that did it.</em>
</li>
<li><code>string</code> operations like this have O(n) complexity <li><code>string</code> operations like this have O(n) complexity
<em>if the implementors do it correctly</em>. The libstdc++ <em>if the implementors do it correctly</em>. The libstdc++
implementors did it correctly. Other vendors might not. implementors did it correctly. Other vendors might not.
</li>
<li>While parts of the SGI STL are used in libstdc++-v3, their <li>While parts of the SGI STL are used in libstdc++-v3, their
string class is not. The SGI <code>string</code> is essentially string class is not. The SGI <code>string</code> is essentially
<code>vector&lt;char&gt;</code> and does not do any reference <code>vector&lt;char&gt;</code> and does not do any reference
@ -129,13 +136,13 @@
libstdc++ string, the SGI string, and the SGI rope, and this libstdc++ string, the SGI string, and the SGI rope, and this
is all before any allocator or traits customizations! (More is all before any allocator or traits customizations! (More
choices than you can shake a stick at -- want fries with that?) choices than you can shake a stick at -- want fries with that?)
</li>
</ul> </ul>
</p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">A case-insensitive string class</a></h2> <h2><a name="2">A case-insensitive string class</a></h2>
<p>The well-known-and-if-it-isn't-well-known-it-ought-to-be <p>The well-known-and-if-it-isn't-well-known-it-ought-to-be
<a href="http://www.peerdirect.com/resources/">Guru of the Week</a> <a href="http://www.peerdirect.com/resources/">Guru of the Week</a>
@ -144,7 +151,8 @@
is identical to the standard 'string' class, but is is identical to the standard 'string' class, but is
case-insensitive in the same way as the (common but nonstandard) case-insensitive in the same way as the (common but nonstandard)
C function stricmp():&quot; C function stricmp():&quot;
<pre> </p>
<pre>
ci_string s( "AbCdE" ); ci_string s( "AbCdE" );
// case insensitive // case insensitive
@ -154,7 +162,6 @@
// still case-preserving, of course // still case-preserving, of course
assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre> assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre>
</p>
<p>The solution is surprisingly easy. The original answer pages <p>The solution is surprisingly easy. The original answer pages
on the GotW website were removed into cold storage, in on the GotW website were removed into cold storage, in
@ -189,7 +196,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Breaking a C++ string into tokens</a></h2> <h2><a name="3">Breaking a C++ string into tokens</a></h2>
<p>The Standard C (and C++) function <code>strtok()</code> leaves a lot to <p>The Standard C (and C++) function <code>strtok()</code> leaves a lot to
be desired in terms of user-friendliness. It's unintuitive, it be desired in terms of user-friendliness. It's unintuitive, it
@ -210,21 +217,23 @@
comments on what kind of string it will accept). The author uses comments on what kind of string it will accept). The author uses
a more general (but less readable) form of it for parsing command 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: strings and the like. If you compiled and ran this code using it:
<pre> </p>
<pre>
std::list&lt;string&gt; ls; std::list&lt;string&gt; ls;
stringtok (ls, " this \t is\t\n a test "); stringtok (ls, " this \t is\t\n a test ");
for (std::list&lt;string&gt;const_iterator i = ls.begin(); for (std::list&lt;string&gt;const_iterator i = ls.begin();
i != ls.end(); ++i) i != ls.end(); ++i)
{ {
std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n"; std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n";
}</pre> } </pre>
You would see this as output: <p>You would see this as output:
<pre> </p>
<pre>
:this: :this:
:is: :is:
:a: :a:
:test:</pre> :test: </pre>
with all the whitespace removed. The original <code>s</code> is still <p>with all the whitespace removed. The original <code>s</code> is still
available for use, <code>ls</code> will clean up after itself, and available for use, <code>ls</code> will clean up after itself, and
<code>ls.size()</code> will return how many tokens there were. <code>ls.size()</code> will return how many tokens there were.
</p> </p>
@ -248,7 +257,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">Simple transformations</a></h2> <h2><a name="4">Simple transformations</a></h2>
<p>Here are Standard, simple, and portable ways to perform common <p>Here are Standard, simple, and portable ways to perform common
transformations on a <code>string</code> instance, such as &quot;convert transformations on a <code>string</code> instance, such as &quot;convert
@ -258,7 +267,8 @@
</p> </p>
<p>This code will go through some iterations (no pun). Here's the <p>This code will go through some iterations (no pun). Here's the
simplistic version usually seen on Usenet: simplistic version usually seen on Usenet:
<pre> </p>
<pre>
#include &lt;string&gt; #include &lt;string&gt;
#include &lt;algorithm&gt; #include &lt;algorithm&gt;
#include &lt;cctype&gt; // old &lt;ctype.h&gt; #include &lt;cctype&gt; // old &lt;ctype.h&gt;
@ -276,7 +286,7 @@
std::string capital_s; std::string capital_s;
capital_s.reserve(s.size()); capital_s.reserve(s.size());
std::transform (s.begin(), s.end(), capital_s.begin(), tolower); </pre> std::transform (s.begin(), s.end(), capital_s.begin(), tolower); </pre>
<span class="larger"><strong>Note</strong></span> that these calls all <p><span class="larger"><strong>Note</strong></span> that these calls all
involve the global C locale through the use of the C functions involve the global C locale through the use of the C functions
<code>toupper/tolower</code>. This is absolutely guaranteed to work -- <code>toupper/tolower</code>. This is absolutely guaranteed to work --
but <em>only</em> if the string contains <em>only</em> characters but <em>only</em> if the string contains <em>only</em> characters
@ -287,12 +297,12 @@
characters (hahahahahaha), then you're done. characters (hahahahahaha), then you're done.
</p> </p>
<p>At minimum, you can write short wrappers like <p>At minimum, you can write short wrappers like
<pre> </p>
<pre>
char toLower (char c) char toLower (char c)
{ {
return tolower(static_cast&lt;unsigned char&gt;(c)); return tolower(static_cast&lt;unsigned char&gt;(c));
}</pre> } </pre>
</p>
<p>The correct method is to use a facet for a particular locale <p>The correct method is to use a facet for a particular locale
and call its conversion functions. These are discussed more in and call its conversion functions. These are discussed more in
Chapter 22; the specific part is Chapter 22; the specific part is
@ -304,7 +314,8 @@
like transformations, this task is trivial with the use of string's like transformations, this task is trivial with the use of string's
<code>find</code> family. These examples are broken into multiple <code>find</code> family. These examples are broken into multiple
statements for readability: statements for readability:
<pre> </p>
<pre>
std::string str (" \t blah blah blah \n "); std::string str (" \t blah blah blah \n ");
// trim leading whitespace // trim leading whitespace
@ -314,7 +325,7 @@
// trim trailing whitespace // trim trailing whitespace
notwhite = str.find_last_not_of(" \t\n"); notwhite = str.find_last_not_of(" \t\n");
str.erase(notwhite+1); </pre> str.erase(notwhite+1); </pre>
Obviously, the calls to <code>find</code> could be inserted directly <p>Obviously, the calls to <code>find</code> could be inserted directly
into the calls to <code>erase</code>, in case your compiler does not into the calls to <code>erase</code>, in case your compiler does not
optimize named temporaries out of existence. optimize named temporaries out of existence.
</p> </p>
@ -322,7 +333,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">Making strings of arbitrary character types</a></h2> <h2><a name="5">Making strings of arbitrary character types</a></h2>
<p>how to work with char_traits -- in the archives, just need to <p>how to work with char_traits -- in the archives, just need to
go through and pull the examples together go through and pull the examples together
@ -335,7 +346,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

229
libstdc++-v3/docs/html/22_locale/codecvt.html
View file

@ -1,18 +1,21 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
Notes on the codecvt implementation. <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
</title> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes on the codecvt implementation." />
<title>Notes on the codecvt implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
<h1> <h1>
Notes on the codecvt implementation. Notes on the codecvt implementation.
</h1> </h1>
<p> <p>
<I> <em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000 prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000
</I> </em>
</p>
<h2> <h2>
1. Abstract 1. Abstract
@ -33,26 +36,25 @@ wide and narrow characters and the implementation-provided extended
functionality are given. functionality are given.
</p> </p>
<p>
<h2> <h2>
2. What the standard says 2. What the standard says
</h2> </h2>
Around page 425 of the C++ Standard, this charming heading comes into view: Around page 425 of the C++ Standard, this charming heading comes into view:
<BLOCKQUOTE> <blockquote>
22.2.1.5 - Template class codecvt [lib.locale.codecvt] 22.2.1.5 - Template class codecvt [lib.locale.codecvt]
</BLOCKQUOTE> </blockquote>
The text around the codecvt definition gives some clues: The text around the codecvt definition gives some clues:
<BLOCKQUOTE> <blockquote>
<I> <em>
-1- The class codecvt&lt;internT,externT,stateT&gt; is for use when -1- The class codecvt&lt;internT,externT,stateT&gt; is for use when
converting from one codeset to another, such as from wide characters converting from one codeset to another, such as from wide characters
to multibyte characters, between wide character encodings such as to multibyte characters, between wide character encodings such as
Unicode and EUC. Unicode and EUC.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p> <p>
Hmm. So, in some unspecified way, Unicode encodings and Hmm. So, in some unspecified way, Unicode encodings and
@ -60,18 +62,18 @@ translations between other character sets should be handled by this
class. class.
</p> </p>
<BLOCKQUOTE> <blockquote>
<I> <em>
-2- The stateT argument selects the pair of codesets being mapped between. -2- The stateT argument selects the pair of codesets being mapped between.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p> <p>
Ah ha! Another clue... Ah ha! Another clue...
</p> </p>
<BLOCKQUOTE> <blockquote>
<I> <em>
-3- The instantiations required in the Table ?? -3- The instantiations required in the Table ??
(lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and (lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and
codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
@ -83,11 +85,12 @@ mbstate_t perform conversion between encodings known to the library
implementor. Other encodings can be converted by specializing on a implementor. Other encodings can be converted by specializing on a
user-defined stateT type. The stateT object can contain any state that user-defined stateT type. The stateT object can contain any state that
is useful to communicate to or from the specialized do_convert member. is useful to communicate to or from the specialized do_convert member.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p> <p>
At this point, a couple points become clear: At this point, a couple points become clear:
</p>
<p> <p>
One: The standard clearly implies that attempts to add non-required One: The standard clearly implies that attempts to add non-required
@ -100,7 +103,6 @@ template parameter, imply an implementation strategy that is mostly
(or wholly) based on the underlying C library, and the functions (or wholly) based on the underlying C library, and the functions
mcsrtombs and wcsrtombs in particular.</p> mcsrtombs and wcsrtombs in particular.</p>
<p>
<h2> <h2>
3. Some thoughts on what would be useful 3. Some thoughts on what would be useful
</h2> </h2>
@ -121,15 +123,19 @@ represent wide characters, and use an internal encoding of
UCS4. (GNU/Linux systems using glibc, in particular.) The C UCS4. (GNU/Linux systems using glibc, in particular.) The C
programming language (and thus C++) does not specify a specific size programming language (and thus C++) does not specify a specific size
for the type wchar_t. for the type wchar_t.
</p>
<p> <p>
Thus, portable C++ code cannot assume a byte size (or endianness) either. Thus, portable C++ code cannot assume a byte size (or endianness) either.
</p>
<p> <p>
Getting back to the frequently asked question: What about Unicode strings? Getting back to the frequently asked question: What about Unicode strings?
</p>
<p> <p>
What magic spell will do this conversion? What magic spell will do this conversion?
</p>
<p> <p>
A couple of comments: A couple of comments:
@ -153,12 +159,14 @@ example, using the iconv family of functions from the Single Unix
Specification (what used to be called X/Open) hosted on the GNU/Linux Specification (what used to be called X/Open) hosted on the GNU/Linux
operating system allows bi-directional mapping between far more than operating system allows bi-directional mapping between far more than
the following tantalizing possibilities: the following tantalizing possibilities:
</p>
<p> <p>
(An edited list taken from <code>`iconv --list`</code> on a Red Hat 6.2/Intel system: (An edited list taken from <code>`iconv --list`</code> on a Red Hat 6.2/Intel system:
</p>
<BLOCKQUOTE> <blockquote>
<PRE> <pre>
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7, 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, 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, GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
@ -168,8 +176,8 @@ 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, 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, UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16). UTF-16, UTF8, UTF16).
</PRE> </pre>
</BLOCKQUOTE> </blockquote>
<p> <p>
For iconv-based implementations, string literals for each of the For iconv-based implementations, string literals for each of the
@ -177,9 +185,12 @@ encodings (ie. &quot;UCS-2&quot; and &quot;UTF-8&quot;) are necessary,
although for other, although for other,
non-iconv implementations a table of enumerated values or some other non-iconv implementations a table of enumerated values or some other
mechanism may be required. mechanism may be required.
</p>
</li>
<li> <li>
Maximum length of the identifying string literal. Maximum length of the identifying string literal.
</li>
<li> <li>
Some encodings are require explicit endian-ness. As such, some kind Some encodings are require explicit endian-ness. As such, some kind
@ -187,6 +198,7 @@ mechanism may be required.
&quot;Footnotes for C/C++ developers&quot; in Haible for more information on &quot;Footnotes for C/C++ developers&quot; in Haible for more information on
UCS-2/Unicode endian issues. (Summary: big endian seems most likely, UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
however implementations, most notably Microsoft, vary.) however implementations, most notably Microsoft, vary.)
</li>
<li> <li>
Types representing the conversion state, for conversions involving Types representing the conversion state, for conversions involving
@ -194,24 +206,28 @@ mechanism may be required.
conversions using iconv (such as the type iconv_t.) Note that the conversions using iconv (such as the type iconv_t.) Note that the
conversion descriptor encodes more information than a simple encoding conversion descriptor encodes more information than a simple encoding
state type. state type.
</li>
<li> <li>
Conversion descriptors for both directions of encoding. (ie, both Conversion descriptors for both directions of encoding. (ie, both
UCS-2 to UTF-8 and UTF-8 to UCS-2.) UCS-2 to UTF-8 and UTF-8 to UCS-2.)
</li>
<li> <li>
Something to indicate if the conversion requested if valid. Something to indicate if the conversion requested if valid.
</li>
<li> <li>
Something to represent if the conversion descriptors are valid. Something to represent if the conversion descriptors are valid.
</li>
<li> <li>
Some way to enforce strict type checking on the internal and 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. As part of this, the size of the internal and
external types will need to be known. external types will need to be known.
</li>
</ul> </ul>
<p>
<h2> <h2>
4. Problems with &quot;C&quot; code conversions : thread safety, global 4. Problems with &quot;C&quot; code conversions : thread safety, global
locales, termination. locales, termination.
@ -224,11 +240,13 @@ when implemented using standard &quot;C&quot; functions.
<p> <p>
Three problems arise, one big, one of medium importance, and one small. Three problems arise, one big, one of medium importance, and one small.
</p>
<p> <p>
First, the small: mcsrtombs and wcsrtombs may not be multithread-safe First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc, on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue. this is not an issue.
</p>
<p> <p>
Of medium concern, in the grand scope of things, is that the functions Of medium concern, in the grand scope of things, is that the functions
@ -236,6 +254,7 @@ used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated, strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise thus giving conversions that end prematurely or are otherwise
incorrect. Yikes! incorrect. Yikes!
</p>
<p> <p>
The last, and fundamental problem, is the assumption of a global The last, and fundamental problem, is the assumption of a global
@ -247,14 +266,15 @@ the GNU C++ library would like to offer a solution that allows
multiple locales and or simultaneous usage with computationally multiple locales and or simultaneous usage with computationally
correct results. In short, libstdc++-v3 is trying to offer, as an correct results. In short, libstdc++-v3 is trying to offer, as an
option, a high-quality implementation, damn the additional complexity! option, a high-quality implementation, damn the additional complexity!
</p>
<p> <p>
For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; , For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
conversions are made between the internal character set (always UCS4 conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements. LC_CTYPE category implements.
</p>
<p>
<h2> <h2>
5. Design 5. Design
</h2> </h2>
@ -264,25 +284,30 @@ The two required specializations are implemented as follows:
<code> <code>
codecvt&lt;char, char, mbstate_t&gt; codecvt&lt;char, char, mbstate_t&gt;
</code> </code>
</p>
<p> <p>
This is a degenerate (ie, does nothing) specialization. Implementing This is a degenerate (ie, does nothing) specialization. Implementing
this was a piece of cake. this was a piece of cake.
</p>
<p> <p>
<code> <code>
codecvt&lt;char, wchar_t, mbstate_t&gt; codecvt&lt;char, wchar_t, mbstate_t&gt;
</code> </code>
</p>
<p> <p>
This specialization, by specifying all the template parameters, pretty This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char. to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p>
<p> <p>
Neither of these two required specializations deals with Unicode Neither of these two required specializations deals with Unicode
characters. As such, libstdc++-v3 implements a partial specialization characters. As such, libstdc++-v3 implements a partial specialization
of the codecvt class with and iconv wrapper class, __enc_traits as the of the codecvt class with and iconv wrapper class, __enc_traits as the
third template parameter. third template parameter.
</p>
<p> <p>
This implementation should be standards conformant. First of all, the This implementation should be standards conformant. First of all, the
@ -293,33 +318,40 @@ non-required conversions. Second of all, the standard says (in Chapter
of all, the requirements for the stateT type elsewhere in the standard 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 (see 21.1.2 traits typedefs) only indicate that this type be copy
constructible. constructible.
</p>
<p> <p>
As such, the type __enc_traits is defined as a non-templatized, POD As such, the type __enc_traits is defined as a non-templatized, POD
type to be used as the third type of a codecvt instantiation. This 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 type is just a wrapper class for iconv, and provides an easy interface
to iconv functionality. to iconv functionality.
</p>
<p> <p>
There are two constructors for __enc_traits: There are two constructors for __enc_traits:
</p>
<p> <p>
<code> <code>
__enc_traits() : __in_desc(0), __out_desc(0) __enc_traits() : __in_desc(0), __out_desc(0)
</code> </code>
</p>
<p> <p>
This default constructor sets the internal encoding to some default This default constructor sets the internal encoding to some default
(currently UCS4) and the external encoding to whatever is returned by (currently UCS4) and the external encoding to whatever is returned by
nl_langinfo(CODESET). nl_langinfo(CODESET).
</p>
<p> <p>
<code> <code>
__enc_traits(const char* __int, const char* __ext) __enc_traits(const char* __int, const char* __ext)
</code> </code>
</p>
<p> <p>
This constructor takes as parameters string literals that indicate the This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for desired internal and external encoding. There are no defaults for
either argument. either argument.
</p>
<p> <p>
One of the issues with iconv is that the string literals identifying One of the issues with iconv is that the string literals identifying
@ -330,24 +362,28 @@ inducing) strategy was implemented: end-users can specify any string
(subject to a pre-determined length qualifier, currently 32 bytes) for (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 encodings. It is up to the user to make sure that these strings are
valid on the target system. valid on the target system.
</p>
<p> <p>
<code> <code>
void void
_M_init() _M_init()
</code> </code>
</p>
<p> <p>
Strangely enough, this member function attempts to open conversion Strangely enough, this member function attempts to open conversion
descriptors for a given __enc_traits object. If the conversion descriptors for a given __enc_traits object. If the conversion
descriptors are not valid, the conversion descriptors returned will descriptors are not valid, the conversion descriptors returned will
not be valid and the resulting calls to the codecvt conversion not be valid and the resulting calls to the codecvt conversion
functions will return error. functions will return error.
</p>
<p> <p>
<code> <code>
bool bool
_M_good() _M_good()
</code> </code>
</p>
<p> <p>
Provides a way to see if the given __enc_traits object has been Provides a way to see if the given __enc_traits object has been
properly initialized. If the string literals describing the desired properly initialized. If the string literals describing the desired
@ -356,57 +392,60 @@ fail, and this will return false. If the internal and external
encodings are valid, but iconv_open could not allocate conversion encodings are valid, but iconv_open could not allocate conversion
descriptors, this will also return false. Otherwise, the object is descriptors, this will also return false. Otherwise, the object is
ready to convert and will return true. ready to convert and will return true.
</p>
<p> <p>
<code> <code>
__enc_traits(const __enc_traits&amp;) __enc_traits(const __enc_traits&amp;)
</code> </code>
</p>
<p> <p>
As iconv allocates memory and sets up conversion descriptors, the copy As iconv allocates memory and sets up conversion descriptors, the copy
constructor can only copy the member data pertaining to the internal constructor can only copy the member data pertaining to the internal
and external code conversions, and not the conversion descriptors and external code conversions, and not the conversion descriptors
themselves. themselves.
</p>
<p> <p>
Definitions for all the required codecvt member functions are provided Definitions for all the required codecvt member functions are provided
for this specialization, and usage of codecvt&lt;internal character type, for this specialization, and usage of codecvt&lt;internal character type,
external character type, __enc_traits&gt; is consistent with other external character type, __enc_traits&gt; is consistent with other
codecvt usage. codecvt usage.
</p>
<p>
<h2> <h2>
6. Examples 6. Examples
</h2> </h2>
<ul> <ul>
<li> <li>
a. conversions involving string literals a. conversions involving string literals
<pre> <pre>
typedef codecvt_base::result result; typedef codecvt_base::result result;
typedef unsigned short unicode_t; typedef unsigned short unicode_t;
typedef unicode_t int_type; typedef unicode_t int_type;
typedef char ext_type; typedef char ext_type;
typedef __enc_traits enc_type; typedef __enc_traits enc_type;
typedef codecvt&lt;int_type, ext_type, enc_type&gt; unicode_codecvt; typedef codecvt&lt;int_type, ext_type, enc_type&gt; unicode_codecvt;
const ext_type* e_lit = "black pearl jasmine tea"; const ext_type* e_lit = "black pearl jasmine tea";
int size = strlen(e_lit); int size = strlen(e_lit);
int_type i_lit_base[24] = int_type i_lit_base[24] =
{ 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696, 27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
25856, 24832, 2560 25856, 24832, 2560
}; };
const int_type* i_lit = i_lit_base; const int_type* i_lit = i_lit_base;
const ext_type* efrom_next; const ext_type* efrom_next;
const int_type* ifrom_next; const int_type* ifrom_next;
ext_type* e_arr = new ext_type[size + 1]; ext_type* e_arr = new ext_type[size + 1];
ext_type* eto_next; ext_type* eto_next;
int_type* i_arr = new int_type[size + 1]; int_type* i_arr = new int_type[size + 1];
int_type* ito_next; int_type* ito_next;
// construct a locale object with the specialized facet. // construct a locale object with the specialized facet.
locale loc(locale::classic(), new unicode_codecvt); locale loc(locale::classic(), new unicode_codecvt);
// sanity check the constructed locale has the specialized facet. // sanity check the constructed locale has the specialized facet.
VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) ); VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc); const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
@ -414,70 +453,80 @@ codecvt usage.
unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1"); unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
initialize_state(state01); initialize_state(state01);
result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
i_arr, i_arr + size, ito_next); i_arr, i_arr + size, ito_next);
VERIFY( r1 == codecvt_base::ok ); VERIFY( r1 == codecvt_base::ok );
VERIFY( !int_traits::compare(i_arr, i_lit, size) ); VERIFY( !int_traits::compare(i_arr, i_lit, size) );
VERIFY( efrom_next == e_lit + size ); VERIFY( efrom_next == e_lit + size );
VERIFY( ito_next == i_arr + size ); VERIFY( ito_next == i_arr + size );
</pre> </pre>
<li> </li>
b. conversions involving std::string <li>
<li> b. conversions involving std::string
c. conversions involving std::filebuf and std::ostream </li>
<li>
c. conversions involving std::filebuf and std::ostream
</li>
</ul> </ul>
More information can be found in the following testcases: More information can be found in the following testcases:
<ul> <ul>
<li> testsuite/22_locale/codecvt_char_char.cc <li> testsuite/22_locale/codecvt_char_char.cc </li>
<li> testsuite/22_locale/codecvt_unicode_wchar_t.cc <li> testsuite/22_locale/codecvt_unicode_wchar_t.cc </li>
<li> testsuite/22_locale/codecvt_unicode_char.cc <li> testsuite/22_locale/codecvt_unicode_char.cc </li>
<li> testsuite/22_locale/codecvt_wchar_t_char.cc <li> testsuite/22_locale/codecvt_wchar_t_char.cc </li>
</ul> </ul>
<p>
<h2> <h2>
7. Unresolved Issues 7. Unresolved Issues
</h2> </h2>
<ul> <ul>
<li> <li>
a. things that are sketchy, or remain unimplemented: a. things that are sketchy, or remain unimplemented:
do_encoding, max_length and length member functions do_encoding, max_length and length member functions
are only weakly implemented. I have no idea how to do are only weakly implemented. I have no idea how to do
this correctly, and in a generic manner. Nathan? this correctly, and in a generic manner. Nathan?
</li>
<li> <li>
b. conversions involving std::string b. conversions involving std::string
<ul> <ul>
<li> <li>
how should operators != and == work for string of how should operators != and == work for string of
different/same encoding? different/same encoding?
</li>
<li> <li>
what is equal? A byte by byte comparison or an what is equal? A byte by byte comparison or an
encoding then byte comparison? encoding then byte comparison?
</li>
<li>
conversions between narrow, wide, and unicode strings <li>
</ul> conversions between narrow, wide, and unicode strings
</li>
</ul>
</li>
<li> <li>
c. conversions involving std::filebuf and std::ostream c. conversions involving std::filebuf and std::ostream
<ul> <ul>
<li> <li>
how to initialize the state object in a how to initialize the state object in a
standards-conformant manner? standards-conformant manner?
</li>
<li> <li>
how to synchronize the &quot;C&quot; and &quot;C++&quot; how to synchronize the &quot;C&quot; and &quot;C++&quot;
conversion information? conversion information?
</li>
<li> <li>
wchar_t/char internal buffers and conversions between wchar_t/char internal buffers and conversions between
internal/external buffers? internal/external buffers?
</ul> </li>
</ul>
</li>
</ul> </ul>
<p>
<h2> <h2>
8. Acknowledgments 8. Acknowledgments
</h2> </h2>
@ -485,7 +534,6 @@ Ulrich Drepper for the iconv suggestions and patient answering of
late-night questions, Jason Merrill for the template partial late-night questions, Jason Merrill for the template partial
specialization hints, language clarification, and wchar_t fixes. specialization hints, language clarification, and wchar_t fixes.
<p>
<h2> <h2>
9. Bibliography / Referenced Documents 9. Bibliography / Referenced Documents
</h2> </h2>
@ -494,35 +542,44 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p> <p>
Drepper, Ulrich, Numerous, late-night email correspondence Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p> <p>
Feather, Clive, &quot;A brief description of Normative Addendum 1,&quot; in particular the parts on Extended Character Sets Feather, Clive, &quot;A brief description of Normative Addendum 1,&quot; in particular the parts on Extended Character Sets
http://www.lysator.liu.se/c/na1.html http://www.lysator.liu.se/c/na1.html
</p>
<p> <p>
Haible, Bruno, &quot;The Unicode HOWTO&quot; v0.18, 4 August 2000 Haible, Bruno, &quot;The Unicode HOWTO&quot; v0.18, 4 August 2000
ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html
</p>
<p> <p>
ISO/IEC 14882:1998 Programming languages - C++ ISO/IEC 14882:1998 Programming languages - C++
</p>
<p> <p>
ISO/IEC 9899:1999 Programming languages - C ISO/IEC 9899:1999 Programming languages - C
</p>
<p> <p>
Khun, Markus, &quot;UTF-8 and Unicode FAQ for Unix/Linux&quot; Khun, Markus, &quot;UTF-8 and Unicode FAQ for Unix/Linux&quot;
http://www.cl.cam.ac.uk/~mgk25/unicode.html http://www.cl.cam.ac.uk/~mgk25/unicode.html
</p>
<p> <p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p> <p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p> <p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc. The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html http://www.opennc.org/austin/docreg.html
</p>
</body> </body>
</html> </html>

72
libstdc++-v3/docs/html/22_locale/ctype.html
View file

@ -1,19 +1,20 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
Notes on the ctype implementation. <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
</title> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes on the ctype implementation." />
<title>Notes on the ctype implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
<h1> <h1>
Notes on the ctype implementation. Notes on the ctype implementation.
</h1> </h1>
<I> <em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000 prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
</I> </em>
<p>
<h2> <h2>
1. Abstract 1. Abstract
</h2> </h2>
@ -21,13 +22,11 @@ prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
Woe is me. Woe is me.
</p> </p>
<p>
<h2> <h2>
2. What the standard says 2. What the standard says
</h2> </h2>
<p>
<h2> <h2>
3. Problems with &quot;C&quot; ctype : global locales, termination. 3. Problems with &quot;C&quot; ctype : global locales, termination.
</h2> </h2>
@ -37,8 +36,8 @@ For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
conversions are made between the internal character set (always UCS4 conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements. LC_CTYPE category implements.
</p>
<p>
<h2> <h2>
4. Design 4. Design
</h2> </h2>
@ -48,24 +47,28 @@ The two required specializations are implemented as follows:
<code> <code>
ctype&lt;char&gt; ctype&lt;char&gt;
</code> </code>
</p>
<p> <p>
This is simple specialization. Implementing this was a piece of cake. This is simple specialization. Implementing this was a piece of cake.
</p>
<p> <p>
<code> <code>
ctype&lt;wchar_t&gt; ctype&lt;wchar_t&gt;
</code> </code>
</p>
<p> <p>
This specialization, by specifying all the template parameters, pretty This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char. to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p>
<p> <p>
Neither of these two required specializations deals with Unicode Neither of these two required specializations deals with Unicode
characters. As such, libstdc++-v3 implements characters. As such, libstdc++-v3 implements
</p>
<p>
<h2> <h2>
5. Examples 5. Examples
</h2> </h2>
@ -76,50 +79,47 @@ characters. As such, libstdc++-v3 implements
More information can be found in the following testcases: More information can be found in the following testcases:
<ul> <ul>
<li> testsuite/22_locale/ctype_char_members.cc <li> testsuite/22_locale/ctype_char_members.cc </li>
<li> testsuite/22_locale/ctype_wchar_t_members.cc <li> testsuite/22_locale/ctype_wchar_t_members.cc </li>
</ul> </ul>
<p>
<h2> <h2>
6. Unresolved Issues 6. Unresolved Issues
</h2> </h2>
<ul> <ul>
<li> how to deal with the global locale issue? <li> how to deal with the global locale issue? </li>
<li> how to deal with different types than char, wchar_t? <li> how to deal with different types than char, wchar_t? </li>
<li> codecvt/ctype overlap: narrow/widen <li> codecvt/ctype overlap: narrow/widen </li>
<li> mask typedef in codecvt_base, argument types in codecvt. <li> mask typedef in codecvt_base, argument types in codecvt.
what is know about this type? what is know about this type? </li>
<li> why mask* argument in codecvt? <li> why mask* argument in codecvt? </li>
<li> can this be made (more) generic? is there a simple way to <li> can this be made (more) generic? is there a simple way to
straighten out the configure-time mess that is a by-product of straighten out the configure-time mess that is a by-product of
this class? this class? </li>
<li> get the ctype&lt;wchar_t&gt;::mask stuff under control. Need to <li> get the ctype&lt;wchar_t&gt;::mask stuff under control. Need to
make some kind of static table, and not do lookup evertime make some kind of static table, and not do lookup evertime
somebody hits the do_is... functions. Too bad we can't just somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt; redefine mask for ctype&lt;wchar_t&gt; </li>
<li> rename abstract base class. See if just smash-overriding <li> rename abstract base class. See if just smash-overriding
is a better approach. Clarify, add sanity to naming. is a better approach. Clarify, add sanity to naming. </li>
</ul> </ul>
<p>
<h2> <h2>
7. Acknowledgments 7. Acknowledgments
</h2> </h2>
Ulrich Drepper for patient answering of late-night questions, skeletal Ulrich Drepper for patient answering of late-night questions, skeletal
examples, and C language expertise. examples, and C language expertise.
<p>
<h2> <h2>
8. Bibliography / Referenced Documents 8. Bibliography / Referenced Documents
</h2> </h2>
@ -128,23 +128,29 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p> <p>
Drepper, Ulrich, Numerous, late-night email correspondence Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p> <p>
ISO/IEC 14882:1998 Programming languages - C++ ISO/IEC 14882:1998 Programming languages - C++
</p>
<p> <p>
ISO/IEC 9899:1999 Programming languages - C ISO/IEC 9899:1999 Programming languages - C
</p>
<p> <p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p> <p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p> <p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc. The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html http://www.opennc.org/austin/docreg.html
</p>
</body> </body>
</html> </html>

47
libstdc++-v3/docs/html/22_locale/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 22</title> <title>libstdc++-v3 HOWTO: Chapter 22</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -16,33 +15,33 @@
<p>Chapter 22 deals with the C++ localization facilities. <p>Chapter 22 deals with the C++ localization facilities.
</p> </p>
<!-- I wanted to write that sentence in something requiring an exotic font, <!-- I wanted to write that sentence in something requiring an exotic font,
like Cryllic or Kanji. Probably more work than such cuteness is worth, like Cyrllic or Kanji. Probably more work than such cuteness is worth,
but I still think it'd be funny. but I still think it'd be funny.
--> -->
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">class locale</a> <li><a href="#1">class locale</a></li>
<li><a href="#2">class codecvt</a> <li><a href="#2">class codecvt</a></li>
<li><a href="#3">class ctype</a> <li><a href="#3">class ctype</a></li>
<li><a href="#4">class messages</a> <li><a href="#4">class messages</a></li>
<li><a href="#5">Bjarne Stroustrup on Locales</a> <li><a href="#5">Bjarne Stroustrup on Locales</a></li>
<li><a href="#6">Nathan Myers on Locales</a> <li><a href="#6">Nathan Myers on Locales</a></li>
<li><a href="#7">Correct Transformations</a> <li><a href="#7">Correct Transformations</a></li>
</ul> </ul>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h2><a name="1">class locale</a></h2> <h2><a name="1">class locale</a></h2>
<p>Notes made during the implementation of locales can be found <p>Notes made during the implementation of locales can be found
<a href="locale.html">here</a>. <a href="locale.html">here</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">class codecvt</a></h2> <h2><a name="2">class codecvt</a></h2>
<p>Notes made during the implementation of codecvt can be found <p>Notes made during the implementation of codecvt can be found
<a href="codecvt.html">here</a>. <a href="codecvt.html">here</a>.
@ -66,19 +65,19 @@
implementation-provided extended functionality are given. implementation-provided extended functionality are given.
</blockquote> </blockquote>
<hr> <hr />
<h2><a name="3">class ctype</a></h2> <h2><a name="3">class ctype</a></h2>
<p>Notes made during the implementation of ctype can be found <p>Notes made during the implementation of ctype can be found
<a href="ctype.html">here</a>. <a href="ctype.html">here</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">class messages</a></h2> <h2><a name="4">class messages</a></h2>
<p>Notes made during the implementation of messages can be found <p>Notes made during the implementation of messages can be found
<a href="messages.html">here</a>. <a href="messages.html">here</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">Stroustrup on Locales</a></h2> <h2><a name="5">Stroustrup on Locales</a></h2>
<p>Dr. Bjarne Stroustrup has released a <p>Dr. Bjarne Stroustrup has released a
<a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a> <a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a>
@ -96,14 +95,14 @@
avoid it. avoid it.
</em></blockquote> </em></blockquote>
<hr> <hr />
<h2><a name="6">Nathan Myers on Locales</a></h2> <h2><a name="6">Nathan Myers on Locales</a></h2>
<p>An article entitled &quot;The Standard C++ Locale&quot; was <p>An article entitled &quot;The Standard C++ Locale&quot; was
published in Dr. Dobb's Journal and can be found published in Dr. Dobb's Journal and can be found
<a href="http://www.cantrip.org/locale.html">here</a>. <a href="http://www.cantrip.org/locale.html">here</a>.
</p> </p>
<hr> <hr />
<h2><a name="7">Correct Transformations</a></h2> <h2><a name="7">Correct Transformations</a></h2>
<!-- Jumping directly to here from chapter 21. --> <!-- Jumping directly to here from chapter 21. -->
<p>A very common question on newsgroups and mailing lists is, &quot;How <p>A very common question on newsgroups and mailing lists is, &quot;How
@ -207,7 +206,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

70
libstdc++-v3/docs/html/22_locale/locale.html
View file

@ -1,19 +1,20 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
Notes on the locale implementation. <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
</title> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes on the locale implementation." />
<title>Notes on the locale implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
<h1> <h1>
Notes on the locale implementation. Notes on the locale implementation.
</h1> </h1>
<I> <em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I> </em>
<p>
<h2> <h2>
1. Abstract Describes the basic locale object, including nested 1. Abstract Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object, classes id, facet, and the reference-counted implementation object,
@ -22,14 +23,12 @@ class _Impl.
<p> <p>
</p> </p>
<p>
<h2> <h2>
2. What the standard says 2. What the standard says
See Chapter 22 of the standard.
</h2> </h2>
See Chapter 22 of the standard.
<p>
<h2> <h2>
3. Problems with &quot;C&quot; locales : global locales, termination. 3. Problems with &quot;C&quot; locales : global locales, termination.
</h2> </h2>
@ -40,7 +39,7 @@ design ontop of POSIX and other relevant stanards, which include the
Single Unix (nee X/Open.) Single Unix (nee X/Open.)
Because POSIX falls down so completely, portibility is an issue. Because POSIX falls down so completely, portibility is an issue.
<p> </p>
<h2> <h2>
4. Design 4. Design
@ -74,7 +73,6 @@ Provides an index for looking up specific facets.
class _Impl class _Impl
<p>
<h2> <h2>
5. Examples 5. Examples
</h2> </h2>
@ -85,43 +83,40 @@ class _Impl
More information can be found in the following testcases: More information can be found in the following testcases:
<ul> <ul>
<li> testsuite/22_locale/ctype_char_members.cc <li> testsuite/22_locale/ctype_char_members.cc </li>
<li> testsuite/22_locale/ctype_wchar_t_members.cc <li> testsuite/22_locale/ctype_wchar_t_members.cc </li>
</ul> </ul>
<p>
<h2> <h2>
6. Unresolved Issues 6. Unresolved Issues
</h2> </h2>
<ul> <ul>
<li> locale -a displays available locales on linux <li> locale -a displays available locales on linux </li>
<li> locale initialization: at what point does _S_classic, <li> locale initialization: at what point does _S_classic,
_S_global get initialized? Can named locales assume this _S_global get initialized? Can named locales assume this
initialization has already taken place? initialization has already taken place? </li>
<li> document how named locales error check when filling data <li> document how named locales error check when filling data
members. Ie, a fr_FR locale that doesn't have members. Ie, a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention? string? What's the convention? </li>
<li> explain how locale aliasing happens. When does "de_DE" <li> explain how locale aliasing happens. When does "de_DE"
use "de" information? What is the rule for locales composed of use "de" information? What is the rule for locales composed of
just an ISO language code (say, "de") and locales with both an just an ISO language code (say, "de") and locales with both an
ISO language code and ISO country code (say, "de_DE"). ISO language code and ISO country code (say, "de_DE"). </li>
<li> what should non-required facet instantiations do? If the <li> what should non-required facet instantiations do? If the
generic implemenation is provided, then how to end-users generic implemenation is provided, then how to end-users
provide specializations? provide specializations? </li>
</ul> </ul>
<p>
<h2> <h2>
7. Acknowledgments 7. Acknowledgments
</h2> </h2>
<p>
<h2> <h2>
8. Bibliography / Referenced Documents 8. Bibliography / Referenced Documents
</h2> </h2>
@ -130,20 +125,31 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p> <p>
Drepper, Ulrich, Numerous, late-night email correspondence Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p> <p>
ISO/IEC 14882:1998 Programming languages - C++ ISO/IEC 14882:1998 Programming languages - C++
</p>
<p> <p>
ISO/IEC 9899:1999 Programming languages - C ISO/IEC 9899:1999 Programming languages - C
</p>
<p> <p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p> <p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p> <p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc. The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html http://www.opennc.org/austin/docreg.html
</p>
</body>
</html>

343
libstdc++-v3/docs/html/22_locale/messages.html
View file

@ -1,19 +1,20 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
Notes on the messages implementation. <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
</title> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes on the messages implementation." />
<title>Notes on the messages implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
<h1> <h1>
Notes on the messages implementation. Notes on the messages implementation.
</h1> </h1>
<I> <em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I> </em>
<p>
<h2> <h2>
1. Abstract 1. Abstract
</h2> </h2>
@ -23,7 +24,6 @@ equivalent to Java's java.text.MessageFormat .using either GNU gettext
or IEEE 1003.1-200 functions. or IEEE 1003.1-200 functions.
</p> </p>
<p>
<h2> <h2>
2. What the standard says 2. What the standard says
</h2> </h2>
@ -34,9 +34,9 @@ locale to the other. For instance, converting the "C" locale's
<code>const char* c = "please"</code> to a German-localized <code>"bitte"</code> <code>const char* c = "please"</code> to a German-localized <code>"bitte"</code>
during program execution. during program execution.
<BLOCKQUOTE> <blockquote>
22.2.7.1 - Template class messages [lib.locale.messages] 22.2.7.1 - Template class messages [lib.locale.messages]
</BLOCKQUOTE> </blockquote>
This class has three public member functions, which directly This class has three public member functions, which directly
correspond to three protected virtual member functions. correspond to three protected virtual member functions.
@ -45,51 +45,57 @@ The public member functions are:
<p> <p>
<code>catalog open(const string&amp;, const locale&amp;) const</code> <code>catalog open(const string&amp;, const locale&amp;) const</code>
</p>
<p> <p>
<code>string_type get(catalog, int, int, const string_type&amp;) const</code> <code>string_type get(catalog, int, int, const string_type&amp;) const</code>
</p>
<p> <p>
<code>void close(catalog) const</code> <code>void close(catalog) const</code>
</p>
<p> <p>
While the virtual functions are: While the virtual functions are:
</p>
<p> <p>
<code>catalog do_open(const string&amp;, const locale&amp;) const</code> <code>catalog do_open(const string&amp;, const locale&amp;) const</code>
<BLOCKQUOTE> </p>
<I> <blockquote>
<em>
-1- Returns: A value that may be passed to get() to retrieve a -1- Returns: A value that may be passed to get() to retrieve a
message, from the message catalog identified by the string name message, from the message catalog identified by the string name
according to an implementation-defined mapping. The result can be used 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 until it is passed to close(). Returns a value less than 0 if no such
catalog can be opened. catalog can be opened.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p> <p>
<code>string_type do_get(catalog, int, int, const string_type&amp;) const</code> <code>string_type do_get(catalog, int, int, const string_type&amp;) const</code>
<BLOCKQUOTE> </p>
<I> <blockquote>
<em>
-3- Requires: A catalog cat obtained from open() and not yet closed. -3- Requires: A catalog cat obtained from open() and not yet closed.
-4- Returns: A message identified by arguments set, msgid, and dfault, -4- Returns: A message identified by arguments set, msgid, and dfault,
according to an implementation-defined mapping. If no such message can according to an implementation-defined mapping. If no such message can
be found, returns dfault. be found, returns dfault.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p> <p>
<code>void do_close(catalog) const</code> <code>void do_close(catalog) const</code>
<BLOCKQUOTE> </p>
<I> <blockquote>
<em>
-5- Requires: A catalog cat obtained from open() and not yet closed. -5- Requires: A catalog cat obtained from open() and not yet closed.
-6- Effects: Releases unspecified resources associated with cat. -6- Effects: Releases unspecified resources associated with cat.
-7- Notes: The limit on such resources, if any, is implementation-defined. -7- Notes: The limit on such resources, if any, is implementation-defined.
</I> </em>
</BLOCKQUOTE> </blockquote>
<p>
<h2> <h2>
3. Problems with &quot;C&quot; messages: thread safety, 3. Problems with &quot;C&quot; messages: thread safety,
over-specification, and assumptions. over-specification, and assumptions.
@ -101,12 +107,14 @@ First, why is <code>messages_base::catalog</code> specified as a typedef
to int? This makes sense for implementations that use to int? This makes sense for implementations that use
<code>catopen</code>, but not for others. Fortunately, it's not heavily <code>catopen</code>, but not for others. Fortunately, it's not heavily
used and so only a minor irritant. used and so only a minor irritant.
</p>
<p> <p>
Second, by making the member functions <code>const</code>, it is Second, by making the member functions <code>const</code>, it is
impossible to save state in them. Thus, storing away information used impossible to save state in them. Thus, storing away information used
in the 'open' member function for use in 'get' is impossible. This is in the 'open' member function for use in 'get' is impossible. This is
unfortunate. unfortunate.
</p>
<p> <p>
The 'open' member function in particular seems to be oddly The 'open' member function in particular seems to be oddly
@ -118,20 +126,22 @@ argument useful? What was the intent? It might make sense if a locale
argument was associated with a given default message string in the argument was associated with a given default message string in the
'open' member function, for instance. Quite murky and unclear, on 'open' member function, for instance. Quite murky and unclear, on
reflection. reflection.
</p>
<p> <p>
Lastly, it seems odd that messages, which explicitly require code Lastly, it seems odd that messages, which explicitly require code
conversion, don't use the codecvt facet. Because the messages facet conversion, don't use the codecvt facet. Because the messages facet
has only one template parameter, it is assumed that ctype, and not has only one template parameter, it is assumed that ctype, and not
codecvt, is to be used to convert between character sets. codecvt, is to be used to convert between character sets.
</p>
<p> <p>
It is implicitly assumed that the locale for the default message 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 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 to be written in English, so translations are always from "en_US" to
other, explicitly named locales. other, explicitly named locales.
</p>
<p>
<h2> <h2>
4. Design and Implementation Details 4. Design and Implementation Details
</h2> </h2>
@ -145,35 +155,39 @@ dependent on the capabilities of the underlying operating system.
<p> <p>
Three different mechanisms have been provided, selectable via Three different mechanisms have been provided, selectable via
configure flags: configure flags:
</p>
<ul> <ul>
<li> generic <li> generic
<p> <p>
This model does very little, and is what is used by default. This model does very little, and is what is used by default.
</p> </p>
</li>
<li> gnu <li> gnu
<p> <p>
The gnu model is complete and fully tested. It's based on the 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 GNU gettext package, which is part of glibc. It uses the functions
<code>textdomain, bindtextdomain, gettext</code> <code>textdomain, bindtextdomain, gettext</code>
to implement full functionality. Creating message to implement full functionality. Creating message
catalogs is a relatively straight-forward process and is catalogs is a relatively straight-forward process and is
lightly documented below, and fully documented in gettext's lightly documented below, and fully documented in gettext's
distributed documentation. distributed documentation.
</p> </p>
</li>
<li> ieee_1003.1-200x <li> ieee_1003.1-200x
<p> <p>
This is a complete, though untested, implementation based on This is a complete, though untested, implementation based on
the IEEE standard. The functions the IEEE standard. The functions
<code>catopen, catgets, catclose</code> <code>catopen, catgets, catclose</code>
are used to retrieve locale-specific messages given the are used to retrieve locale-specific messages given the
appropriate message catalogs that have been constructed for appropriate message catalogs that have been constructed for
their use. Note, the script <code> po2msg.sed</code> that is part their use. Note, the script <code> po2msg.sed</code> that is part
of the gettext distribution can convert gettext catalogs into of the gettext distribution can convert gettext catalogs into
catalogs that <code>catopen</code> can use. catalogs that <code>catopen</code> can use.
</p> </p>
</li>
</ul> </ul>
<p> <p>
@ -181,9 +195,11 @@ A new, standards-conformant non-virtual member function signature was
added for 'open' so that a directory could be specified with a given added for 'open' so that a directory could be specified with a given
message catalog. This simplifies calling conventions for the gnu message catalog. This simplifies calling conventions for the gnu
model. model.
</p>
<p> <p>
The rest of this document discusses details of the GNU model. The rest of this document discusses details of the GNU model.
</p>
<p> <p>
The messages facet, because it is retrieving and converting between The messages facet, because it is retrieving and converting between
@ -193,67 +209,79 @@ necessary for more than just the <code>LC_MESSAGES</code> mask:
<code>LC_CTYPE</code> is also necessary. To avoid any unpleasantness, all <code>LC_CTYPE</code> is also necessary. To avoid any unpleasantness, all
bits of the "C" mask (ie <code>LC_ALL</code>) are set before retrieving bits of the "C" mask (ie <code>LC_ALL</code>) are set before retrieving
messages. messages.
</p>
<p> <p>
Making the message catalogs can be initially tricky, but become quite Making the message catalogs can be initially tricky, but become quite
simple with practice. For complete info, see the gettext simple with practice. For complete info, see the gettext
documentation. Here's an idea of what is required: documentation. Here's an idea of what is required:
</p>
<ul> <ul>
<LI > Make a source file with the required string literals <li> Make a source file with the required string literals
that need to be translated. See that need to be translated. See
<code>intl/string_literals.cc</code> for an example. <code>intl/string_literals.cc</code> for an example.
</li>
<p> <li> Make initial catalog (see "4 Making the PO Template File"
<li> Make initial catalog (see "4 Making the PO Template File" from the gettext docs).
from the gettext docs). <p>
<p> <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
<code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> </p>
</li>
<p>
<li> Make language and country-specific locale catalogs. <li> Make language and country-specific locale catalogs.
<p> <p>
<code>cp libstdc++.pot fr_FR.po</code> <code>cp libstdc++.pot fr_FR.po</code>
<p> </p>
<code>cp libstdc++.pot de_DE.po</code> <p>
<code>cp libstdc++.pot de_DE.po</code>
</p>
</li>
<p> <li> Edit localized catalogs in emacs so that strings are
<li> Edit localized catalogs in emacs so that strings are translated.
translated. <p>
<p> <code>emacs fr_FR.po</code>
<code>emacs fr_FR.po</code> </p>
</li>
<p>
<li> Make the binary mo files. <li> Make the binary mo files.
<p> <p>
<code>msgfmt fr_FR.po -o fr_FR.mo</code> <code>msgfmt fr_FR.po -o fr_FR.mo</code>
<p> </p>
<code>msgfmt de_DE.po -o de_DE.mo</code> <p>
<code>msgfmt de_DE.po -o de_DE.mo</code>
</p>
</li>
<p> <li> Copy the binary files into the correct directory structure.
<li> Copy the binary files into the correct directory structure. <p>
<p> <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code>
<code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code> </p>
<p> <p>
<code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code> <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code>
</p>
</li>
<p> <li> Use the new message catalogs.
<li> Use the new message catalogs. <p>
<p> <code>locale loc_de("de_DE");</code>
<code>locale loc_de("de_DE");</code> </p>
<p> <p>
<code> <code>
use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir); use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
</code> </code>
</p>
</li>
</ul> </ul>
<p>
<h2> <h2>
5. Examples 5. Examples
</h2> </h2>
<ul> <ul>
<li> message converting, simple example using the GNU model. <li> message converting, simple example using the GNU model.
<pre> <pre>
#include &lt;iostream&gt; #include &lt;iostream&gt;
@ -276,82 +304,87 @@ void test01()
mssg_de.close(cat_de); mssg_de.close(cat_de);
} }
</pre> </pre>
</li>
</ul> </ul>
More information can be found in the following testcases: More information can be found in the following testcases:
<ul> <ul>
<li> testsuite/22_locale/messages.cc <li> testsuite/22_locale/messages.cc </li>
<li> testsuite/22_locale/messages_byname.cc <li> testsuite/22_locale/messages_byname.cc </li>
<li> testsuite/22_locale/messages_char_members.cc <li> testsuite/22_locale/messages_char_members.cc </li>
</ul> </ul>
<p>
<h2> <h2>
6. Unresolved Issues 6. Unresolved Issues
</h2> </h2>
<ul> <ul>
<li> Things that are sketchy, or remain unimplemented: <li> Things that are sketchy, or remain unimplemented:
<ul> <ul>
<li>_M_convert_from_char, _M_convert_to_char are in <li>_M_convert_from_char, _M_convert_to_char are in
flux, depending on how the library ends up doing flux, depending on how the library ends up doing
character set conversions. It might not be possible to character set conversions. It might not be possible to
do a real character set based conversion, due to the do a real character set based conversion, due to the
fact that the template parameter for messages is not fact that the template parameter for messages is not
enough to instantiate the codecvt facet (1 supplied, enough to instantiate the codecvt facet (1 supplied,
need at least 2 but would prefer 3). need at least 2 but would prefer 3).
</li>
<li> There are issues with gettext needing the global <li> There are issues with gettext needing the global
locale set to extract a message. This dependence on locale set to extract a message. This dependence on
the global locale makes the current "gnu" model non the global locale makes the current "gnu" model non
MT-safe. Future versions of glibc, ie glibc 2.3.x will MT-safe. Future versions of glibc, ie glibc 2.3.x will
fix this, and the C++ library bits are already in fix this, and the C++ library bits are already in
place. place.
</ul> </li>
</ul>
<p> </li>
<li> Development versions of the GNU "C" library, glibc 2.3 will allow
a more efficient, MT implementation of std::messages, and will <li> Development versions of the GNU "C" library, glibc 2.3 will allow
allow the removal of the _M_name_messages data member. If this a more efficient, MT implementation of std::messages, and will
is done, it will change the library ABI. The C++ parts to allow the removal of the _M_name_messages data member. If this
support glibc 2.3 have already been coded, but are not in use: is done, it will change the library ABI. The C++ parts to
once this version of the "C" library is released, the marked support glibc 2.3 have already been coded, but are not in use:
parts of the messages implementation can be switched over to once this version of the "C" library is released, the marked
the new "C" library functionality. parts of the messages implementation can be switched over to
<p> the new "C" library functionality.
</li>
<li> At some point in the near future, std::numpunct will probably use <li> At some point in the near future, std::numpunct will probably use
std::messages facilities to implement truename/falename std::messages facilities to implement truename/falename
correctly. This is currently not done, but entries in correctly. This is currently not done, but entries in
libstdc++.pot have already been made for "true" and "false" libstdc++.pot have already been made for "true" and "false"
string literals, so all that remains is the std::numpunct string literals, so all that remains is the std::numpunct
coding and the configure/make hassles to make the installed coding and the configure/make hassles to make the installed
library search its own catalog. Currently the libstdc++.mo library search its own catalog. Currently the libstdc++.mo
catalog is only searched for the testsuite cases involving catalog is only searched for the testsuite cases involving
messages members. messages members.
</li>
<p> <li> The following member functions:
<li> The following member functions:
<p> <p>
<code> <code>
catalog catalog
open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
</code> </code>
</p>
<p> <p>
<code> <code>
catalog catalog
open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const; open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
</code> </code>
</p>
<p> <p>
Don't actually return a "value less than 0 if no such catalog Don't actually return a "value less than 0 if no such catalog
can be opened" as required by the standard in the "gnu" can be opened" as required by the standard in the "gnu"
model. As of this writing, it is unknown how to query to see model. As of this writing, it is unknown how to query to see
if a specified message catalog exists using the gettext if a specified message catalog exists using the gettext
package. package.
</p>
</li>
</ul> </ul>
<p>
<h2> <h2>
7. Acknowledgments 7. Acknowledgments
</h2> </h2>
@ -359,7 +392,6 @@ Ulrich Drepper for the character set explanations, gettext details,
and patient answering of late-night questions, Tom Tromey for the java details. and patient answering of late-night questions, Tom Tromey for the java details.
<p>
<h2> <h2>
8. Bibliography / Referenced Documents 8. Bibliography / Referenced Documents
</h2> </h2>
@ -371,36 +403,49 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters
Drepper, Ulrich, Thread-Aware Locale Model, A proposal. This is a Drepper, Ulrich, Thread-Aware Locale Model, A proposal. This is a
draft document describing the design of glibc 2.3 MT locale draft document describing the design of glibc 2.3 MT locale
functionality. functionality.
</p>
<p> <p>
Drepper, Ulrich, Numerous, late-night email correspondence Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p> <p>
ISO/IEC 9899:1999 Programming languages - C ISO/IEC 9899:1999 Programming languages - C
</p>
<p> <p>
ISO/IEC 14882:1998 Programming languages - C++ ISO/IEC 14882:1998 Programming languages - C++
</p>
<p> <p>
Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In
particular, java.util.Properties, java.text.MessageFormat, particular, java.util.Properties, java.text.MessageFormat,
java.util.Locale, java.util.ResourceBundle. java.util.Locale, java.util.ResourceBundle.
http://java.sun.com/j2se/1.3/docs/api http://java.sun.com/j2se/1.3/docs/api
</p>
<p> <p>
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x) System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc. The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
In particular see lines 5268-5427. In particular see lines 5268-5427.
http://www.opennc.org/austin/docreg.html http://www.opennc.org/austin/docreg.html
</p>
<p> GNU gettext tools, version 0.10.38, Native Language Support <p> GNU gettext tools, version 0.10.38, Native Language Support
Library and Tools. Library and Tools.
http://sources.redhat.com/gettext http://sources.redhat.com/gettext
</p>
<p> <p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales,
Advanced Programmer's Guide and Reference, Addison Wesley Longman, Advanced Programmer's Guide and Reference, Addison Wesley Longman,
Inc. 2000. See page 725, Internationalized Messages. Inc. 2000. See page 725, Internationalized Messages.
</p>
<p> <p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
</body>
</html>

107
libstdc++-v3/docs/html/23_containers/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 23</title> <title>libstdc++-v3 HOWTO: Chapter 23</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -18,19 +17,19 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Making code unaware of the container/array difference</a> <li><a href="#1">Making code unaware of the container/array difference</a></li>
<li><a href="#2">Variable-sized bitmasks</a> <li><a href="#2">Variable-sized bitmasks</a></li>
<li><a href="#3">Containers and multithreading</a> <li><a href="#3">Containers and multithreading</a></li>
<li><a href="#4">&quot;Hinting&quot; during insertion</a> <li><a href="#4">&quot;Hinting&quot; during insertion</a></li>
<li><a href="#5">Bitmasks and string arguments</a> <li><a href="#5">Bitmasks and string arguments</a></li>
<li><a href="#6"><code>std::list::size()</code> is O(n)!</a> <li><a href="#6"><code>std::list::size()</code> is O(n)!</a></li>
<li><a href="#7">Space overhead management for vectors</a> <li><a href="#7">Space overhead management for vectors</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -65,9 +64,10 @@
code size or execution time. code size or execution time.
</p> </p>
<p>The result is that if all your algorithm calls look like <p>The result is that if all your algorithm calls look like
<pre> </p>
<pre>
std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);</pre> std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);</pre>
then the type of foo can change from an array of ints to a vector <p>then the type of foo can change from an array of ints to a vector
of ints to a deque of ints and back again, without ever changing any of ints to a deque of ints and back again, without ever changing any
client code. client code.
</p> </p>
@ -86,19 +86,21 @@
give the extra three lines and avoid confusion. give the extra three lines and avoid confusion.
</p> </p>
<p>Second, the line <p>Second, the line
<pre> </p>
<pre>
inline unsigned int lengthof (T (&amp;)[sz]) { return sz; } </pre> inline unsigned int lengthof (T (&amp;)[sz]) { return sz; } </pre>
looks just weird! Hint: unused parameters can be left nameless. <p>looks just weird! Hint: unused parameters can be left nameless.
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Variable-sized bitmasks</a></h2> <h2><a name="2">Variable-sized bitmasks</a></h2>
<p>No, you cannot write code of the form <p>No, you cannot write code of the form
</p>
<!-- Careful, the leading spaces in PRE show up directly. --> <!-- Careful, the leading spaces in PRE show up directly. -->
<pre> <pre>
#include &lt;bitset&gt; #include &lt;bitset&gt;
void foo (size_t n) void foo (size_t n)
@ -106,19 +108,19 @@
std::bitset&lt;n&gt; bits; std::bitset&lt;n&gt; bits;
.... ....
} </pre> } </pre>
because <code>n</code> must be known at compile time. Your compiler is <p>because <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 correct; it is not a bug. That's the way templates work. (Yes, it
<em>is</em> a feature.) <em>is</em> a feature.)
</p> </p>
<p>There are a couple of ways to handle this kind of thing. Please <p>There are a couple of ways to handle this kind of thing. Please
consider all of them before passing judgement. They include, in consider all of them before passing judgement. They include, in
no particular order: no particular order:
<ul>
<li>A very large N in <code>bitset&lt;N&gt;</code>.
<li>A container&lt;bool&gt;.
<li>Extremely weird solutions.
</ul>
</p> </p>
<ul>
<li>A very large N in <code>bitset&lt;N&gt;</code>.</li>
<li>A container&lt;bool&gt;.</li>
<li>Extremely weird solutions.</li>
</ul>
<p><strong>A very large N in <p><strong>A very large N in
<code>bitset&lt;N&gt;</code>.&nbsp;&nbsp;</strong> It has <code>bitset&lt;N&gt;</code>.&nbsp;&nbsp;</strong> It has
been pointed out a few times in newsgroups that N bits only takes up been pointed out a few times in newsgroups that N bits only takes up
@ -192,7 +194,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Containers and multithreading</a></h2> <h2><a name="3">Containers and multithreading</a></h2>
<p>This section discusses issues surrounding the design of <p>This section discusses issues surrounding the design of
multithreaded applications which use Standard C++ containers. multithreaded applications which use Standard C++ containers.
@ -204,14 +206,14 @@
multithreading as it relates to libstdc++, including details on multithreading as it relates to libstdc++, including details on
the proper compilation of threaded code (and compatibility between the proper compilation of threaded code (and compatibility between
threaded and non-threaded code), see Chapter 17. threaded and non-threaded code), see Chapter 17.
</p> </p>
<p>Two excellent pages to read when working with the Standard C++ <p>Two excellent pages to read when working with the Standard C++
containers and threads are containers and threads are
<a href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's <a href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
http://www.sgi.com/tech/stl/thread_safety.html</a> and http://www.sgi.com/tech/stl/thread_safety.html</a> and
<a href="http://www.sgi.com/tech/stl/Allocators.html">SGI's <a href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
http://www.sgi.com/tech/stl/Allocators.html</a>. http://www.sgi.com/tech/stl/Allocators.html</a>.
</p> </p>
<p><em>However, please ignore all discussions about the user-level <p><em>However, please ignore all discussions about the user-level
configuration of the lock implementation inside the STL configuration of the lock implementation inside the STL
container-memory allocator on those pages. For the sake of this container-memory allocator on those pages. For the sake of this
@ -223,7 +225,7 @@
STL. This is no longer required for any port and should no STL. This is no longer required for any port and should no
longer be done unless you really know what you are doing and longer be done unless you really know what you are doing and
assume all responsibility.</em> assume all responsibility.</em>
</p> </p>
<p>Since the container implementation of libstdc++-v3 uses the SGI <p>Since the container implementation of libstdc++-v3 uses the SGI
code, we use the same definition of thread safety as SGI when code, we use the same definition of thread safety as SGI when
discussing design. A key point that beginners may miss is the discussing design. A key point that beginners may miss is the
@ -235,7 +237,7 @@
element is constructed uses an internal lock obtained and element is constructed uses an internal lock obtained and
released solely within libstdc++-v3 code (in fact, this is the released solely within libstdc++-v3 code (in fact, this is the
reason STL requires any knowledge of the thread configuration). reason STL requires any knowledge of the thread configuration).
</p> </p>
<p>For implementing a container which does its own locking, it is <p>For implementing a container which does its own locking, it is
trivial to provide a wrapper class which obtains the lock (as trivial to provide a wrapper class which obtains the lock (as
SGI suggests), performs the container operation, and then SGI suggests), performs the container operation, and then
@ -249,7 +251,8 @@
you must change this on a global basis for your platform to better you must change this on a global basis for your platform to better
support multi-threading, then please consult all commentary in support multi-threading, then please consult all commentary in
include/bits/stl_alloc.h and the allocators link below. include/bits/stl_alloc.h and the allocators link below.
<blockquote> </p>
<blockquote>
<p>(Explicit warning since so many people get confused while <p>(Explicit warning since so many people get confused while
attempting this:) attempting this:)
</p> </p>
@ -271,8 +274,8 @@
one-definition rule of C/C++ and you might cause yourself untold one-definition rule of C/C++ and you might cause yourself untold
problems. problems.
</p> </p>
</blockquote> </blockquote>
If you find any platform where gcc reports a <p>If you find any platform where gcc reports a
threading model other than single, and where libstdc++-v3 builds threading model other than single, and where libstdc++-v3 builds
a buggy container allocator when used with threads unless you a buggy container allocator when used with threads unless you
define __USE_MALLOC, we want to hear about it ASAP. In the define __USE_MALLOC, we want to hear about it ASAP. In the
@ -290,13 +293,14 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">&quot;Hinting&quot; during insertion</a></h2> <h2><a name="4">&quot;Hinting&quot; during insertion</a></h2>
<p>Section [23.1.2], Table 69, of the C++ standard lists this function <p>Section [23.1.2], Table 69, of the C++ standard lists this function
for all of the associative containers (map, set, etc): for all of the associative containers (map, set, etc):
<pre> </p>
<pre>
a.insert(p,t);</pre> a.insert(p,t);</pre>
where 'p' is an iterator into the container 'a', and 't' is the item <p>where 'p' is an iterator into the container 'a', and 't' is the item
to insert. The standard says that &quot;iterator p is a hint to insert. The standard says that &quot;iterator p is a hint
pointing to where the insert should start to search,&quot; but pointing to where the insert should start to search,&quot; but
specifies nothing more. (LWG Issue #233, currently in review, specifies nothing more. (LWG Issue #233, currently in review,
@ -321,23 +325,26 @@
their new meanings in the next paragraph. *grin* their new meanings in the next paragraph. *grin*
</p> </p>
<p>If the <code>hint</code> parameter ('p' above) is equivalent to: <p>If the <code>hint</code> parameter ('p' above) is equivalent to:
</p>
<ul> <ul>
<li><code>begin()</code>, then the item being inserted should have a key <li><code>begin()</code>, then the item being inserted should have a key
less than all the other keys in the container. The item will less than all the other keys in the container. The item will
be inserted at the beginning of the container, becoming the new be inserted at the beginning of the container, becoming the new
entry at <code>begin()</code>. entry at <code>begin()</code>.
</li>
<li><code>end()</code>, then the item being inserted should have a key <li><code>end()</code>, then the item being inserted should have a key
greater than all the other keys in the container. The item will greater than all the other keys in the container. The item will
be inserted at the end of the container, becoming the new entry be inserted at the end of the container, becoming the new entry
at <code>end()</code>. at <code>end()</code>.
</li>
<li>neither <code>begin()</code> nor <code>end()</code>, then: Let <code>h</code> <li>neither <code>begin()</code> nor <code>end()</code>, then: Let <code>h</code>
be the entry in the container pointed to by <code>hint</code>, that be the entry in the container pointed to by <code>hint</code>, that
is, <code>h = *hint</code>. Then the item being inserted should have is, <code>h = *hint</code>. Then the item being inserted should have
a key less than that of <code>h</code>, and greater than that of the a key less than that of <code>h</code>, and greater than that of the
item preceding <code>h</code>. The new item will be inserted item preceding <code>h</code>. The new item will be inserted
between <code>h</code> and <code>h</code>'s predecessor. between <code>h</code> and <code>h</code>'s predecessor.
</li>
</ul> </ul>
</p>
<p>For <code>multimap</code> and <code>multiset</code>, the restrictions are <p>For <code>multimap</code> and <code>multiset</code>, the restrictions are
slightly looser: &quot;greater than&quot; should be replaced by slightly looser: &quot;greater than&quot; should be replaced by
&quot;not less than&quot; and &quot;less than&quot; should be replaced &quot;not less than&quot; and &quot;less than&quot; should be replaced
@ -372,7 +379,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">Bitmasks and string arguments</a></h2> <h2><a name="5">Bitmasks and string arguments</a></h2>
<p>Bitmasks do not take char* nor const char* arguments in their <p>Bitmasks do not take char* nor const char* arguments in their
constructors. This is something of an accident, but you can read constructors. This is something of an accident, but you can read
@ -383,6 +390,7 @@
</p> </p>
<p>For now you can simply make a temporary string object using the <p>For now you can simply make a temporary string object using the
constructor expression: constructor expression:
</p>
<pre> <pre>
std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) ); std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) );
</pre> </pre>
@ -390,17 +398,17 @@
<pre> <pre>
std::bitset&lt;5&gt; b ( &quot;10110&quot; ); // invalid std::bitset&lt;5&gt; b ( &quot;10110&quot; ); // invalid
</pre> </pre>
</p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="6"><code>std::list::size()</code> is O(n)!</a></h2> <h2><a name="6"><code>std::list::size()</code> is O(n)!</a></h2>
<p>Yes it is, and that's okay. This is a decision that we preserved when <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 we imported SGI's STL implementation. The following is quoted from
<a href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</a>: <a href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</a>:
<blockquote> </p>
<blockquote>
<p>The size() member function, for list and slist, takes time <p>The size() member function, for list and slist, takes time
proportional to the number of elements in the list. This was a proportional to the number of elements in the list. This was a
deliberate tradeoff. The only way to get a constant-time size() for deliberate tradeoff. The only way to get a constant-time size() for
@ -419,6 +427,7 @@
is supposed to do something unless there is a good reason not to. is supposed to do something unless there is a good reason not to.
</p> </p>
<p>One implication of linear time size(): you should never write <p>One implication of linear time size(): you should never write
</p>
<pre> <pre>
if (L.size() == 0) if (L.size() == 0)
...</pre> ...</pre>
@ -426,15 +435,13 @@
<pre> <pre>
if (L.empty()) if (L.empty())
...</pre> ...</pre>
</p> </blockquote>
</blockquote>
</p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="7">Space overhead management for vectors</h2> <h2><a name="7">Space overhead management for vectors</a></h2>
<p>In <p>In
<a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this <a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this
message to the list</a>, Daniel Kostecky announced work on an message to the list</a>, Daniel Kostecky announced work on an
@ -457,7 +464,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

70
libstdc++-v3/docs/html/24_iterators/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 24</title> <title>libstdc++-v3 HOWTO: Chapter 24</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -19,14 +18,14 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">They ain't pointers!</a> <li><a href="#1">They ain't pointers!</a></li>
<li><a href="#2">It ends <em>where?</em></a> <li><a href="#2">It ends <em>where?</em></a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -67,41 +66,46 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">It ends <em>where?</em></a></h2> <h2><a name="2">It ends <em>where?</em></a></h2>
<p>This starts off sounding complicated, but is actually very easy, <p>This starts off sounding complicated, but is actually very easy,
especially towards the end. Trust me. especially towards the end. Trust me.
</p> </p>
<p>Beginners usually have a little trouble understand the whole <p>Beginners usually have a little trouble understand the whole
'past-the-end' thing, until they remember their early algebra classes 'past-the-end' thing, until they remember their early algebra classes
(see, they </em>told</em> you that stuff would come in handy!) and (see, they <em>told</em> you that stuff would come in handy!) and
the concept of half-open ranges. the concept of half-open ranges.
</p> </p>
<p>First, some history, and a reminder of some of the funkier rules in <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 C and C++ for builtin arrays. The following rules have always been
true for both languages: true for both languages:
<ol> </p>
<li>You can point anywhere in the array, <em>or to the first element <ol>
past the end of the array</em>. A pointer that points to one <li>You can point anywhere in the array, <em>or to the first element
past the end of the array is guaranteed to be as unique as a past the end of the array</em>. A pointer that points to one
pointer to somewhere inside the array, so that you can compare past the end of the array is guaranteed to be as unique as a
such pointers safely. pointer to somewhere inside the array, so that you can compare
<li>You can only dereference a pointer that points into an array. such pointers safely.
If your array pointer points outside the array -- even to just </li>
one past the end -- and you dereference it, Bad Things happen. <li>You can only dereference a pointer that points into an array.
<li>Strictly speaking, simply pointing anywhere else invokes If your array pointer points outside the array -- even to just
undefined behavior. Most programs won't puke until such a one past the end -- and you dereference it, Bad Things happen.
pointer is actually dereferenced, but the standards leave that </li>
up to the platform. <li>Strictly speaking, simply pointing anywhere else invokes
</ol> undefined behavior. Most programs won't puke until such a
The reason this past-the-end addressing was allowed is to make it pointer is actually dereferenced, but the standards leave that
up to the platform.
</li>
</ol>
<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., easy to write a loop to go over an entire array, e.g.,
while (*d++ = *s++);. while (*d++ = *s++);.
</p> </p>
<p>So, when you think of two pointers delimiting an array, don't think <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 <em>boundary of them as indexing 0 through n-1. Think of them as <em>boundary
markers</em>: markers</em>:
<pre> </p>
<pre>
beginning end beginning end
| | | |
@ -121,8 +125,8 @@
| | dereference 'end'. | | dereference 'end'.
beginning end beginning end
</pre> </pre>
See? Everything between the boundary markers is part of the array. <p>See? Everything between the boundary markers is part of the array.
Simple. Simple.
</p> </p>
<p>Now think back to your junior-high school algebra course, when you <p>Now think back to your junior-high school algebra course, when you
@ -171,7 +175,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

45
libstdc++-v3/docs/html/25_algorithms/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 25</title> <title>libstdc++-v3 HOWTO: Chapter 25</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -19,14 +18,14 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Prerequisites</a> <li><a href="#1">Prerequisites</a></li>
<li><a href="#2">Special <code>swap</code>s</a> <li><a href="#2">Special <code>swap</code>s</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -34,16 +33,18 @@
<p>The neatest accomplishment of the algorithms chapter is that all the <p>The neatest accomplishment of the algorithms chapter is that all the
work is done via iterators, not containers directly. This means two work is done via iterators, not containers directly. This means two
important things: important things:
<ol>
<li>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.
<li>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.
</ol>
</p> </p>
<ol>
<li>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.
</li>
<li>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.
</li>
</ol>
<p>Even strings can be fed through the algorithms here, although the <p>Even strings can be fed through the algorithms here, although the
string class has specialized versions of many of these functions (for string class has specialized versions of many of these functions (for
example, <code>string::find()</code>). Most of the examples on this example, <code>string::find()</code>). Most of the examples on this
@ -67,7 +68,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Special <code>swap</code>s</a></h2> <h2><a name="2">Special <code>swap</code>s</a></h2>
<p>If you call <code> std::swap(x,y); </code> where x and y are standard <p>If you call <code> std::swap(x,y); </code> where x and y are standard
containers, then the call will automatically be replaced by a call to containers, then the call will automatically be replaced by a call to
@ -90,7 +91,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

71
libstdc++-v3/docs/html/26_numerics/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 26</title> <title>libstdc++-v3 HOWTO: Chapter 26</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -15,29 +14,32 @@
<p>Chapter 26 deals with building block abstractions to aid in <p>Chapter 26 deals with building block abstractions to aid in
numerical computing: numerical computing:
<ul> </p>
<li>Template data structures such as <code>valarray&lt;&gt;</code> <ul>
and <code>complex&lt;&gt;</code>. <li>Template data structures such as <code>valarray&lt;&gt;</code>
<li>Template numerical functions such as <code>accumulate</code>, and <code>complex&lt;&gt;</code>.
<code>inner_product</code>, <code>partial_sum</code>, and </li>
<code>adjacent_difference</code>. <li>Template numerical functions such as <code>accumulate</code>,
</ul> <code>inner_product</code>, <code>partial_sum</code>, and
All of the Standard C math functions are of course included in C++, <code>adjacent_difference</code>.
</li>
</ul>
<p>All of the Standard C math functions are of course included in C++,
and overloaded versions for <code>long</code>, <code>float</code>, and and overloaded versions for <code>long</code>, <code>float</code>, and
<code>long double</code> have been added for all of them. <code>long double</code> have been added for all of them.
</p> </p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Complex Number Processing</a> <li><a href="#1">Complex Number Processing</a></li>
<li><a href="#2">Array Processing</a> <li><a href="#2">Array Processing</a></li>
<li><a href="#3">Numerical Functions</a> <li><a href="#3">Numerical Functions</a></li>
<li><a href="#4">C99</a> <li><a href="#4">C99</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -62,7 +64,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Array Processing</a></h2> <h2><a name="2">Array Processing</a></h2>
<p>One of the major reasons why FORTRAN can chew through numbers so well <p>One of the major reasons why FORTRAN can chew through numbers so well
is that it is defined to be free of pointer aliasing, an assumption is that it is defined to be free of pointer aliasing, an assumption
@ -87,22 +89,23 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Numerical Functions</a></h2> <h2><a name="3">Numerical Functions</a></h2>
<p>There are four generalized functions in the &lt;numeric&gt; header <p>There are four generalized functions in the &lt;numeric&gt; header
that follow the same conventions as those in &lt;algorithm&gt;. Each that follow the same conventions as those in &lt;algorithm&gt;. Each
of them is overloaded: one signature for common default operations, of them is overloaded: one signature for common default operations,
and a second for fully general operations. Their names are and a second for fully general operations. Their names are
self-explanatory to anyone who works with numerics on a regular basis: self-explanatory to anyone who works with numerics on a regular basis:
<ul>
<li><code>accumulate</code>
<li><code>inner_product</code>
<li><code>partial_sum</code>
<li><code>adjacent_difference</code>
</ul>
</p> </p>
<ul>
<li><code>accumulate</code></li>
<li><code>inner_product</code></li>
<li><code>partial_sum</code></li>
<li><code>adjacent_difference</code></li>
</ul>
<p>Here is a simple example of the two forms of <code>accumulate</code>. <p>Here is a simple example of the two forms of <code>accumulate</code>.
<pre> </p>
<pre>
int ar[50]; int ar[50];
int someval = somefunction(); int someval = somefunction();
@ -111,8 +114,8 @@
int sum = std::accumulate(ar,ar+50,0); int sum = std::accumulate(ar,ar+50,0);
int sum_stuff = std::accumulate(ar,ar+50,someval); int sum_stuff = std::accumulate(ar,ar+50,someval);
int product = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;()); int product = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
</pre> </pre>
The first call adds all the members of the array, using zero as an <p>The first call adds all the members of the array, using zero as an
initial value for <code>sum</code>. The second does the same, but uses initial value for <code>sum</code>. The second does the same, but uses
<code>someval</code> as the starting value (thus, <code>sum_stuff == sum + <code>someval</code> as the starting value (thus, <code>sum_stuff == sum +
someval</code>). The final call uses the second of the two signatures, someval</code>). The final call uses the second of the two signatures,
@ -125,7 +128,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">C99</a></h2> <h2><a name="4">C99</a></h2>
<p>In addition to the other topics on this page, we'll note here some <p>In addition to the other topics on this page, we'll note here some
of the C99 features that appear in libstdc++-v3. of the C99 features that appear in libstdc++-v3.
@ -151,7 +154,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

148
libstdc++-v3/docs/html/27_io/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27."> <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 27</title> <title>libstdc++-v3 HOWTO: Chapter 27</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -19,20 +18,20 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Copying a file</a> <li><a href="#1">Copying a file</a></li>
<li><a href="#2">The buffering is screwing up my program!</a> <li><a href="#2">The buffering is screwing up my program!</a></li>
<li><a href="#3">Binary I/O</a> <li><a href="#3">Binary I/O</a></li>
<li><a href="#5">What is this &lt;sstream&gt;/stringstreams thing?</a> <li><a href="#5">What is this &lt;sstream&gt;/stringstreams thing?</a></li>
<li><a href="#6">Deriving a stream buffer</a> <li><a href="#6">Deriving a stream buffer</a></li>
<li><a href="#7">More on binary I/O</a> <li><a href="#7">More on binary I/O</a></li>
<li><a href="#8">Pathetic performance? Ditch C.</a> <li><a href="#8">Pathetic performance? Ditch C.</a></li>
<li><a href="#9">Threads and I/O</a> <li><a href="#9">Threads and I/O</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -40,27 +39,29 @@
<p>So you want to copy a file quickly and easily, and most important, <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 completely portably. And since this is C++, you have an open
ifstream (call it IN) and an open ofstream (call it OUT): ifstream (call it IN) and an open ofstream (call it OUT):
<pre> </p>
<pre>
#include &lt;fstream&gt; #include &lt;fstream&gt;
std::ifstream IN ("input_file"); std::ifstream IN ("input_file");
std::ofstream OUT ("output_file"); </pre> std::ofstream OUT ("output_file"); </pre>
</p>
<p>Here's the easiest way to get it completely wrong: <p>Here's the easiest way to get it completely wrong:
<pre> </p>
<pre>
OUT &lt;&lt; IN;</pre> OUT &lt;&lt; IN;</pre>
For those of you who don't already know why this doesn't work <p>For those of you who don't already know why this doesn't work
(probably from having done it before), I invite you to quickly (probably from having done it before), I invite you to quickly
create a simple text file called &quot;input_file&quot; containing create a simple text file called &quot;input_file&quot; containing
the sentence the sentence
</p>
<pre> <pre>
The quick brown fox jumped over the lazy dog.</pre> The quick brown fox jumped over the lazy dog.</pre>
surrounded by blank lines. Code it up and try it. The contents <p>surrounded by blank lines. Code it up and try it. The contents
of &quot;output_file&quot; may surprise you. of &quot;output_file&quot; may surprise you.
</p> </p>
<p>Seriously, go do it. Get surprised, then come back. It's worth it. <p>Seriously, go do it. Get surprised, then come back. It's worth it.
</p> </p>
<hr width="60%"> <hr width="60%" />
<p>The thing to remember is that the <code>basic_[io]stream</code> classes <p>The thing to remember is that the <code>basic_[io]stream</code> classes
handle formatting, nothing else. In particular, they break up on handle formatting, nothing else. In particular, they break up on
whitespace. The actual reading, writing, and storing of data is whitespace. The actual reading, writing, and storing of data is
@ -76,9 +77,9 @@
as well as the streams themselves. The pointer is easily retrieved as well as the streams themselves. The pointer is easily retrieved
using the <code>rdbuf()</code> member function. Therefore, the easiest using the <code>rdbuf()</code> member function. Therefore, the easiest
way to copy the file is: way to copy the file is:
<pre>
OUT &lt;&lt; IN.rdbuf();</pre>
</p> </p>
<pre>
OUT &lt;&lt; IN.rdbuf();</pre>
<p>So what <em>was</em> happening with OUT&lt;&lt;IN? Undefined <p>So what <em>was</em> happening with OUT&lt;&lt;IN? Undefined
behavior, since that particular &lt;&lt; isn't defined by the Standard. behavior, since that particular &lt;&lt; isn't defined by the Standard.
I have seen instances where it is implemented, but the character I have seen instances where it is implemented, but the character
@ -89,7 +90,7 @@
file then contains a perfect text representation of a hexidecimal file then contains a perfect text representation of a hexidecimal
address (quite a big surprise). Others don't compile at all. address (quite a big surprise). Others don't compile at all.
</p> </p>
<p>Also note that none of this is specific to o<B>*f*</B>streams. <p>Also note that none of this is specific to o<b>*f*</b>streams.
The operators shown above are all defined in the parent The operators shown above are all defined in the parent
basic_ostream class and are therefore available with all possible basic_ostream class and are therefore available with all possible
descendents. descendents.
@ -98,7 +99,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">The buffering is screwing up my program!</a></h2> <h2><a name="2">The buffering is screwing up my program!</a></h2>
<!-- <!--
This is not written very well. I need to redo this section. This is not written very well. I need to redo this section.
@ -122,35 +123,38 @@
is the effect you want when writing to a screen -- get the text is the effect you want when writing to a screen -- get the text
out as soon as possible, etc -- but the buffering is largely out as soon as possible, etc -- but the buffering is largely
wasted when doing this to a file: wasted when doing this to a file:
<pre> </p>
<pre>
output &lt;&lt; &quot;a line of text&quot; &lt;&lt; endl; output &lt;&lt; &quot;a line of text&quot; &lt;&lt; endl;
output &lt;&lt; some_data_variable &lt;&lt; endl; output &lt;&lt; some_data_variable &lt;&lt; endl;
output &lt;&lt; &quot;another line of text&quot; &lt;&lt; endl; </pre> output &lt;&lt; &quot;another line of text&quot; &lt;&lt; endl; </pre>
The proper thing to do in this case to just write the data out <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. and let the libraries and the system worry about the buffering.
If you need a newline, just write a newline: If you need a newline, just write a newline:
<pre> </p>
<pre>
output &lt;&lt; &quot;a line of text\n&quot; output &lt;&lt; &quot;a line of text\n&quot;
&lt;&lt; some_data_variable &lt;&lt; '\n' &lt;&lt; some_data_variable &lt;&lt; '\n'
&lt;&lt; &quot;another line of text\n&quot;; </pre> &lt;&lt; &quot;another line of text\n&quot;; </pre>
I have also joined the output statements into a single statement. <p>I have also joined the output statements into a single statement.
You could make the code prettier by moving the single newline to You could make the code prettier by moving the single newline to
the start of the quoted text on the thing line, for example. the start of the quoted text on the thing line, for example.
</p> </p>
<p>If you do need to flush the buffer above, you can send an <p>If you do need to flush the buffer above, you can send an
<code>endl</code> if you also need a newline, or just flush the buffer <code>endl</code> if you also need a newline, or just flush the buffer
yourself: yourself:
<pre> </p>
<pre>
output &lt;&lt; ...... &lt;&lt; flush; // can use std::flush manipulator output &lt;&lt; ...... &lt;&lt; flush; // can use std::flush manipulator
output.flush(); // or call a member fn </pre> output.flush(); // or call a member fn </pre>
</p>
<p>On the other hand, there are times when writing to a file should <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 be like writing to standard error; no buffering should be done
because the data needs to appear quickly (a prime example is a because the data needs to appear quickly (a prime example is a
log file for security-related information). The way to do this is log file for security-related information). The way to do this is
just to turn off the buffering <em>before any I/O operations at just to turn off the buffering <em>before any I/O operations at
all</em> have been done, i.e., as soon as possible after opening: all</em> have been done, i.e., as soon as possible after opening:
<pre> </p>
<pre>
std::ofstream os (&quot;/foo/bar/baz&quot;); std::ofstream os (&quot;/foo/bar/baz&quot;);
std::ifstream is (&quot;/qux/quux/quuux&quot;); std::ifstream is (&quot;/qux/quux/quuux&quot;);
int i; int i;
@ -160,7 +164,6 @@
... ...
os &lt;&lt; &quot;this data is written immediately\n&quot;; os &lt;&lt; &quot;this data is written immediately\n&quot;;
is &gt;&gt; i; // and this will probably cause a disk read </pre> is &gt;&gt; i; // and this will probably cause a disk read </pre>
</p>
<p>Since all aspects of buffering are handled by a streambuf-derived <p>Since all aspects of buffering are handled by a streambuf-derived
member, it is necessary to get at that member with <code>rdbuf()</code>. member, it is necessary to get at that member with <code>rdbuf()</code>.
Then the public version of <code>setbuf</code> can be called. The Then the public version of <code>setbuf</code> can be called. The
@ -189,7 +192,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Binary I/O</a></h2> <h2><a name="3">Binary I/O</a></h2>
<p>The first and most important thing to remember about binary I/O is <p>The first and most important thing to remember about binary I/O is
that opening a file with <code>ios::binary</code> is not, repeat that opening a file with <code>ios::binary</code> is not, repeat
@ -234,25 +237,28 @@
of <em>formatting</em> functions and classes to perform something of <em>formatting</em> functions and classes to perform something
which <em>requires</em> that formatting not be done? There are a which <em>requires</em> that formatting not be done? There are a
seemingly infinite number of solutions, and a few are listed here: seemingly infinite number of solutions, and a few are listed here:
<ul>
<li>&quot;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.&quot; 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.
<li>&quot;Build the file structure in memory, then <code>mmap()</code>
the file and copy the structure.&quot; Well, this is easy to
make work, and easy to break, and is pretty equivalent to
using <code>::read()</code> and <code>::write()</code> directly, and
makes no use of the iostream library at all...
<li>&quot;Use streambufs, that's what they're there for.&quot;
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.
</ul>
</p> </p>
<ul>
<li>&quot;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.&quot; 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.
</li>
<li>&quot;Build the file structure in memory, then <code>mmap()</code>
the file and copy the structure.&quot; Well, this is easy to
make work, and easy to break, and is pretty equivalent to
using <code>::read()</code> and <code>::write()</code> directly, and
makes no use of the iostream library at all...
</li>
<li>&quot;Use streambufs, that's what they're there for.&quot;
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.
</li>
</ul>
<p>How to go about using streambufs is a bit beyond the scope of this <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, document (at least for now), but while streambufs go a long way,
they still leave a couple of things up to you, the programmer. they still leave a couple of things up to you, the programmer.
@ -287,7 +293,7 @@
made are good ones.) made are good ones.)
</p> </p>
<hr> <hr />
<h2><a name="5">What is this &lt;sstream&gt;/stringstreams thing?</a></h2> <h2><a name="5">What is this &lt;sstream&gt;/stringstreams thing?</a></h2>
<p>Stringstreams (defined in the header <code>&lt;sstream&gt;</code>) <p>Stringstreams (defined in the header <code>&lt;sstream&gt;</code>)
are in this author's opinion one of the coolest things since are in this author's opinion one of the coolest things since
@ -311,7 +317,7 @@
<p>This only works if you've written your <p>This only works if you've written your
<code>&lt;&lt;</code>/<code>&gt;&gt;</code> functions correctly, though, <code>&lt;&lt;</code>/<code>&gt;&gt;</code> functions correctly, though,
and correctly means that they take istreams and ostreams as and correctly means that they take istreams and ostreams as
parameters, not i<B>f</B>streams and o<B>f</B>streams. If they parameters, not i<b>f</b>streams and o<b>f</b>streams. If they
take the latter, then your I/O operators will work fine with take the latter, then your I/O operators will work fine with
file streams, but with nothing else -- including stringstreams. file streams, but with nothing else -- including stringstreams.
</p> </p>
@ -324,7 +330,7 @@
support them, and 2) if you use them, people will laugh at you. support them, and 2) if you use them, people will laugh at you.
</p> </p>
<hr> <hr />
<h2><a name="6">Deriving a stream buffer</a></h2> <h2><a name="6">Deriving a stream buffer</a></h2>
<p>Creating your own stream buffers for I/O can be remarkably easy. <p>Creating your own stream buffers for I/O can be remarkably easy.
If you are interested in doing so, we highly recommend two very If you are interested in doing so, we highly recommend two very
@ -339,7 +345,8 @@
transforms everything sent through it to uppercase. This version transforms everything sent through it to uppercase. This version
assumes many things about the nature of the character type being assumes many things about the nature of the character type being
used (for more information, read the books or the newsgroups): used (for more information, read the books or the newsgroups):
<pre> </p>
<pre>
#include &lt;iostream&gt; #include &lt;iostream&gt;
#include &lt;streambuf&gt; #include &lt;streambuf&gt;
#include &lt;locale&gt; #include &lt;locale&gt;
@ -377,11 +384,11 @@
return 0; return 0;
} }
</pre> </pre>
Try it yourself! More examples can be found in 3.1.x code, in <p>Try it yourself! More examples can be found in 3.1.x code, in
<code>include/ext/*_filebuf.h</code>. <code>include/ext/*_filebuf.h</code>.
</p> </p>
<hr> <hr />
<h2><a name="7">More on binary I/O</a></h2> <h2><a name="7">More on binary I/O</a></h2>
<p>Towards the beginning of February 2001, the subject of <p>Towards the beginning of February 2001, the subject of
&quot;binary&quot; I/O was brought up in a couple of places at the &quot;binary&quot; I/O was brought up in a couple of places at the
@ -406,22 +413,23 @@
a portable binary format. a portable binary format.
</p> </p>
<hr> <hr />
<h2><a name="8">Pathetic performance? Ditch C.</a></h2> <h2><a name="8">Pathetic performance? Ditch C.</a></h2>
<p>It sounds like a flame on C, but it isn't. Really. Calm down. <p>It sounds like a flame on C, but it isn't. Really. Calm down.
I'm just saying it to get your attention. I'm just saying it to get your attention.
</p> </p>
<p>Because the C++ library includes the C library, both C-style and <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: C++-style I/O have to work at the same time. For example:
<pre> </p>
<pre>
#include &lt;iostream&gt; #include &lt;iostream&gt;
#include &lt;cstdio&gt; #include &lt;cstdio&gt;
std::cout &lt;&lt; &quot;Hel&quot;; std::cout &lt;&lt; &quot;Hel&quot;;
std::printf (&quot;lo, worl&quot;); std::printf (&quot;lo, worl&quot;);
std::cout &lt;&lt; &quot;d!\n&quot;; std::cout &lt;&lt; &quot;d!\n&quot;;
</pre> </pre>
This must do what you think it does. <p>This must do what you think it does.
</p> </p>
<p>Alert members of the audience will immediately notice that buffering <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. is going to make a hash of the output unless special steps are taken.
@ -440,12 +448,12 @@
when both libraries' facilities are in use. If your program only uses 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 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 thing to do in this case is to call
<pre> </p>
<pre>
#include <em>any of the I/O headers such as ios, iostream, etc</em> #include <em>any of the I/O headers such as ios, iostream, etc</em>
std::ios::sync_with_stdio(false); std::ios::sync_with_stdio(false);
</pre> </pre>
</p>
<p>You must do this before performing any I/O via the C++ stream objects. <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 Once you call this, the C++ streams will operate independently of the
(unused) C streams. For GCC 3.x, this means that <code>cout</code> and (unused) C streams. For GCC 3.x, this means that <code>cout</code> and
@ -459,7 +467,7 @@
buffered. buffered.
</p> </p>
<hr> <hr />
<h2><a name="9">Threads and I/O</a></h2> <h2><a name="9">Threads and I/O</a></h2>
<p>I'll assume that you have already read the <p>I'll assume that you have already read the
<a href="../17_intro/howto.html#3">general notes on library threads</a>, <a href="../17_intro/howto.html#3">general notes on library threads</a>,
@ -548,7 +556,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

2
libstdc++-v3/docs/html/Makefile
View file

@ -13,7 +13,7 @@ documentation.html: $(wildcard */howto.html)
sed -n '1,/beginlist/p' $@ > tmp.top sed -n '1,/beginlist/p' $@ > tmp.top
sed -n '/endlist/,$$p' $@ > tmp.bottom sed -n '/endlist/,$$p' $@ > tmp.bottom
echo ' <ul>' > tmp.middle echo ' <ul>' > tmp.middle
for i in [[:digit:]]*/howto.html; do \ for i in [0-9]*/howto.html; do \
title=`grep 'h1 ' $$i |\ title=`grep 'h1 ' $$i |\
sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\ sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\
awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\ awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\

74
libstdc++-v3/docs/html/configopts.html
View file

@ -1,12 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="Configuration options for libstdc++-v3."> <meta name="DESCRIPTION" content="Configuration options for libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 configure options</title> <title>libstdc++-v3 configure options</title>
<link rel="StyleSheet" href="lib3styles.css"> <link rel="StyleSheet" href="lib3styles.css" />
</head> </head>
<body> <body>
@ -19,10 +18,10 @@ options</a></h1>
</p> </p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p>Here are some of the non-obvious options to libstdc++'s configure. <p>Here are some of the non-obvious options to libstdc++'s configure.
Keep in mind that Keep in mind that
<!-- This SECnn should be the "Choosing Package Options" section. --> <!-- This SECnn should be the "Choosing Package Options" section. -->
@ -37,15 +36,16 @@ options</a></h1>
</p> </p>
<dl> <dl>
<dt><code>--enable-multilib </code>[default] <dt><code>--enable-multilib </code>[default]</dt>
<dd><p>This is part of the generic multilib support for building cross <dd><p>This is part of the generic multilib support for building cross
compilers. As such, targets like &quot;powerpc-elf&quot; will have compilers. As such, targets like &quot;powerpc-elf&quot; will have
libstdc++ built many different ways: &quot;-msoft-float&quot; libstdc++ built many different ways: &quot;-msoft-float&quot;
and not, etc. A different libstdc++ will be built for each of and not, etc. A different libstdc++ will be built for each of
the different multilib versions. This option is on by default. the different multilib versions. This option is on by default.
</p> </p>
</dd>
<dt><code>--enable-debug </code> <dt><code>--enable-debug </code></dt>
<dd><p>The configure script will automatically detect the highest <dd><p>The configure script will automatically detect the highest
level of optimization that the compiler in use can use. level of optimization that the compiler in use can use.
This --enable flag will disable all optimizations and instruct This --enable flag will disable all optimizations and instruct
@ -55,13 +55,15 @@ options</a></h1>
configuration difference: configuration difference:
<code>make CXXFLAGS='-g -O0' all</code> <code>make CXXFLAGS='-g -O0' all</code>
</p> </p>
</dd>
<dt><code>--enable-cstdio </code> <dt><code>--enable-cstdio </code></dt>
<dd><p>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code> <dd><p>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
(described next). (described next).
</p> </p>
</dd>
<dt><code>--enable-cstdio=LIB </code> <dt><code>--enable-cstdio=LIB </code></dt>
<dd><p>Select a target-specific I/O package. As of libstdc++-v3 <dd><p>Select a target-specific I/O package. As of libstdc++-v3
snapshot 3.0.96, the choices are 'libio' to specify the GNU snapshot 3.0.96, the choices are 'libio' to specify the GNU
I/O package (from I/O package (from
@ -70,32 +72,36 @@ options</a></h1>
abstraction. The default is 'stdio'. A longer explanation abstraction. The default is 'stdio'. A longer explanation
is <a href="explanations.html#cstdio">here</a>. is <a href="explanations.html#cstdio">here</a>.
</p> </p>
</dd>
<dt><code>--enable-sjlj-exceptions </code> <dt><code>--enable-sjlj-exceptions </code></dt>
<dd><p>Forces old, set-jump/long-jump exception handling model. If <dd><p>Forces old, set-jump/long-jump exception handling model. If
at all possible, the new, frame unwinding exception handling routines at all possible, the new, frame unwinding exception handling routines
should be used instead, as they significantly reduce both runtime should be used instead, as they significantly reduce both runtime
memory usage and executable size. memory usage and executable size.
</p> </p>
</dd>
<dt><code>--enable-clocale </code> <dt><code>--enable-clocale </code></dt>
<dd><p>This is an abbreviated form of <code>'--enable-clocale=generic'</code> <dd><p>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
(described next). (described next).
</p> </p>
</dd>
<dt><code>--enable-clocale=MODEL </code> <dt><code>--enable-clocale=MODEL </code></dt>
<dd><p>Select a target-specific underlying locale package. The <dd><p>Select a target-specific underlying locale package. The
choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
(IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
'gnu' to specify a model based on functionality from the GNU C 'gnu' to specify a model based on functionality from the GNU C
library (langinfo/iconv/gettext) (from <A library (langinfo/iconv/gettext) (from <a
href="http://sources.redhat.com/glibc/">glibc</a>, the GNU C href="http://sources.redhat.com/glibc/">glibc</a>, the GNU C
library), or 'generic' to use a generic &quot;C&quot; library), or 'generic' to use a generic &quot;C&quot;
abstraction which consists of &quot;C&quot; locale info. The abstraction which consists of &quot;C&quot; locale info. The
default is 'generic'. default is 'generic'.
</p> </p>
</dd>
<dt><code>--enable-c99 </code> <dt><code>--enable-c99 </code></dt>
<dd><p>The &quot;long long&quot; type was introduced in C99, along <dd><p>The &quot;long long&quot; type was introduced in C99, along
with many other functions for wide characters, and math with many other functions for wide characters, and math
classification macros, etc. If enabled, all C99 functions not classification macros, etc. If enabled, all C99 functions not
@ -108,8 +114,9 @@ options</a></h1>
configure probes find all the necessary functions and bits configure probes find all the necessary functions and bits
necessary. necessary.
</p> </p>
</dd>
<dt><code>--enable-long-long </code> <dt><code>--enable-long-long </code></dt>
<dd><p>The &quot;long long&quot; type was introduced in C99. It is <dd><p>The &quot;long long&quot; type was introduced in C99. It is
provided as a GNU extension to C++98 in g++. This flag builds provided as a GNU extension to C++98 in g++. This flag builds
support for &quot;long long&quot; into the library (specialized support for &quot;long long&quot; into the library (specialized
@ -121,26 +128,30 @@ options</a></h1>
the flag is -D_ISOC99_SOURCE, which is added automatically via the flag is -D_ISOC99_SOURCE, which is added automatically via
CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
</p> </p>
</dd>
<dt><code>--enable-cheaders=OPTION </code> <dt><code>--enable-cheaders=OPTION </code></dt>
<dd><p>This allows the user to define what kind of C headers are <dd><p>This allows the user to define what kind of C headers are
used. Options are: c, c_std, and c_shadow. These correspond used. Options are: c, c_std, and c_shadow. These correspond
to the source directory's include/c, include/c_std, and to the source directory's include/c, include/c_std, and
include/c_shadow directories. The default is c_std. include/c_shadow directories. The default is c_std.
</p> </p>
</dd>
<dt><code>--enable-threads </code> <dt><code>--enable-threads </code></dt>
<dd><p>This is an abbreviated form of <code>'--enable-threads=yes'</code> <dd><p>This is an abbreviated form of <code>'--enable-threads=yes'</code>
(described next). (described next).
</p> </p>
</dd>
<dt><code>--enable-threads=LIB </code> <dt><code>--enable-threads=LIB </code></dt>
<dd><p>Select a threading library. A full description is given in the <dd><p>Select a threading library. A full description is given in the
general <a href="http://gcc.gnu.org/install/configure.html">compiler general <a href="http://gcc.gnu.org/install/configure.html">compiler
configuration instructions</a>. configuration instructions</a>.
</p> </p>
</dd>
<dt><code>--enable-version-specific-runtime-libs </code> <dt><code>--enable-version-specific-runtime-libs </code></dt>
<dd><p>Specify that run-time libraries should be installed in the <dd><p>Specify that run-time libraries should be installed in the
compiler-specific subdirectory (i.e., compiler-specific subdirectory (i.e.,
<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
@ -151,17 +162,18 @@ options</a></h1>
unless you also specify unless you also specify
<code>--with-gxx-include-dir=<em>dirname</em></code> during configuration. <code>--with-gxx-include-dir=<em>dirname</em></code> during configuration.
</p> </p>
</dd>
<dt><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code> <dt><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code></dt>
<dd><p>Adds support for named libstdc++ include directory. For instance, <dd><p>Adds support for named libstdc++ include directory. For instance,
the following puts all the libstdc++ headers into a directory the following puts all the libstdc++ headers into a directory
called &quot;2.97-20001008&quot; instead of the usual called &quot;2.97-20001008&quot; instead of the usual
&quot;g++-v3&quot;. &quot;g++-v3&quot;.
</p> </p>
<pre> <pre>
--with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</pre> --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</pre> </dd>
<dt><code>--enable-cxx-flags=FLAGS</code> <dt><code>--enable-cxx-flags=FLAGS</code></dt>
<dd><p>With this option, you can pass a string of -f (functionality) <dd><p>With this option, you can pass a string of -f (functionality)
flags to the compiler to use when building libstdc++. FLAGS flags to the compiler to use when building libstdc++. FLAGS
is a quoted string of options, like is a quoted string of options, like
@ -188,8 +200,9 @@ options</a></h1>
<p>and opposite forms (-fno-) of the same. Tell us (the libstdc++ <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> </p>
</dd>
<dt><code>--enable-c-mbchar </code>[default] <dt><code>--enable-c-mbchar </code>[default]</dt>
<dd><p>Certain template specializations are required for wide <dd><p>Certain template specializations are required for wide
character conversion support. This is tricky and currently character conversion support. This is tricky and currently
changing rapidly, and can cause problems on new platforms. changing rapidly, and can cause problems on new platforms.
@ -197,16 +210,18 @@ options</a></h1>
porting steps, but builds only a subset of what is required by porting steps, but builds only a subset of what is required by
ISO. By default, this option is on. ISO. By default, this option is on.
</p> </p>
</dd>
<dt><code>--enable-concept-checks </code> <dt><code>--enable-concept-checks </code></dt>
<dd><p>This turns on additional compile-time checks for instantiated <dd><p>This turns on additional compile-time checks for instantiated
library templates, in the form of specialized templates, library templates, in the form of specialized templates,
<a href="19_diagnostics/howto.html#3">described here</a>. They <a href="19_diagnostics/howto.html#3">described here</a>. They
can help users discover when they break the rules of the STL, before can help users discover when they break the rules of the STL, before
their programs run. their programs run.
</p> </p>
</dd>
<dt><code>--enable-symvers[=style] </code> <dt><code>--enable-symvers[=style] </code></dt>
<dd><p>In 3.1, tries to turn on symbol versioning in the shared library (if a <dd><p>In 3.1, tries to turn on symbol versioning in the shared library (if a
shared library has been requested). The only 'style' currently shared library has been requested). The only 'style' currently
supported is 'gnu' which requires that a recent version of the GNU supported is 'gnu' which requires that a recent version of the GNU
@ -214,6 +229,7 @@ options</a></h1>
try to guess if the 'gnu' style can be used, and if so, will turn it try to guess if the 'gnu' style can be used, and if so, will turn it
on. Hopefully people will volunteer to do other 'style' options. on. Hopefully people will volunteer to do other 'style' options.
</p> </p>
</dd>
</dl> </dl>
<p>Return <a href="#top">to the top of the page</a> or <p>Return <a href="#top">to the top of the page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>. <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
@ -222,7 +238,7 @@ options</a></h1>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions. See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

116
libstdc++-v3/docs/html/documentation.html
View file

@ -1,10 +1,9 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html> <html>
<head> <head>
<meta name="KEYWORDS" <meta name="KEYWORDS"
content="libstdc++, homepage, home, C++, library, c++, std, g++, ABI, STL"> content="libstdc++, homepage, home, C++, library, c++, std, g++, ABI, STL" />
<title>GNU C++ Standard Library</title> <title>GNU C++ Standard Library</title>
<link rel="StyleSheet" href="lib3styles.css"> <link rel="StyleSheet" href="lib3styles.css" />
</head> </head>
<body> <body>
@ -15,40 +14,40 @@
automatically-generated source documentation, available separately. automatically-generated source documentation, available separately.
</p> </p>
<hr /> <hr />
<br> <br />
<h2><a name="1">Introduction</a></h2> <h2><a name="1">Introduction</a></h2>
<p>This is a short list of text files pertaining to this implementation of <p>This is a short list of text files pertaining to this implementation of
ISO 14882. A brief description may follow the name of the file. ISO 14882. A brief description may follow the name of the file.
</p>
<ul> <ul>
<li><a href="17_intro/COPYING">License</a> <li><a href="17_intro/COPYING">License</a>
- GPL v2 license terms - GPL v2 license terms</li>
<li><a href="abi.txt">ABI Policy and Guidelines</a> <li><a href="abi.txt">ABI Policy and Guidelines</a></li>
<li><a href="17_intro/BUGS">BUGS</a> <li><a href="17_intro/BUGS">BUGS</a></li>
<li><a href="17_intro/PROBLEMS">PROBLEMS</a> <li><a href="17_intro/PROBLEMS">PROBLEMS</a>
- target-specific known issues - target-specific known issues</li>
<!-- Linking to "../README" doesn't work; we are at the top level <!-- Linking to "../README" doesn't work; we are at the top level
of the web pages. Punt. --> of the web pages. Punt. -->
<li>README - directory structure <li>README - directory structure</li>
<li><a href="17_intro/RELEASE-NOTES">RELEASE-NOTES</a> <li><a href="17_intro/RELEASE-NOTES">RELEASE-NOTES</a>
- latest version info, recent changes and news - latest version info, recent changes and news</li>
<li><a href="17_intro/TODO">TODO</a> <li><a href="17_intro/TODO">TODO</a>
- tasks yet undone - tasks yet undone</li>
</ul> </ul>
<hr /> <hr />
<br> <br />
<h2><a name="2">Configuring, Building, Installing</a></h2> <h2><a name="2">Configuring, Building, Installing</a></h2>
<ul> <ul>
<li><a href="configopts.html">Configure options</a> <li><a href="configopts.html">Configure options</a></li>
<li><a href="install.html">Getting started: configure, build, install</a> <li><a href="install.html">Getting started: configure, build, install</a>
</ul> </li>
</ul>
<hr /> <hr />
<br> <br />
<h2><a name="4">Source-Level Documentation</a></h2> <h2><a name="4">Source-Level Documentation</a></h2>
<p>The library sources have been specially formatted so that with the <p>The library sources have been specially formatted so that with the
proper invocation of another tool (Doxygen), a set of HTML pages proper invocation of another tool (Doxygen), a set of HTML pages
@ -58,13 +57,16 @@
the library classes, finding out what is in a particular include the library classes, finding out what is in a particular include
file, looking at inheritance diagrams, etc. file, looking at inheritance diagrams, etc.
</p> </p>
<p>The Source-Level documentation can be viewed online: <p>The Source-Level documentation can be viewed online:</p>
<ul> <ul>
<li><a href="libstdc++-html-USERS-3.1/index.html">for the 3.1 release</a> <li><a href="libstdc++-html-USERS-3.1/index.html">for the 3.1 release</a>
</li>
<li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2 release</a> <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2 release</a>
</li>
<li><a href="latest-doxygen/index.html">&quot;the latest collection&quot;</a> <li><a href="latest-doxygen/index.html">&quot;the latest collection&quot;</a>
(for the snapshot or later; see the date on the first page) (for the snapshot or later; see the date on the first page)
</ul> </li>
</ul>
<p>This generated HTML collection, as above, is also available for download in <p>This generated HTML collection, as above, is also available for download in
the libstdc++ snapshots directory at the libstdc++ snapshots directory at
<code>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/&gt;</code>. <code>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/&gt;</code>.
@ -81,7 +83,7 @@
<hr /> <hr />
<br> <br />
<h2><a name="3">Chapter-Specific Documentation</a></h2> <h2><a name="3">Chapter-Specific Documentation</a></h2>
<p>Information, extensions, notes and advice on specific implementation <p>Information, extensions, notes and advice on specific implementation
capabilites and/or liabilities broken down into chapter names based on the capabilites and/or liabilities broken down into chapter names based on the
@ -95,7 +97,7 @@
--> -->
<!-- beginlist --> <!-- beginlist -->
<ul> <ul>
<li>Library Introduction (Chapter 17)</li> <li>Library Introduction (Chapter 17)
<ul> <ul>
<li><a href="17_intro/howto.html#2">The Standard C++ header files</a></li> <li><a href="17_intro/howto.html#2">The Standard C++ header files</a></li>
<li><a href="17_intro/howto.html#3">The Standard C++ library and multithreading</a></li> <li><a href="17_intro/howto.html#3">The Standard C++ library and multithreading</a></li>
@ -104,8 +106,9 @@
<li><a href="17_intro/howto.html#5">Behavior specific to libstdc++-v3</a></li> <li><a href="17_intro/howto.html#5">Behavior specific to libstdc++-v3</a></li>
<li><a href="17_intro/howto.html#6">Preprocessor macros controlling the library</a></li> <li><a href="17_intro/howto.html#6">Preprocessor macros controlling the library</a></li>
</ul> </ul>
</li>
<li>Library Support (Chapter 18)</li> <li>Library Support (Chapter 18)
<ul> <ul>
<li><a href="18_support/howto.html#1">Types</a></li> <li><a href="18_support/howto.html#1">Types</a></li>
<li><a href="18_support/howto.html#2">Implementation properties</a></li> <li><a href="18_support/howto.html#2">Implementation properties</a></li>
@ -113,24 +116,27 @@
<li><a href="18_support/howto.html#4">Dynamic memory management</a></li> <li><a href="18_support/howto.html#4">Dynamic memory management</a></li>
<li><a href="18_support/howto.html#5">RTTI, the ABI, and demangling</a></li> <li><a href="18_support/howto.html#5">RTTI, the ABI, and demangling</a></li>
</ul> </ul>
</li>
<li>Diagnostics (Chapter 19)</li> <li>Diagnostics (Chapter 19)
<ul> <ul>
<li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li> <li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li>
<li><a href="19_diagnostics/howto.html#2">Exception class hierarchy diagram</a></li> <li><a href="19_diagnostics/howto.html#2">Exception class hierarchy diagram</a></li>
<li><a href="19_diagnostics/howto.html#3">Concept checkers -- <strong>new and improved!</strong></a></li> <li><a href="19_diagnostics/howto.html#3">Concept checkers -- <strong>new and improved!</strong></a></li>
<li><a href="19_diagnostics/howto.html#4">Verbose <code>terminate</code></a></li> <li><a href="19_diagnostics/howto.html#4">Verbose <code>terminate</code></a></li>
</ul> </ul>
</li>
<li>General Utilities (Chapter 20)</li> <li>General Utilities (Chapter 20)
<ul> <ul>
<li><a href="20_util/howto.html#1"><code>auto_ptr</code> is not omnipotent</a></li> <li><a href="20_util/howto.html#1"><code>auto_ptr</code> is not omnipotent</a></li>
<li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li> <li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li>
<li><a href="20_util/howto.html#3">Functors</a></li> <li><a href="20_util/howto.html#3">Functors</a></li>
<li><a href="20_util/howto.html#4">Pairs</a></li> <li><a href="20_util/howto.html#4">Pairs</a></li>
</ul> </ul>
</li>
<li>Strings (Chapter 21)</li> <li>Strings (Chapter 21)
<ul> <ul>
<li><a href="21_strings/howto.html#1">MFC's CString</a></li> <li><a href="21_strings/howto.html#1">MFC's CString</a></li>
<li><a href="21_strings/howto.html#2">A case-insensitive string class</a></li> <li><a href="21_strings/howto.html#2">A case-insensitive string class</a></li>
@ -138,19 +144,21 @@
<li><a href="21_strings/howto.html#4">Simple transformations</a></li> <li><a href="21_strings/howto.html#4">Simple transformations</a></li>
<li><a href="21_strings/howto.html#5">Making strings of arbitrary character types</a></li> <li><a href="21_strings/howto.html#5">Making strings of arbitrary character types</a></li>
</ul> </ul>
</li>
<li>Localization (Chapter 22)</li> <li>Localization (Chapter 22)
<ul> <ul>
<li><a href="22_locale/howto.html#1">class locale</a></li> <li><a href="22_locale/howto.html#1">class locale</a></li>
<li><a href="22_locale/howto.html#2">class codecvt</a></li> <li><a href="22_locale/howto.html#2">class codecvt</a></li>
<li><a href="22_locale/howto.html#3">class ctype</a></li> <li><a href="22_locale/howto.html#3">class ctype</a></li>
<li><a href="22_locale/howto.html#4">class messages</a></li> <li><a href="22_locale/howto.html#4">class messages</a></li>
<li><a href="22_locale/howto.html#5">Bjarne Stroustrup on Locales</a></li> <li><a href="22_locale/howto.html#5">Bjarne Stroustrup on Locales</a></li>
<li><a href="22_locale/howto.html#6">Nathan Myers on Locales </a></li> <li><a href="22_locale/howto.html#6">Nathan Myers on Locales</a></li>
<li><a href="22_locale/howto.html#7">Correct Transformations</a></li> <li><a href="22_locale/howto.html#7">Correct Transformations</a></li>
</ul> </ul>
</li>
<li>Containers (Chapter 23)</li> <li>Containers (Chapter 23)
<ul> <ul>
<li><a href="23_containers/howto.html#1">Making code unaware of the container/array difference</a></li> <li><a href="23_containers/howto.html#1">Making code unaware of the container/array difference</a></li>
<li><a href="23_containers/howto.html#2">Variable-sized bitmasks</a></li> <li><a href="23_containers/howto.html#2">Variable-sized bitmasks</a></li>
@ -160,28 +168,32 @@
<li><a href="23_containers/howto.html#6"><code>std::list::size()</code> is O(n)!</a></li> <li><a href="23_containers/howto.html#6"><code>std::list::size()</code> is O(n)!</a></li>
<li><a href="23_containers/howto.html#7">Space overhead management for vectors</a></li> <li><a href="23_containers/howto.html#7">Space overhead management for vectors</a></li>
</ul> </ul>
</li>
<li>Iterators (Chapter 24)</li> <li>Iterators (Chapter 24)
<ul> <ul>
<li><a href="24_iterators/howto.html#1">They ain't pointers!</a></li> <li><a href="24_iterators/howto.html#1">They ain't pointers!</a></li>
<li><a href="24_iterators/howto.html#2">It ends <em>where?</em></a></li> <li><a href="24_iterators/howto.html#2">It ends <em>where?</em></a></li>
</ul> </ul>
</li>
<li>Algorithms (Chapter 25)</li> <li>Algorithms (Chapter 25)
<ul> <ul>
<li><a href="25_algorithms/howto.html#1">Prerequisites</a></li> <li><a href="25_algorithms/howto.html#1">Prerequisites</a></li>
<li><a href="25_algorithms/howto.html#2">Special <code>swap</code>s</a></li> <li><a href="25_algorithms/howto.html#2">Special <code>swap</code>s</a></li>
</ul> </ul>
</li>
<li>Numerics (Chapter 26)</li> <li>Numerics (Chapter 26)
<ul> <ul>
<li><a href="26_numerics/howto.html#1">Complex Number Processing</a></li> <li><a href="26_numerics/howto.html#1">Complex Number Processing</a></li>
<li><a href="26_numerics/howto.html#2">Array Processing</a></li> <li><a href="26_numerics/howto.html#2">Array Processing</a></li>
<li><a href="26_numerics/howto.html#3">Numerical Functions</a></li> <li><a href="26_numerics/howto.html#3">Numerical Functions</a></li>
<li><a href="26_numerics/howto.html#4">C99</a></li> <li><a href="26_numerics/howto.html#4">C99</a></li>
</ul> </ul>
</li>
<li>Input/Output (Chapter 27)</li> <li>Input/Output (Chapter 27)
<ul> <ul>
<li><a href="27_io/howto.html#1">Copying a file</a></li> <li><a href="27_io/howto.html#1">Copying a file</a></li>
<li><a href="27_io/howto.html#2">The buffering is screwing up my program!</a></li> <li><a href="27_io/howto.html#2">The buffering is screwing up my program!</a></li>
@ -192,8 +204,9 @@
<li><a href="27_io/howto.html#8">Pathetic performance? Ditch C.</a></li> <li><a href="27_io/howto.html#8">Pathetic performance? Ditch C.</a></li>
<li><a href="27_io/howto.html#9">Threads and I/O</a></li> <li><a href="27_io/howto.html#9">Threads and I/O</a></li>
</ul> </ul>
</li>
<li>Extensions to the Standard Library</li> <li>Extensions to the Standard Library
<ul> <ul>
<li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a></li> <li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a></li>
<li><a href="ext/howto.html#2">Added members and types</a></li> <li><a href="ext/howto.html#2">Added members and types</a></li>
@ -202,27 +215,28 @@
<li><a href="ext/howto.html#4">Compile-time checks</a></li> <li><a href="ext/howto.html#4">Compile-time checks</a></li>
<li><a href="ext/howto.html#5">LWG Issues</a></li> <li><a href="ext/howto.html#5">LWG Issues</a></li>
</ul> </ul>
</li>
</ul> </ul>
<!-- endlist --> <!-- endlist -->
<hr /> <hr />
<br> <br />
<h2><a name="5">Contributor-Specific Information</a></h2> <h2><a name="5">Contributor-Specific Information</a></h2>
<ul> <ul>
<li><a href="17_intro/contribute.html">Contributor checklist</a> <li><a href="17_intro/contribute.html">Contributor checklist</a></li>
<li><a href="17_intro/libstdc++-assign.txt">Copyright assignment form for libstdc++-v3</a> <li><a href="17_intro/libstdc++-assign.txt">Copyright assignment form for libstdc++-v3</a></li>
<li><a href="17_intro/BADNAMES">BADNAMES</a> <li><a href="17_intro/BADNAMES">BADNAMES</a>
- names to avoid because of potential collisions - names to avoid because of potential collisions</li>
<li><a href="17_intro/C++STYLE">C++STYLE</a> <li><a href="17_intro/C++STYLE">C++STYLE</a>
- coding style by example - coding style by example</li>
<li><a href="17_intro/CHECKLIST">CHECKLIST</a> <li><a href="17_intro/CHECKLIST">CHECKLIST</a>
- a list of required features and their status. - a list of required features and their status.</li>
<li><a href="17_intro/DESIGN">DESIGN</a> <li><a href="17_intro/DESIGN">DESIGN</a>
- overview of the implementation plan - overview of the implementation plan</li>
<li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a> <li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a>
- header naming and sub-include structure - header naming and sub-include structure</li>
</ul> </ul>
<!-- ####################################################### --> <!-- ####################################################### -->

22
libstdc++-v3/docs/html/explanations.html
View file

@ -1,12 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3."> <meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>Explanatory notes about libstdc++-v3 design</title> <title>Explanatory notes about libstdc++-v3 design</title>
<link rel="StyleSheet" href="lib3styles.css"> <link rel="StyleSheet" href="lib3styles.css" />
</head> </head>
<body> <body>
@ -19,11 +18,12 @@ design</a></h1>
</p> </p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<a name="cstdio"><h3>&quot;I/O packages&quot;, <code>--enable-cstdio</code></h3></a> <h3><a name="cstdio">&quot;I/O packages&quot;, <code>--enable-cstdio</code></a></h3>
<p>In addition to all the nifty things which C++ can do for I/O, its library <p>In addition to all the nifty things which C++ can do for I/O, its library
also includes all of the I/O capabilites of C. Making them work together also includes all of the I/O capabilites of C. Making them work together
can be a challenge, not only can be a challenge, not only
@ -61,8 +61,8 @@ design</a></h1>
</p> </p>
<hr> <hr />
<a name="alloc"><h3>Internal Allocators</h3></a> <h3><a name="alloc">Internal Allocators</a></h3>
<p> <p>
</p> </p>
<p>Return <a href="#top">to the top of the page</a> or <p>Return <a href="#top">to the top of the page</a> or
@ -72,7 +72,7 @@ design</a></h1>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions. See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

211
libstdc++-v3/docs/html/ext/howto.html
View file

@ -1,13 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes for the libstdc++ extensions."> <meta name="DESCRIPTION" content="Notes for the libstdc++ extensions." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Extensions</title> <title>libstdc++-v3 HOWTO: Extensions</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
</head> </head>
<body> <body>
@ -18,45 +17,46 @@
and some just seemed to appear on the doorstep. and some just seemed to appear on the doorstep.
</p> </p>
<p><strong>Before you leap in and use these</strong>, be aware of two things: <p><strong>Before you leap in and use these</strong>, be aware of two things:
<ol>
<li>Non-Standard means exactly that. 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++-v3 may not recognize these names, or
treat them differently, or...
<li>You should know how to <a href="../faq/index.html#5_4">access
these headers properly</a>.
</ol>
</p> </p>
<ol>
<li>Non-Standard means exactly that. 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++-v3 may not recognize these names, or
treat them differently, or... </li>
<li>You should know how to <a href="../faq/index.html#5_4">access
these headers properly</a>. </li>
</ol>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Contents</h1> <h1>Contents</h1>
<ul> <ul>
<li><a href="#1">Ropes and trees and hashes, oh my!</a> <li><a href="#1">Ropes and trees and hashes, oh my!</a></li>
<li><a href="#2">Added members and types</a> <li><a href="#2">Added members and types</a></li>
<li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a> <li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a></li>
<li><a href="#6">Allocators (version 3.3)</a> <li><a href="#6">Allocators (version 3.3)</a></li>
<li><a href="#4">Compile-time checks</a> <li><a href="#4">Compile-time checks</a></li>
<li><a href="#5">LWG Issues</a> <li><a href="#5">LWG Issues</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
<h2><a name="1">Ropes and trees and hashes, oh my!</a></h2> <h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
<p>The SGI headers <p>The SGI headers</p>
<pre> <pre>
&lt;bvector&gt; &lt;bvector&gt;
&lt;hash_map&gt; &lt;hash_map&gt;
&lt;hash_set&gt; &lt;hash_set&gt;
&lt;rope&gt; &lt;rope&gt;
&lt;slist&gt; &lt;slist&gt;
&lt;tree&gt; &lt;tree&gt;
</pre> are all here; <code>&lt;bvector&gt;</code> exposes the old bit_vector </pre>
<p>are all here; <code>&lt;bvector&gt;</code> exposes the old bit_vector
class that was used before specialization of vector&lt;bool&gt; was class that was used before specialization of vector&lt;bool&gt; was
available (it's actually a typedef for the specialization now). available (it's actually a typedef for the specialization now).
<code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code> <code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
@ -88,25 +88,25 @@
</p> </p>
<p>Why would you want to use a hashing class instead of the <p>Why would you want to use a hashing class instead of the
&quot;normal&quot; implementations? Matt Austern writes: &quot;normal&quot; implementations? Matt Austern writes:
<blockquote><em>[W]ith a well chosen hash function, hash tables
generally provide much better average-case performance than binary
search trees, and much worse worst-case performance. So if your
implementation has hash_map, if you don't mind using nonstandard
components, and if you aren't scared about the possibility of
pathological cases, you'll probably get better performance from
hash_map.</em></blockquote>
</p> </p>
<blockquote><em>[W]ith a well chosen hash function, hash tables
generally provide much better average-case performance than binary
search trees, and much worse worst-case performance. So if your
implementation has hash_map, if you don't mind using nonstandard
components, and if you aren't scared about the possibility of
pathological cases, you'll probably get better performance from
hash_map.</em></blockquote>
<p>(Side note: for those of you wondering, <strong>&quot;Why wasn't a hash <p>(Side note: for those of you wondering, <strong>&quot;Why wasn't a hash
table included in the Standard in the first #!$@ place?&quot;</strong> table included in the Standard in the first #!$@ place?&quot;</strong>
I'll give a quick answer: it was proposed, but too late and in too I'll give a quick answer: it was proposed, but too late and in too
unorganized a fashion. Some sort of hashing will undoubtedly be unorganized a fashion. Some sort of hashing will undoubtedly be
included in a future Standard. included in a future Standard.)
</p> </p>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="2">Added members and types</a></h2> <h2><a name="2">Added members and types</a></h2>
<p>Some of the classes in the Standard Library have additional <p>Some of the classes in the Standard Library have additional
publicly-available members, and some classes are themselves not in publicly-available members, and some classes are themselves not in
@ -114,29 +114,32 @@
for example, additional typedefs. Those won't be described here for example, additional typedefs. Those won't be described here
(or anywhere else). (or anywhere else).
</p> </p>
<p> <ul>
<ul>
<li>The extensions added by SGI are so numerous that they have <li>The extensions added by SGI are so numerous that they have
<a href="sgiexts.html">their own page</a>. Since the SGI STL is no <a href="sgiexts.html">their own page</a>. Since the SGI STL is no
longer actively maintained, we will try and keep this code working longer actively maintained, we will try and keep this code working
ourselves.</li> ourselves.</li>
<li>3.0.x <code>filebuf</code>s have another ctor with this signature:<br> <li>3.0.x <code>filebuf</code>s have another ctor with this signature:
<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code> <br />
<br>This comes in very handy in a number of places, such as <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code>
<br />This comes in very handy in a number of places, such as
attaching Unix sockets, pipes, and anything else which uses file attaching Unix sockets, pipes, and anything else which uses file
descriptors, into the IOStream buffering classes. The three descriptors, into the IOStream buffering classes. The three
arguments are as follows: arguments are as follows:
<ul> <ul>
<li><code>__c_file_type* F </code> <li><code>__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE // the __c_file_type typedef usually boils down to stdio's FILE
</li>
<li><code>ios_base::openmode M </code> <li><code>ios_base::openmode M </code>
// same as all the other uses of openmode // same as all the other uses of openmode
</li>
<li><code>int_type B </code> <li><code>int_type B </code>
// buffer size, defaults to BUFSIZ if not specified // buffer size, defaults to BUFSIZ if not specified
</li>
</ul> </ul>
For those wanting to use file descriptors instead of FILE*'s, I For those wanting to use file descriptors instead of FILE*'s, I
invite you to contemplate the mysteries of C's <code>fdopen()</code>. invite you to contemplate the mysteries of C's <code>fdopen()</code>.
</li> </li>
<li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring <li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
back an old extension: the <code>fd()</code> member function. The back an old extension: the <code>fd()</code> member function. The
integer returned from this function can be used for whatever file integer returned from this function can be used for whatever file
@ -144,31 +147,35 @@
library cannot track what you do on your own with a file descriptor, 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 so if you perform any I/O directly, don't expect the library to be
aware of it. aware of it.
</li>
<li>Beginning with 3.1, the extra <code>filebuf</code> constructor and <li>Beginning with 3.1, the extra <code>filebuf</code> constructor and
the <code>fd()</code> function were removed from the standard the <code>fd()</code> function were removed from the standard
filebuf. Instead, <code>&lt;ext/stdio_filebuf.h&gt;</code> contains filebuf. Instead, <code>&lt;ext/stdio_filebuf.h&gt;</code> contains
a derived class called <code>__gnu_cxx::stdio_filebuf</code>. a derived class called <code>__gnu_cxx::stdio_filebuf</code>.
</ul> </li>
</p> </ul>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="3">Allocators (versions 3.0, 3.1, 3.2)</a></h2> <h2><a name="3">Allocators (versions 3.0, 3.1, 3.2)</a></h2>
<p>Thread-safety, space efficiency, high speed, portability... this is a <p>Thread-safety, space efficiency, high speed, portability... this is a
mess. Where to begin? mess. Where to begin?
</p> </p>
<h3>The Rules</h3> <h3>The Rules</h3>
<p>The C++ standard only gives a few directives in this area: <p>The C++ standard only gives a few directives in this area:
<ul> </p>
<ul>
<li>When you add elements to a container, and the container must allocate <li>When you add elements to a container, and the container must allocate
more memory to hold them, the container makes the request via its more memory to hold them, the container makes the request via its
<code>Allocator</code> template parameter. This includes adding <code>Allocator</code> template parameter. This includes adding
char's to the string class, which acts as a regular STL container char's to the string class, which acts as a regular STL container
in this respect. in this respect.
</li>
<li>The default <code>Allocator</code> of every container-of-T is <li>The default <code>Allocator</code> of every container-of-T is
<code>std::allocator&lt;T&gt;</code>. <code>std::allocator&lt;T&gt;</code>.
</li>
<li>The interface of the <code>allocator&lt;T&gt;</code> class is <li>The interface of the <code>allocator&lt;T&gt;</code> class is
extremely simple. It has about 20 public declarations (nested extremely simple. It has about 20 public declarations (nested
typedefs, member functions, etc), but the two which concern us most typedefs, member functions, etc), but the two which concern us most
@ -180,13 +187,14 @@
The <code>&quot;n&quot;</code> arguments in both those functions is a The <code>&quot;n&quot;</code> arguments in both those functions is a
<em>count</em> of the number of T's to allocate space for, <em>count</em> of the number of T's to allocate space for,
<em>not their total size</em>. <em>not their total size</em>.
</li>
<li>&quot;The storage is obtained by calling <li>&quot;The storage is obtained by calling
<code>::operator new(size_t)</code>, but it is unspecified when or <code>::operator new(size_t)</code>, but it is unspecified when or
how often this function is called. The use of <code>hint</code> how often this function is called. The use of <code>hint</code>
is unspecified, but intended as an aid to locality if an is unspecified, but intended as an aid to locality if an
implementation so desires.&quot; [20.4.1.1]/6 implementation so desires.&quot; [20.4.1.1]/6
</ul> </li>
</p> </ul>
<h3>Problems and Possibilities</h3> <h3>Problems and Possibilities</h3>
<p>The easiest way of fulfilling the requirements is to call operator new <p>The easiest way of fulfilling the requirements is to call operator new
each time a container needs memory, and to call operator delete each each time a container needs memory, and to call operator delete each
@ -235,33 +243,39 @@
information for maintainers and contributors in addition to users. information for maintainers and contributors in addition to users.
</p> </p>
<p>These classes are always available: <p>These classes are always available:
<ul> </p>
<ul>
<li><code>__new_alloc</code> simply wraps <code>::operator new</code> <li><code>__new_alloc</code> simply wraps <code>::operator new</code>
and <code>::operator delete</code>. and <code>::operator delete</code>.
</li>
<li><code>__malloc_alloc_template&lt;int inst&gt;</code> simply wraps <li><code>__malloc_alloc_template&lt;int inst&gt;</code> simply wraps
<code>malloc</code> and <code>free</code>. There is also a hook <code>malloc</code> and <code>free</code>. There is also a hook
for an out-of-memory handler (for new/delete this is taken care of for an out-of-memory handler (for new/delete this is taken care of
elsewhere). The <code>inst</code> parameter is described below. elsewhere). The <code>inst</code> parameter is described below.
This class was called <code>malloc_alloc</code> in earlier versions. This class was called <code>malloc_alloc</code> in earlier versions.
</li>
<li><code>allocator&lt;T&gt;</code> has already been described; it is <li><code>allocator&lt;T&gt;</code> has already been described; it is
The Standard Allocator for instances of T. It uses the internal The Standard Allocator for instances of T. It uses the internal
<code>__alloc</code> typedef (see below) to satisy its requests. <code>__alloc</code> typedef (see below) to satisy its requests.
</li>
<li><code>__simple_alloc&lt;T,A&gt;</code> is a wrapper around another <li><code>__simple_alloc&lt;T,A&gt;</code> is a wrapper around another
allocator, A, which itself is an allocator for instances of T. allocator, A, which itself is an allocator for instances of T.
This is primarily used in an internal &quot;allocator traits&quot; This is primarily used in an internal &quot;allocator traits&quot;
class which helps encapsulate the different styles of allocators. class which helps encapsulate the different styles of allocators.
</li>
<li><code>__debug_alloc&lt;A&gt;</code> is also a wrapper around an <li><code>__debug_alloc&lt;A&gt;</code> is also a wrapper around an
arbitrary allocator A. It passes on slightly increased size arbitrary allocator A. It passes on slightly increased size
requests to A, and uses the extra memory to store size information. requests to A, and uses the extra memory to store size information.
When a pointer is passed to <code>deallocate()</code>, the stored When a pointer is passed to <code>deallocate()</code>, the stored
size is checked, and assert() is used to guarantee they match. size is checked, and assert() is used to guarantee they match.
</li>
<li><code>__allocator&lt;T,A&gt;</code> is an adaptor. Many of these <li><code>__allocator&lt;T,A&gt;</code> is an adaptor. Many of these
allocator classes have a consistent yet non-standard interface. allocator classes have a consistent yet non-standard interface.
Such classes can be changed to a conforming interface with this Such classes can be changed to a conforming interface with this
wrapper: <code>__allocator&lt;T, __alloc&gt;</code> is thus the wrapper: <code>__allocator&lt;T, __alloc&gt;</code> is thus the
same as <code>allocator&lt;T&gt;</code>. same as <code>allocator&lt;T&gt;</code>.
</ul> </li>
</p> </ul>
<p>An internal typedef, <code> __mem_interface </code>, is defined to be <p>An internal typedef, <code> __mem_interface </code>, is defined to be
<code>__new_alloc</code> by default. <code>__new_alloc</code> by default.
</p> </p>
@ -297,15 +311,15 @@
<p>If you've already read <a href="../23_containers/howto.html#3">this <p>If you've already read <a href="../23_containers/howto.html#3">this
advice</a> and decided to define this macro, then the situation changes advice</a> and decided to define this macro, then the situation changes
thusly: thusly:
<ol>
<li><code>__mem_interface</code>, and
<li><code>__alloc</code>, and
<li><code>__single_client_alloc</code> are all typedef'd to
<code>__malloc_alloc_template</code>.
<li><code>__default_alloc_template</code> is no longer available.
At all. Anywhere.
</ol>
</p> </p>
<ol>
<li><code>__mem_interface</code>, and</li>
<li><code>__alloc</code>, and</li>
<li><code>__single_client_alloc</code> are all typedef'd to
<code>__malloc_alloc_template</code>.</li>
<li><code>__default_alloc_template</code> is no longer available.
At all. Anywhere.</li>
</ol>
<h3>Writing your own allocators</h3> <h3>Writing your own allocators</h3>
<p>Depending on your application (a specific program, a generic library, <p>Depending on your application (a specific program, a generic library,
etc), allocator classes tend to be one of two styles: &quot;SGI&quot; etc), allocator classes tend to be one of two styles: &quot;SGI&quot;
@ -326,12 +340,12 @@
(but nonportable) (but nonportable)
method of specifying that only malloc/free should be used instead of method of specifying that only malloc/free should be used instead of
the default node allocator is: the default node allocator is:
<pre> </p>
<pre>
std::list &lt;my_type, std::__malloc_alloc_template&lt;0&gt; &gt; my_malloc_based_list;</pre> std::list &lt;my_type, std::__malloc_alloc_template&lt;0&gt; &gt; my_malloc_based_list;</pre>
Likewise, a debugging form of whichever allocator is currently in use: Likewise, a debugging form of whichever allocator is currently in use:
<pre> <pre>
std::deque &lt;my_type, std::__debug_alloc&lt;std::__alloc&gt; &gt; debug_deque;</pre> std::deque &lt;my_type, std::__debug_alloc&lt;std::__alloc&gt; &gt; debug_deque;</pre>
</p>
<h3><code>inst</code></h3> <h3><code>inst</code></h3>
<p>The <code>__malloc_alloc_template</code> and <p>The <code>__malloc_alloc_template</code> and
<code>__default_alloc_template</code> classes take an integer parameter, <code>__default_alloc_template</code> classes take an integer parameter,
@ -339,11 +353,12 @@
</p> </p>
<p>The point of the number is to allow multiple instantiations of the <p>The point of the number is to allow multiple instantiations of the
classes without changing the semantics at all. All three of classes without changing the semantics at all. All three of
<pre> </p>
<pre>
typedef __default_alloc_template&lt;true,0&gt; normal; typedef __default_alloc_template&lt;true,0&gt; normal;
typedef __default_alloc_template&lt;true,1&gt; private; typedef __default_alloc_template&lt;true,1&gt; private;
typedef __default_alloc_template&lt;true,42&gt; also_private;</pre> typedef __default_alloc_template&lt;true,42&gt; also_private;</pre>
behave exactly the same way. However, the memory pool for each type <p>behave exactly the same way. However, the memory pool for each type
(and remember that different instantiations result in different types) (and remember that different instantiations result in different types)
remains separate. remains separate.
</p> </p>
@ -365,7 +380,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="6">Allocators (version 3.3)</a></h2> <h2><a name="6">Allocators (version 3.3)</a></h2>
<p>Changes are coming... <p>Changes are coming...
</p> </p>
@ -373,7 +388,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="4">Compile-time checks</a></h2> <h2><a name="4">Compile-time checks</a></h2>
<p>Currently libstdc++-v3 uses the concept checkers from the Boost <p>Currently libstdc++-v3 uses the concept checkers from the Boost
library to perform <a href="../19_diagnostics/howto.html#3">optional library to perform <a href="../19_diagnostics/howto.html#3">optional
@ -384,7 +399,7 @@
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
<hr> <hr />
<h2><a name="5">LWG Issues</a></h2> <h2><a name="5">LWG Issues</a></h2>
<p>Everybody's got issues. Even the C++ Standard Library. <p>Everybody's got issues. Even the C++ Standard Library.
</p> </p>
@ -418,134 +433,188 @@
examples of style. Note that we usually do not make changes to the code examples of style. Note that we usually do not make changes to the code
until an issue has reached <a href="lwg-active.html#DR">DR</a> status. until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
</p> </p>
<p><dl> <dl>
<dt><a href="lwg-defects.html#5">5</a>: <dt><a href="lwg-defects.html#5">5</a>:
<em>string::compare specification questionable</em> <em>string::compare specification questionable</em>
</dt>
<dd>This should be two overloaded functions rather than a single function. <dd>This should be two overloaded functions rather than a single function.
</dd>
<dt><a href="lwg-defects.html#17">17</a>: <dt><a href="lwg-defects.html#17">17</a>:
<em>Bad bool parsing</em> <em>Bad bool parsing</em>
</dt>
<dd>Apparently extracting Boolean values was messed up... <dd>Apparently extracting Boolean values was messed up...
</dd>
<dt><a href="lwg-defects.html#22">22</a>: <dt><a href="lwg-defects.html#22">22</a>:
<em>Member open vs flags</em> <em>Member open vs flags</em>
</dt>
<dd>Re-opening a file stream does <em>not</em> clear the state flags. <dd>Re-opening a file stream does <em>not</em> clear the state flags.
</dd>
<dt><a href="lwg-defects.html#25">25</a>: <dt><a href="lwg-defects.html#25">25</a>:
<em>String operator&lt;&lt; uses width() value wrong</em> <em>String operator&lt;&lt; uses width() value wrong</em>
</dt>
<dd>Padding issues. <dd>Padding issues.
</dd>
<dt><a href="lwg-defects.html#48">48</a>: <dt><a href="lwg-defects.html#48">48</a>:
<em>Use of non-existent exception constructor</em> <em>Use of non-existent exception constructor</em>
</dt>
<dd>An instance of <code>ios_base::failure</code> is constructed instead. <dd>An instance of <code>ios_base::failure</code> is constructed instead.
</dd>
<dt><a href="lwg-defects.html#49">49</a>: <dt><a href="lwg-defects.html#49">49</a>:
<em>Underspecification of ios_base::sync_with_stdio</em> <em>Underspecification of ios_base::sync_with_stdio</em>
</dt>
<dd>The return type is the <em>previous</em> state of synchronization. <dd>The return type is the <em>previous</em> state of synchronization.
</dd>
<dt><a href="lwg-defects.html#50">50</a>: <dt><a href="lwg-defects.html#50">50</a>:
<em>Copy constructor and assignment operator of ios_base</em> <em>Copy constructor and assignment operator of ios_base</em>
</dt>
<dd>These members functions are declared <code>private</code> and are <dd>These members functions are declared <code>private</code> and are
thus inaccessible. Specifying the correct semantics of thus inaccessible. Specifying the correct semantics of
&quot;copying stream state&quot; was deemed too complicated. &quot;copying stream state&quot; was deemed too complicated.
</dd>
<dt><a href="lwg-defects.html#68">68</a>: <dt><a href="lwg-defects.html#68">68</a>:
<em>Extractors for char* should store null at end</em> <em>Extractors for char* should store null at end</em>
</dt>
<dd>And they do now. An editing glitch in the last item in the list of <dd>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.
</dd>
<dt><a href="lwg-defects.html#74">74</a>: <dt><a href="lwg-defects.html#74">74</a>:
<em>Garbled text for codecvt::do_max_length</em> <em>Garbled text for codecvt::do_max_length</em>
</dt>
<dd>The text of the standard was gibberish. Typos gone rampant. <dd>The text of the standard was gibberish. Typos gone rampant.
</dd>
<dt><a href="lwg-defects.html#83">83</a>: <dt><a href="lwg-defects.html#83">83</a>:
<em>string::npos vs. string::max_size()</em> <em>string::npos vs. string::max_size()</em>
</dt>
<dd>Safety checks on the size of the string should test against <dd>Safety checks on the size of the string should test against
<code>max_size()</code> rather than <code>npos</code>. <code>max_size()</code> rather than <code>npos</code>.
</dd>
<dt><a href="lwg-defects.html#109">109</a>: <dt><a href="lwg-defects.html#109">109</a>:
<em>Missing binders for non-const sequence elements</em> <em>Missing binders for non-const sequence elements</em>
</dt>
<dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
<code>operator()</code> taking a non-const parameter. <code>operator()</code> taking a non-const parameter.
</dd>
<dt><a href="lwg-defects.html#110">110</a>: <dt><a href="lwg-defects.html#110">110</a>:
<em>istreambuf_iterator::equal not const</em> <em>istreambuf_iterator::equal not const</em>
</dt>
<dd>This was not a const member function. Note that the DR says to <dd>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 replace the function with a const one; we have instead provided an
overloaded version with identical contents. overloaded version with identical contents.
</dd>
<dt><a href="lwg-defects.html#117">117</a>: <dt><a href="lwg-defects.html#117">117</a>:
<em>basic_ostream uses nonexistent num_put member functions</em> <em>basic_ostream uses nonexistent num_put member functions</em>
</dt>
<dd><code>num_put::put()</code> was overloaded on the wrong types. <dd><code>num_put::put()</code> was overloaded on the wrong types.
</dd>
<dt><a href="lwg-defects.html#118">118</a>: <dt><a href="lwg-defects.html#118">118</a>:
<em>basic_istream uses nonexistent num_get member functions</em> <em>basic_istream uses nonexistent num_get member functions</em>
</dt>
<dd>Same as 117, but for <code>num_get::get()</code>. <dd>Same as 117, but for <code>num_get::get()</code>.
</dd>
<dt><a href="lwg-defects.html#129">129</a>: <dt><a href="lwg-defects.html#129">129</a>:
<em>Need error indication from seekp() and seekg()</em> <em>Need error indication from seekp() and seekg()</em>
</dt>
<dd>These functions set <code>failbit</code> on error now. <dd>These functions set <code>failbit</code> on error now.
</dd>
<dt><a href="lwg-defects.html#136">136</a>: <dt><a href="lwg-defects.html#136">136</a>:
<em>seekp, seekg setting wrong streams?</em> <em>seekp, seekg setting wrong streams?</em>
</dt>
<dd><code>seekp</code> should only set the output stream, and <dd><code>seekp</code> should only set the output stream, and
<code>seekg</code> should only set the input stream. <code>seekg</code> should only set the input stream.
</dd>
<!--<dt><a href="lwg-defects.html#159">159</a>: <!--<dt><a href="lwg-defects.html#159">159</a>:
<em>Strange use of underflow()</em> <em>Strange use of underflow()</em>
</dt>
<dd>In fstream.tcc, the basic_filebuf&lt;&gt;::showmanyc() function <dd>In fstream.tcc, the basic_filebuf&lt;&gt;::showmanyc() function
should probably not be calling <code>underflow()</code>.--> should probably not be calling <code>underflow()</code>.
</dd> -->
<dt><a href="lwg-active.html#167">167</a>: <dt><a href="lwg-active.html#167">167</a>:
<em>Improper use of traits_type::length()</em> <em>Improper use of traits_type::length()</em>
</dt>
<dd><code>op&lt;&lt;</code> with a <code>const char*</code> was <dd><code>op&lt;&lt;</code> with a <code>const char*</code> was
calculating an incorrect number of characters to write. calculating an incorrect number of characters to write.
</dd>
<dt><a href="lwg-defects.html#181">181</a>: <dt><a href="lwg-defects.html#181">181</a>:
<em>make_pair() unintended behavior</em> <em>make_pair() unintended behavior</em>
</dt>
<dd>This function used to take its arguments as reference-to-const, now <dd>This function used to take its arguments as reference-to-const, now
it copies them (pass by value). it copies them (pass by value).
</dd>
<dt><a href="lwg-defects.html#195">195</a>: <dt><a href="lwg-defects.html#195">195</a>:
<em>Should basic_istream::sentry's constructor ever set eofbit?</em> <em>Should basic_istream::sentry's constructor ever set eofbit?</em>
</dt>
<dd>Yes, it can, specifically if EOF is reached while skipping whitespace. <dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
</dd>
<dt><a href="lwg-defects.html#211">211</a>: <dt><a href="lwg-defects.html#211">211</a>:
<em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em> <em>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</em>
</dt>
<dd>If nothing is extracted into the string, <code>op&gt;&gt;</code> now <dd>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
sets <code>failbit</code> (which can cause an exception, etc, etc). sets <code>failbit</code> (which can cause an exception, etc, etc).
</dd>
<dt><a href="lwg-defects.html#214">214</a>: <dt><a href="lwg-defects.html#214">214</a>:
<em>set::find() missing const overload</em> <em>set::find() missing const overload</em>
</dt>
<dd>Both <code>set</code> and <code>multiset</code> were missing <dd>Both <code>set</code> and <code>multiset</code> were missing
overloaded find, lower_bound, upper_bound, and equal_range functions overloaded find, lower_bound, upper_bound, and equal_range functions
for const instances. for const instances.
</dd>
<dt><a href="lwg-defects.html#251">251</a>: <dt><a href="lwg-defects.html#251">251</a>:
<em>basic_stringbuf missing allocator_type</em> <em>basic_stringbuf missing allocator_type</em>
</dt>
<dd>This nested typdef was originally not specified. <dd>This nested typdef was originally not specified.
</dd>
<dt><a href="lwg-defects.html#265">265</a>: <dt><a href="lwg-defects.html#265">265</a>:
<em>std::pair::pair() effects overly restrictive</em> <em>std::pair::pair() effects overly restrictive</em>
</dt>
<dd>The default ctor would build its members from copies of temporaries; <dd>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.
</dd>
<dt><a href="lwg-defects.html#266">266</a>: <dt><a href="lwg-defects.html#266">266</a>:
<em>bad_exception::~bad_exception() missing Effects clause</em> <em>bad_exception::~bad_exception() missing Effects clause</em>
</dt>
<dd>The <code>bad_</code>* classes no longer have destructors (they <dd>The <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.
</dd>
<dt><a href="lwg-defects.html#275">275</a>: <dt><a href="lwg-defects.html#275">275</a>:
<em>Wrong type in num_get::get() overloads</em> <em>Wrong type in num_get::get() overloads</em>
</dt>
<dd>Similar to 118. <dd>Similar to 118.
</dd>
<!-- <!--
<dt><a href="lwg-defects.html#"></a>: <dt><a href="lwg-defects.html#"></a>:
<em></em> <em></em>
</dt>
<dd> <dd>
</dd>
--> -->
</dl></p> </dl>
<p>Return <a href="#top">to top of page</a> or <p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>. <a href="../faq/index.html">to the FAQ</a>.
</p> </p>
@ -553,7 +622,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

112
libstdc++-v3/docs/html/ext/sgiexts.html
View file

@ -1,12 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI"> <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI" />
<meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3."> <meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>SGI extensions to the library in libstdc++-v3</title> <title>SGI extensions to the library in libstdc++-v3</title>
<link rel="StyleSheet" href="lib3styles.css"> <link rel="StyleSheet" href="lib3styles.css" />
</head> </head>
<body> <body>
@ -25,7 +24,7 @@ libstdc++-v3</a></h1>
for a description). Not every chapter may have extensions, and the for a description). Not every chapter may have extensions, and the
extensions may come and go. Also, this page is incomplete because the extensions may come and go. Also, this page is incomplete because the
author is pressed for time. Check back often; the latest change was on author is pressed for time. Check back often; the latest change was on
$Date: 2001/11/23 16:29:01 $ (UTC). $Date: 2001/11/28 00:02:04 $ (UTC).
</p> </p>
<p>Descriptions range from the scanty to the verbose. You should also check <p>Descriptions range from the scanty to the verbose. You should also check
@ -36,30 +35,33 @@ libstdc++-v3</a></h1>
</p> </p>
<p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>. <p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<a name="ch20"><h3>Chapter 20</h3></a> <h3><a name="ch20">Chapter 20</a></h3>
<p>The &lt;functional&gt; header contains many additional functors and <p>The &lt;functional&gt; header contains many additional functors and
helper functions, extending section 20.3. They are implemented in the helper functions, extending section 20.3. They are implemented in the
file stl_function.h: file stl_function.h:
<ul> </p>
<li><code>identity_element</code> for addition and multiplication. * <ul>
<li>The functor <code>identity</code>, whose op() returns the argument <li><code>identity_element</code> for addition and multiplication. * </li>
unchanged. * <li>The functor <code>identity</code>, whose <code>operator()</code>
returns the argument unchanged. * </li>
<li>Composition functors <code>unary_function</code> and <li>Composition functors <code>unary_function</code> and
<code>binary_function</code>, and their helpers <code>compose1</code> <code>binary_function</code>, and their helpers <code>compose1</code>
and <code>compose2</code>. * and <code>compose2</code>. * </li>
<li><code>select1st</code> and <code>select2nd</code>, to strip pairs. * <li><code>select1st</code> and <code>select2nd</code>, to strip pairs. * </li>
<li><code>project1st</code> and <code>project2nd</code>. * <li><code>project1st</code> and <code>project2nd</code>. * </li>
<li>A set of functors/functions which always return the same result. They <li>A set of functors/functions which always return the same result. They
are <code>constant_void_fun, constant_binary_fun, constant_unary_fun, are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
constant0, constant1, and constant2. * <code>constant_unary_fun</code>, <code>constant0</code>,
<li>The class <code>subtractive_rng</code>. * <code>constant1</code>, and <code>constant2</code>. * </li>
<li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for <li>The class <code>subtractive_rng</code>. * </li>
backwards compatibility. <li>mem_fun adaptor helpers <code>mem_fun1</code> and
</ul></p> <code>mem_fun1_ref</code> are provided for backwards compatibility. </li>
</ul>
<p>20.4.1 can use several different allocators; they are described on the <p>20.4.1 can use several different allocators; they are described on the
main extensions page. main extensions page.
</p> </p>
@ -68,12 +70,12 @@ libstdc++-v3</a></h1>
is a pointer, which is ignored, but can be used to specify the template is a pointer, which is ignored, but can be used to specify the template
type (instead of using explicit function template arguments like the type (instead of using explicit function template arguments like the
standard version does). That is, in addition to standard version does). That is, in addition to
</p>
<pre> <pre>
get_temporary_buffer&lt;int&gt;(5);</pre> get_temporary_buffer&lt;int&gt;(5);</pre>
you can also use you can also use
<pre> <pre>
get_temporary_buffer(5, (int*)0);</pre> get_temporary_buffer(5, (int*)0);</pre>
</p>
<p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. * <p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
</p> </p>
<p>The specialized algorithms of section 20.4.4 are extended with <p>The specialized algorithms of section 20.4.4 are extended with
@ -84,8 +86,8 @@ libstdc++-v3</a></h1>
</p> </p>
<hr> <hr />
<a name="ch23"><h3>Chapter 23</h3></a> <h3><a name="ch23">Chapter 23</a></h3>
<p>A few extensions and nods to backwards-compatibility have been made with <p>A few extensions and nods to backwards-compatibility have been made with
containers. Those dealing with older SGI-style allocators are dealt with containers. Those dealing with older SGI-style allocators are dealt with
elsewhere. The remaining ones all deal with bits: elsewhere. The remaining ones all deal with bits:
@ -105,18 +107,18 @@ libstdc++-v3</a></h1>
versions of single-bit test, set, reset, and flip member functions which versions of single-bit test, set, reset, and flip member functions which
do no range-checking. If we call them member functions of an instantiation do no range-checking. If we call them member functions of an instantiation
of &quot;bitset&lt;N&gt;,&quot; then their names and signatures are: of &quot;bitset&lt;N&gt;,&quot; then their names and signatures are:
</p>
<pre> <pre>
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos); bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos, int val); bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos, int val);
bitset&lt;N&gt;&amp; _Unchecked_reset (size_t pos); bitset&lt;N&gt;&amp; _Unchecked_reset (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_flip (size_t pos); bitset&lt;N&gt;&amp; _Unchecked_flip (size_t pos);
bool _Unchecked_test (size_t pos);</pre> bool _Unchecked_test (size_t pos);</pre>
Note that these may in fact be removed in the future, although we have <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 no present plans to do so (and there doesn't seem to be any immediate
reason to). reason to).
</p> </p>
<p> <p>The semantics of member function <code>operator[]</code> are not specified
The semantics of member function <code>operator[]</code> are not specified
in the C++ standard. A long-standing defect report calls for sensible in the C++ standard. A long-standing defect report calls for sensible
obvious semantics, which are already implemented here: <code>op[]</code> obvious semantics, which are already implemented here: <code>op[]</code>
on a const bitset returns a bool, and for a non-const bitset returns a on a const bitset returns a bool, and for a non-const bitset returns a
@ -128,30 +130,31 @@ libstdc++-v3</a></h1>
<p>Finally, two additional searching functions have been added. They return <p>Finally, two additional searching functions have been added. They return
the index of the first &quot;on&quot; bit, and the index of the first the index of the first &quot;on&quot; bit, and the index of the first
&quot;on&quot; bit that is after <code>prev</code>, respectively: &quot;on&quot; bit that is after <code>prev</code>, respectively:
</p>
<pre> <pre>
size_t _Find_first() const; size_t _Find_first() const;
size_t _Find_next (size_t prev) const;</pre> size_t _Find_next (size_t prev) const;</pre>
The same caveat given for the _Unchecked_* functions applies here also. <p>The same caveat given for the _Unchecked_* functions applies here also.
</p> </p>
<p>Return <a href="howto.html">to the main extensions page</a> or <p>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p> </p>
<hr> <hr />
<a name="ch24"><h3>Chapter 24</h3></a> <h3><a name="ch24">Chapter 24</a></h3>
<p>24.3.2 describes <code>struct iterator</code>, which didn't exist in the <p>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
original HP STL implementation (the language wasn't rich enough at the original HP STL implementation (the language wasn't rich enough at the
time). For backwards compatibility, base classes are provided which time). For backwards compatibility, base classes are provided which
declare the same nested typedefs: declare the same nested typedefs:
<ul>
<li>input_iterator
<li>output_iterator
<li>forward_iterator
<li>bidirectional_iterator
<li>random_access_iterator
</ul>
</p> </p>
<ul>
<li>input_iterator</li>
<li>output_iterator</li>
<li>forward_iterator</li>
<li>bidirectional_iterator</li>
<li>random_access_iterator</li>
</ul>
<p>24.3.4 describes iterator operation <code>distance</code>, which takes <p>24.3.4 describes iterator operation <code>distance</code>, which takes
two iterators and returns a result. It is extended by another signature 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 which takes two iterators and a reference to a result. The result is
@ -162,50 +165,53 @@ libstdc++-v3</a></h1>
</p> </p>
<hr> <hr />
<a name="ch25"><h3>Chapter 25</h3></a> <h3><a name="ch25">Chapter 25</a></h3>
<p>25.1.6 (count, count_if) is extended with two more versions of count <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 and count_if. The standard versions return their results. The
additional signatures return void, but take a final parameter by additional signatures return void, but take a final parameter by
reference to which they assign their results, e.g., reference to which they assign their results, e.g.,
</p>
<pre> <pre>
void count (first, last, value, n);</pre> void count (first, last, value, n);</pre>
</p>
<p>25.2 (mutating algorithms) is extended with two families of signatures, <p>25.2 (mutating algorithms) is extended with two families of signatures,
random_sample and random_sample_n. random_sample and random_sample_n.
</p> </p>
<p>25.2.1 (copy) is extended with <p>25.2.1 (copy) is extended with
</p>
<pre> <pre>
copy_n (_InputIter first, _Size count, _OutputIter result);</pre> copy_n (_InputIter first, _Size count, _OutputIter result);</pre>
which copies the first 'count' elements at 'first' into 'result'. <p>which copies the first 'count' elements at 'first' into 'result'.
</p> </p>
<p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper <p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
predicates. Look in the doxygen-generated pages for notes on these. predicates. Look in the doxygen-generated pages for notes on these.
<ul>
<li><code>is_heap</code> tests whether or not a range is a heap.
<li><code>is_sorted</code> tests whether or not a range is sorted in
nondescending order.
</ul>
</p> </p>
<ul>
<li><code>is_heap</code> tests whether or not a range is a heap.</li>
<li><code>is_sorted</code> tests whether or not a range is sorted in
nondescending order.</li>
</ul>
<p>25.3.8 (lexigraphical_compare) is extended with <p>25.3.8 (lexigraphical_compare) is extended with
</p>
<pre> <pre>
lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
_InputIter2 first2, _InputIter2 last2)</pre> _InputIter2 first2, _InputIter2 last2)</pre>
which does... what? <p>which does... what?
</p> </p>
<p>Return <a href="howto.html">to the main extensions page</a> or <p>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p> </p>
<hr> <hr />
<a name="ch26"><h3>Chapter 26</h3></a> <h3><a name="ch26">Chapter 26</a></h3>
<p>26.4, the generalized numeric operations such as accumulate, are extended <p>26.4, the generalized numeric operations such as accumulate, are extended
with the following functions: with the following functions:
</p>
<pre> <pre>
power (x, n); power (x, n);
power (x, n, moniod_operation);</pre> power (x, n, moniod_operation);</pre>
Returns, in FORTRAN syntax, &quot;x ** n&quot; where n&gt;=0. In the <p>Returns, in FORTRAN syntax, &quot;x ** n&quot; where n&gt;=0. In the
case of n == 0, returns the <a href="#ch20">identity element</a> for the case of n == 0, returns the <a href="#ch20">identity element</a> for the
monoid operation. The two-argument signature uses multiplication (for monoid operation. The two-argument signature uses multiplication (for
a true &quot;power&quot; implementation), but addition is supported as well. a true &quot;power&quot; implementation), but addition is supported as well.
@ -215,9 +221,9 @@ libstdc++-v3</a></h1>
Coolest Name. It &quot;assigns sequentially increasing values to a range. Coolest Name. It &quot;assigns sequentially increasing values to a range.
That is, it assigns value to *first, value + 1 to *(first + 1) and so That is, it assigns value to *first, value + 1 to *(first + 1) and so
on.&quot; Quoted from SGI documentation. on.&quot; Quoted from SGI documentation.
</p>
<pre> <pre>
void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre> void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre>
</p>
<p>Return <a href="howto.html">to the main extensions page</a> or <p>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p> </p>
@ -225,7 +231,7 @@ libstdc++-v3</a></h1>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

377
libstdc++-v3/docs/html/faq/index.html
View file

@ -1,10 +1,10 @@
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, libg++, STL"> <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="FAQ for the GNU libstdc++ effort."> <meta name="DESCRIPTION" content="FAQ for the GNU libstdc++ effort." />
<title>libstdc++-v3 FAQ</title> <title>libstdc++-v3 FAQ</title>
<link rel="StyleSheet" href="../lib3styles.css"> <link rel="StyleSheet" href="../lib3styles.css" />
<!-- <!--
** Locations of "the most recent snapshot is the Nth" text are ** Locations of "the most recent snapshot is the Nth" text are
** answers 1_1, 1_4, 4_1. ** answers 1_1, 1_4, 4_1.
@ -23,84 +23,92 @@
</p> </p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h1>Questions</h1> <h1>Questions</h1>
<ol> <ol>
<li><a href="#1_0">General Information</a> <li><a href="#1_0">General Information</a>
<!-- I suspect these will mostly be links to/into existing documents. --> <!-- I suspect these will mostly be links to/into existing documents. -->
<ol> <ol>
<li><a href="#1_1">What is libstdc++-v3?</a> <li><a href="#1_1">What is libstdc++-v3?</a> </li>
<li><a href="#1_2">Why should I use libstdc++?</a> <li><a href="#1_2">Why should I use libstdc++?</a> </li>
<li><a href="#1_3">Who's in charge of it?</a> <li><a href="#1_3">Who's in charge of it?</a> </li>
<li><a href="#1_4">How do I get libstdc++?</a> <li><a href="#1_4">How do I get libstdc++?</a> </li>
<li><a href="#1_5">When is libstdc++ going to be finished?</a> <li><a href="#1_5">When is libstdc++ going to be finished?</a> </li>
<li><a href="#1_6">How do I contribute to the effort?</a> <li><a href="#1_6">How do I contribute to the effort?</a> </li>
<li><a href="#1_7">What happened to libg++? I need that!</a> <li><a href="#1_7">What happened to libg++? I need that!</a> </li>
<li><a href="#1_8">What if I have more questions?</a> <li><a href="#1_8">What if I have more questions?</a> </li>
<li><a href="#1_9">What are the license terms for libstdc++-v3?</a> <li><a href="#1_9">What are the license terms for libstdc++-v3?</a> </li>
</ol> </ol>
</li>
<li><a href="#2_0">Installation</a> <li><a href="#2_0">Installation</a>
<ol> <ol>
<li><a href="#2_1">How do I install libstdc++-v3?</a> <li><a href="#2_1">How do I install libstdc++-v3?</a> </li>
<li><a href="#2_2">[removed]</a> <li><a href="#2_2">[removed]</a> </li>
<li><a href="#2_3">What is this CVS thing that you keep <li><a href="#2_3">What is this CVS thing that you keep
mentioning?</a> mentioning?</a> </li>
<li><a href="#2_4">How do I know if it works?</a> <li><a href="#2_4">How do I know if it works?</a> </li>
<li><a href="#2_5">This library is HUGE! And what's libsupc++?</a> <li><a href="#2_5">This library is HUGE! And what's libsupc++?</a> </li>
</ol> </ol>
</li>
<li><a href="#3_0">Platform-Specific Issues</a> <li><a href="#3_0">Platform-Specific Issues</a>
<ol> <ol>
<li><a href="#3_1">Can libstdc++-v3 be used with &lt;my <li><a href="#3_1">Can libstdc++-v3 be used with &lt;my
favorite compiler&gt;?</a> favorite compiler&gt;?</a> </li>
<li><a href="#3_2">[removed]</a> <li><a href="#3_2">[removed]</a> </li>
<li><a href="#3_3">[removed]</a> <li><a href="#3_3">[removed]</a> </li>
<li><a href="#3_4">I can't use 'long long' on Solaris</a> <li><a href="#3_4">I can't use 'long long' on Solaris</a> </li>
<li><a href="#3_5"><code>_XOPEN_SOURCE</code> / <li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
<code>_GNU_SOURCE</code> / etc is always defined</a> <code>_GNU_SOURCE</code> / etc is always defined</a>
<li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a> </li>
<li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a> </li>
</ol> </ol>
</li>
<li><a href="#4_0">Known Bugs and Non-Bugs</a> <li><a href="#4_0">Known Bugs and Non-Bugs</a>
<ol> <ol>
<li><a href="#4_1">What works already?</a> <li><a href="#4_1">What works already?</a> </li>
<li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> <li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> </li>
<li><a href="#4_3">Bugs in the C++ language/lib specification</a> <li><a href="#4_3">Bugs in the C++ language/lib specification</a> </li>
<li><a href="#4_4">Things in libstdc++ that only look like bugs</a><ul> <li><a href="#4_4">Things in libstdc++ that only look like bugs</a><ul>
<li><a href="#4_4_iostreamclear">reopening a stream fails</a> <li><a href="#4_4_iostreamclear">reopening a stream fails</a> </li>
<li><a href="#4_4_Weff">-Weffc++ complains too much</a> <li><a href="#4_4_Weff">-Weffc++ complains too much</a> </li>
<li><a href="#4_4_rel_ops">&quot;ambiguous overloads&quot; <li><a href="#4_4_rel_ops">&quot;ambiguous overloads&quot;
after including an old-style header</a> after including an old-style header</a> </li>
<li><a href="#4_4_interface">The g++-3 headers are <li><a href="#4_4_interface">The g++-3 headers are
<strong>not ours</strong></a> <strong>not ours</strong></a> </li>
<li><a href="#4_4_glibc">compilation errors from streambuf.h</a> <li><a href="#4_4_glibc">compilation errors from streambuf.h</a> </li>
<li><a href="#4_4_checks">errors about <em>*Concept</em> and <li><a href="#4_4_checks">errors about <em>*Concept</em> and
<em>constraints</em> in the STL...</a> <em>constraints</em> in the STL...</a> </li>
<li><a href="#4_4_dlsym">program crashes when using library code <li><a href="#4_4_dlsym">program crashes when using library code
in a dynamically-loaded library</a> in a dynamically-loaded library</a> </li>
</ul> </ul>
<li><a href="#4_5">Aw, that's easy to fix!</a> </li>
<li><a href="#4_5">Aw, that's easy to fix!</a> </li>
</ol> </ol>
</li>
<li><a href="#5_0">Miscellaneous</a> <li><a href="#5_0">Miscellaneous</a>
<ol> <ol>
<li><a href="#5_1">string::iterator is not char*; <li><a href="#5_1">string::iterator is not char*;
vector&lt;T&gt;::iterator is not T*</a> vector&lt;T&gt;::iterator is not T*</a> </li>
<li><a href="#5_2">What's next after libstdc++-v3?</a> <li><a href="#5_2">What's next after libstdc++-v3?</a> </li>
<li><a href="#5_3">What about the STL from SGI?</a> <li><a href="#5_3">What about the STL from SGI?</a> </li>
<li><a href="#5_4">Extensions and Backward Compatibility</a> <li><a href="#5_4">Extensions and Backward Compatibility</a> </li>
<li><a href="#5_5">[removed]</a> <li><a href="#5_5">[removed]</a> </li>
<li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> </li>
<li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> </li>
<li><a href="#5_8">What's an ABI and why is it so messy?</a> <li><a href="#5_8">What's an ABI and why is it so messy?</a> </li>
</ol> </ol>
</li>
</ol> </ol>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -127,7 +135,7 @@
official <a href="../17_intro/DESIGN">design document</a>. official <a href="../17_intro/DESIGN">design document</a>.
</p> </p>
<hr> <hr />
<h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2> <h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2>
<p>The completion of the ISO C++ standardization gave the <p>The completion of the ISO C++ standardization gave the
C++ community a powerful set of reuseable tools in the form C++ community a powerful set of reuseable tools in the form
@ -153,7 +161,7 @@
nor be worried about platform-specific incompatibilities. nor be worried about platform-specific incompatibilities.
</p> </p>
<hr> <hr />
<h2><a name="1_3">1.3 Who's in charge of it?</a></h2> <h2><a name="1_3">1.3 Who's in charge of it?</a></h2>
<p>The libstdc++ project is contributed to by several developers <p>The libstdc++ project is contributed to by several developers
all over the world, in the same way as GCC or Linux. all over the world, in the same way as GCC or Linux.
@ -168,7 +176,7 @@
If you have questions, ideas, code, or are just curious, sign up! If you have questions, ideas, code, or are just curious, sign up!
</p> </p>
<hr> <hr />
<h2><a name="1_4">1.4 How do I get libstdc++?</a></h2> <h2><a name="1_4">1.4 How do I get libstdc++?</a></h2>
<p>The fourteenth (and latest) snapshot of libstdc++-v3 is <p>The fourteenth (and latest) snapshot of libstdc++-v3 is
<a href="http://gcc.gnu.org/libstdc++/index.html#download">available <a href="http://gcc.gnu.org/libstdc++/index.html#download">available
@ -183,9 +191,9 @@
of the SGI STL. of the SGI STL.
</p> </p>
<hr> <hr />
<h2><a name="1_5">1.5 When is libstdc++ going to be finished?</a></h2> <h2><a name="1_5">1.5 When is libstdc++ going to be finished?</a></h2>
<!-- <p>Nathan Myers gave the best of all possible answers in <A <!-- <p>Nathan Myers gave the best of all possible answers in <a
href="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text">a href="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text">a
Usenet article</a>.</p> Usenet article</a>.</p>
which is no longer available, thanks deja...--> which is no longer available, thanks deja...-->
@ -193,7 +201,7 @@ which is no longer available, thanks deja...-->
Usenet article asking this question: <em>Sooner, if you help.</em> Usenet article asking this question: <em>Sooner, if you help.</em>
</p> </p>
<hr> <hr />
<h2><a name="1_6">1.6 How do I contribute to the effort?</a></h2> <h2><a name="1_6">1.6 How do I contribute to the effort?</a></h2>
<p>Here is <a href="../17_intro/contribute.html">a <p>Here is <a href="../17_intro/contribute.html">a
page devoted to this topic</a>. Subscribing to the mailing page devoted to this topic</a>. Subscribing to the mailing
@ -205,7 +213,7 @@ which is no longer available, thanks deja...-->
we all thought was working, is more than welcome! we all thought was working, is more than welcome!
</p> </p>
<hr> <hr />
<h2><a name="1_7">1.7 What happened to libg++? I need that!</a></h2> <h2><a name="1_7">1.7 What happened to libg++? I need that!</a></h2>
<p>The most recent libg++ README states that libg++ is no longer <p>The most recent libg++ README states that libg++ is no longer
being actively maintained. It should not be used for new being actively maintained. It should not be used for new
@ -244,7 +252,7 @@ which is no longer available, thanks deja...-->
describes where to find the last libg++ source. describes where to find the last libg++ source.
</p> </p>
<hr> <hr />
<h2><a name="1_8">1.8 What if I have more questions?</a></h2> <h2><a name="1_8">1.8 What if I have more questions?</a></h2>
<p>If you have read the README and RELEASE-NOTES files, and your <p>If you have read the README and RELEASE-NOTES files, and your
question remains unanswered, then just ask the mailing list. question remains unanswered, then just ask the mailing list.
@ -260,13 +268,13 @@ which is no longer available, thanks deja...-->
or <a href="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</a>. or <a href="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</a>.
</p> </p>
<hr> <hr />
<h2><a name="1_9">1.9 What are the license terms for libstdc++-v3?</a></h2> <h2><a name="1_9">1.9 What are the license terms for libstdc++-v3?</a></h2>
<p>See <a href="../17_intro/license.html">our license description</a> <p>See <a href="../17_intro/license.html">our license description</a>
for these and related questions. for these and related questions.
</p> </p>
<hr> <hr />
<h1><a name="2_0">2.0 Installation</a></h1> <h1><a name="2_0">2.0 Installation</a></h1>
<h2><a name="2_1">2.1 How do I install libstdc++-v3?</a></h2> <h2><a name="2_1">2.1 How do I install libstdc++-v3?</a></h2>
<p>Complete instructions are not given here (this is a FAQ, not <p>Complete instructions are not given here (this is a FAQ, not
@ -277,9 +285,12 @@ which is no longer available, thanks deja...-->
easier and more automated than building the GCC 2.[78] easier and more automated than building the GCC 2.[78]
series was. If you are using GCC 2.95, you can still series was. If you are using GCC 2.95, you can still
build earlier snapshots of libstdc++. build earlier snapshots of libstdc++.
</li>
<li> GNU Make is recommended, but should not be required. <li> GNU Make is recommended, but should not be required.
</li>
<li> The GNU Autotools are needed if you are messing with <li> The GNU Autotools are needed if you are messing with
the configury or makefiles. the configury or makefiles.
</li>
</ul> </ul>
<p>The file <a href="../documentation.html">documentation.html</a> <p>The file <a href="../documentation.html">documentation.html</a>
provides a good overview of the steps necessary to build, install, provides a good overview of the steps necessary to build, install,
@ -295,18 +306,18 @@ which is no longer available, thanks deja...-->
&quot;.../docs/17_intro/&quot; directory of the distribution. &quot;.../docs/17_intro/&quot; directory of the distribution.
</p> </p>
<hr> <hr />
<h2><a name="2_2">2.2 [removed]</a></h2> <h2><a name="2_2">2.2 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub <p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks). is here to preserve numbering (and hence links/bookmarks).
</p> </p>
<hr> <hr />
<h2><a name="2_3">2.3 What is this CVS thing that you <h2><a name="2_3">2.3 What is this CVS thing that you
keep mentioning?</a></h2> keep mentioning?</a></h2>
<p>The <em>Concurrent Versions System</em> is one of several revision <p>The <em>Concurrent Versions System</em> is one of several revision
control packages. It was selected for GNU projects because it's control packages. It was selected for GNU projects because it's
free (speech), free (beer), and very high quality. The <A free (speech), free (beer), and very high quality. The <a
href="http://www.gnu.org/software/cvs/cvs.html">CVS entry in href="http://www.gnu.org/software/cvs/cvs.html">CVS entry in
the GNU software catalogue</a> has a better description as the GNU software catalogue</a> has a better description as
well as a well as a
@ -321,7 +332,7 @@ which is no longer available, thanks deja...-->
<!-- wonder how long that'll live --> <!-- wonder how long that'll live -->
</p> </p>
<hr> <hr />
<h2><a name="2_4">2.4 How do I know if it works?</a></h2> <h2><a name="2_4">2.4 How do I know if it works?</a></h2>
<p>libstdc++-v3 comes with its own testsuite. You do not need <p>libstdc++-v3 comes with its own testsuite. You do not need
to actually install the library (&quot;<code>make to actually install the library (&quot;<code>make
@ -337,7 +348,7 @@ which is no longer available, thanks deja...-->
<strong>please</strong> write up your idea and send it to the list! <strong>please</strong> write up your idea and send it to the list!
</p> </p>
<hr> <hr />
<h2><a name="2_5">2.4 This library is HUGE! And what's libsupc++?</a></h2> <h2><a name="2_5">2.4 This library is HUGE! And what's libsupc++?</a></h2>
<p>Usually the size of libraries on disk isn't noticeable. When a <p>Usually the size of libraries on disk isn't noticeable. When a
link editor (or simply &quot;linker&quot;) pulls things from a link editor (or simply &quot;linker&quot;) pulls things from a
@ -387,7 +398,7 @@ which is no longer available, thanks deja...-->
when building the library. when building the library.
</p> </p>
<hr> <hr />
<h1><a name="3_0">3.0 Platform-Specific Issues</a></h1> <h1><a name="3_0">3.0 Platform-Specific Issues</a></h1>
<h2><a name="3_1">3.1 Can libstdc++-v3 be used with &lt;my <h2><a name="3_1">3.1 Can libstdc++-v3 be used with &lt;my
favorite compiler&gt;?</a></h2> favorite compiler&gt;?</a></h2>
@ -409,19 +420,19 @@ which is no longer available, thanks deja...-->
GCC/g++, however. GCC/g++, however.
</p> </p>
<hr> <hr />
<h2><a name="3_2">3.2 [removed]</a></h2> <h2><a name="3_2">3.2 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub <p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks). is here to preserve numbering (and hence links/bookmarks).
</p> </p>
<hr> <hr />
<h2><a name="3_3">3.3 [removed]</a></h2> <h2><a name="3_3">3.3 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub <p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks). is here to preserve numbering (and hence links/bookmarks).
</p> </p>
<hr> <hr />
<h2><a name="3_4">3.4 I can't use 'long long' on Solaris</a></h2> <h2><a name="3_4">3.4 I can't use 'long long' on Solaris</a></h2>
<p>By default we try to support the C99 <code>long long</code> type. <p>By default we try to support the C99 <code>long long</code> type.
This requires that certain functions from your C library be present. This requires that certain functions from your C library be present.
@ -433,7 +444,7 @@ which is no longer available, thanks deja...-->
<p>This has been fixed for 3.0.3 and onwards. <p>This has been fixed for 3.0.3 and onwards.
</p> </p>
<hr> <hr />
<h2><a name="3_5">3.5 <code>_XOPEN_SOURCE</code> / <code>_GNU_SOURCE</code> <h2><a name="3_5">3.5 <code>_XOPEN_SOURCE</code> / <code>_GNU_SOURCE</code>
/ etc is always defined</a></h2> / etc is always defined</a></h2>
<p>On Solaris, g++ (but not gcc) always defines the preprocessor <p>On Solaris, g++ (but not gcc) always defines the preprocessor
@ -465,13 +476,13 @@ which is no longer available, thanks deja...-->
a list of predefined macros for any particular installation. a list of predefined macros for any particular installation.
</p> </p>
<p>This has been discussed on the mailing lists <p>This has been discussed on the mailing lists
<a href="http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris">quite a bit</a>. <a href="http://gcc.gnu.org/cgi-bin/htsearch?method=and&amp;format=builtin-long&amp;sort=score&amp;words=_XOPEN_SOURCE+Solaris">quite a bit</a>.
</p> </p>
<p>This method is something of a wart. We'd like to find a cleaner <p>This method is something of a wart. We'd like to find a cleaner
solution, but nobody yet has contributed the time. solution, but nobody yet has contributed the time.
</p> </p>
<hr> <hr />
<h2><a name="3_6">3.6 OS X ctype.h is broken! How can I hack it?</a></h2> <h2><a name="3_6">3.6 OS X ctype.h is broken! How can I hack it?</a></h2>
<p>This is a long-standing bug in the OS X support. Fortunately, <p>This is a long-standing bug in the OS X support. Fortunately,
the patch is quite simple, and well-known. the patch is quite simple, and well-known.
@ -479,7 +490,7 @@ which is no longer available, thanks deja...-->
link to the solution.</a> link to the solution.</a>
</p> </p>
<hr> <hr />
<h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1> <h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1>
<em>Note that this section can get rapdily outdated -- such is the <em>Note that this section can get rapdily outdated -- such is the
nature of an open-source project. For the latest information, join nature of an open-source project. For the latest information, join
@ -571,7 +582,7 @@ New:
</pre> </pre>
<hr> <hr />
<h2><a name="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</a></h2> <h2><a name="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</a></h2>
<p>This is by no means meant to be complete nor exhaustive, but <p>This is by no means meant to be complete nor exhaustive, but
mentions some problems that users may encounter when building mentions some problems that users may encounter when building
@ -596,7 +607,7 @@ New:
experiences. :-)</li> experiences. :-)</li>
</ul> </ul>
<hr> <hr />
<h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2> <h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2>
<p>Yes, unfortunately, there are some. In a <p>Yes, unfortunately, there are some. In a
<a href="http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html">message <a href="http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html">message
@ -615,28 +626,26 @@ New:
Some of these have resulted in <a href="#5_2">code changes</a>. Some of these have resulted in <a href="#5_2">code changes</a>.
</p> </p>
<hr> <hr />
<h2><a name="4_4">4.4 Things in libstdc++ that only look like bugs</a></h2> <h2><a name="4_4">4.4 Things in libstdc++ that only look like bugs</a></h2>
<p>There are things which are not bugs in the compiler (4.2) nor <p>There are things which are not bugs in the compiler (4.2) nor
the language specification (4.3), but aren't really bugs in the language specification (4.3), but aren't really bugs in
libstdc++, either. Really! Please do not report these as bugs. libstdc++, either. Really! Please do not report these as bugs.
</p> </p>
<a name="4_4_Weff"> <p><a name="4_4_Weff"><strong>-Weffc++</strong></a>
<p><strong>-Weffc++</strong> The biggest of these is the quadzillions of warnings about the
The biggest of these is the quadzillions of warnings about the library headers emitted when <code>-Weffc++</code> is used. Making
library headers emitted when <code>-Weffc++</code> is used. Making libstdc++ &quot;-Weffc++-clean&quot; is not a goal of the project,
libstdc++ &quot;-Weffc++-clean&quot; is not a goal of the project, for a few reasons. Mainly, that option tries to enforce
for a few reasons. Mainly, that option tries to enforce object-oriented programming, while the Standard Library isn't
object-oriented programming, while the Standard Library isn't necessarily trying to be OO.
necessarily trying to be OO. </p>
</p> <p><a name="4_4_iostreamclear"><strong>reopening a stream fails</strong>
</a> </a> Did I just say that -Weffc++ was our biggest false-bug report?
<a name="4_4_iostreamclear"> I lied. (It used to be.) Today it seems to be reports that after
<p><strong>reopening a stream fails</strong> executing a sequence like
Did I just say that -Weffc++ was our biggest false-bug report? I </p>
lied. (It used to be.) Today it seems to be reports that after <pre>
executing a sequence like
<pre>
#include &lt;fstream&gt; #include &lt;fstream&gt;
... ...
std::fstream fs(&quot;a_file&quot;); std::fstream fs(&quot;a_file&quot;);
@ -645,59 +654,54 @@ New:
// . // .
fs.close(); fs.close();
fs.open(&quot;a_new_file&quot;);</pre> fs.open(&quot;a_new_file&quot;);</pre>
all operations on the re-opened <code>fs</code> will fail, or at <p>all operations on the re-opened <code>fs</code> will fail, or at
least act very strangely. Yes, they often will, especially if least act very strangely. Yes, they often will, especially if
<code>fs</code> reached the EOF state on the previous file. The <code>fs</code> reached the EOF state on the previous file. The
reason is that the state flags are <strong>not</strong> cleared reason is that the state flags are <strong>not</strong> cleared
on a successful call to open(). The standard unfortunately did on a successful call to open(). The standard unfortunately did
not specify behavior in this case, and to everybody's great sorrow, not specify behavior in this case, and to everybody's great sorrow,
the <a href="../ext/howto.html#5">proposed LWG resolution</a> (see the <a href="../ext/howto.html#5">proposed LWG resolution</a> (see
DR #22) is to leave the flags unchanged. You must insert a call DR #22) is to leave the flags unchanged. You must insert a call
to <code>fs.clear()</code> between the calls to close() and open(), to <code>fs.clear()</code> between the calls to close() and open(),
and then everything will work like we all expect it to work. and then everything will work like we all expect it to work.
</p> </p>
</a> <p><a name="4_4_rel_ops"><strong>rel_ops</strong></a>
<a name="4_4_rel_ops"> Another is the <code>rel_ops</code> namespace and the template
<p><strong>rel_ops</strong> comparison operator functions contained therein. If they become
Another is the <code>rel_ops</code> namespace and the template visible in the same namespace as other comparison functions
comparison operator functions contained therein. If they become (e.g., '<code>using</code>' them and the &lt;iterator&gt; header),
visible in the same namespace as other comparison functions then you will suddenly be faced with huge numbers of ambiguity
(e.g., '<code>using</code>' them and the &lt;iterator&gt; header), errors. This was discussed on the -v3 list; Nathan Myers
then you will suddenly be faced with huge numbers of ambiguity <a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
errors. This was discussed on the -v3 list; Nathan Myers things up here</a>. The collisions with vector/string iterator
<a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums types have been fixed for 3.1. <!-- more links to email here -->
things up here</a>. The collisions with vector/string iterator </p>
types have been fixed for 3.1. <!-- more links to email here --> <h3><a name="4_4_interface">The g++-3 headers are <em>not ours</em></a></h3>
</p> <p>If you have found an extremely broken header file which is
</a> causing problems for you, look carefully before submitting a
<a name="4_4_interface"><h3>The g++-3 headers are &quot;high&quot; priority bug report (which you probably shouldn't
<em>not ours</em></h3> do anyhow; see the last paragraph of the page describing
<p>If you have found an extremely broken header file which is
causing problems for you, look carefully before submitting a
&quot;high&quot; priority bug report (which you probably shouldn't
do anyhow; see the last paragraph of the page describing
<a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>). <a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>).
</p> </p>
<p>If the headers are in <code>${prefix}/include/g++-3</code>, or if <p>If the headers are in <code>${prefix}/include/g++-3</code>, or if
the installed library's name looks like <code>libstdc++-2.10.a</code> the installed library's name looks like <code>libstdc++-2.10.a</code>
or <code>libstdc++-libc6-2.10.so</code>, or <code>libstdc++-libc6-2.10.so</code>,
then you are using the old libstdc++-v2 library, which is nonstandard then you are using the old libstdc++-v2 library, which is nonstandard
and unmaintained. Do not report problems with -v2 to the -v3 and unmaintained. Do not report problems with -v2 to the -v3
mailing list. mailing list.
</p> </p>
<p>Currently our header files are installed in <p>Currently our header files are installed in
<code>${prefix}/include/g++-v3</code> (see the 'v'?). This may <code>${prefix}/include/g++-v3</code> (see the 'v'?). This may
change with the next release of GCC, as it may be too confusing, change with the next release of GCC, as it may be too confusing,
but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the
question has not yet been decided</a>. question has not yet been decided</a>.
</p> </p>
</a> <p><a name="4_4_glibc"><strong>glibc</strong></a>
<a name="4_4_glibc"> If you're on a GNU/Linux system and have just upgraded to
<p><strong>glibc</strong> glibc 2.2, but are still using gcc 2.95.2, then you should have
If you're on a GNU/Linux system and have just upgraded to read the glibc FAQ, specifically 2.34:
glibc 2.2, but are still using gcc 2.95.2, then you should have </p>
read the glibc FAQ, specifically 2.34: <pre>
<pre>
2.34. When compiling C++ programs, I get a compilation error in streambuf.h. 2.34. When compiling C++ programs, I get a compilation error in streambuf.h.
{BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to
@ -705,34 +709,31 @@ apply a patch to the include files in /usr/include/g++, because the fpos_t
type has changed in glibc 2.2. The patch is at type has changed in glibc 2.2. The patch is at
http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
</pre> </pre>
Note that 2.95.x shipped with the <p>Note that 2.95.x shipped with the
<a href="#4_4_interface">old v2 library</a> which is no longer <a href="#4_4_interface">old v2 library</a> which is no longer
maintained. Also note that gcc 2.95.3 fixes this problem, but maintained. Also note that gcc 2.95.3 fixes this problem, but
requires a separate patch for libstdc++-v3. requires a separate patch for libstdc++-v3.
</p> </p>
</a> <p><a name="4_4_checks"><strong>concept checks</strong></a>
<a name="4_4_checks"> If you see compilation errors containing messages about
<p><strong>concept checks</strong> <code> <em>foo</em>Concept </code>and a<code> constraints </code>
If you see compilation errors containing messages about member function, then most likely you have violated one of the
<code> <em>foo</em>Concept </code>and a<code> constraints </code> requirements for types used during instantiation of template
member function, then most likely you have violated one of the containers and functions. For example, EqualityComparableConcept
requirements for types used during instantiation of template appears if your types must be comparable with == and you have not
containers and functions. For example, EqualityComparableConcept provided this capability (a typo, or wrong visibility, or you
appears if your types must be comparable with == and you have not just plain forgot, etc).
provided this capability (a typo, or wrong visibility, or you </p>
just plain forgot, etc). <p>More information, including how to optionally enable/disable the
</p> checks, is available
<p>More information, including how to optionally enable/disable the <a href="../19_diagnostics/howto.html#3">here</a>.
checks, is available </p>
<a href="../19_diagnostics/howto.html#3">here</a>. <p><a name="4_4_dlsym"><strong>dlopen/dlsym</strong></a>
</p> If you are using the C++ library across dynamically-loaded
</a> objects, make certain that you are passing the correct options
<a name="4_4_dlsym"> when compiling and linking:
<p><strong>dlopen/dlsym</strong> </p>
If you are using the C++ library across dynamically-loaded <pre>
objects, make certain that you are passing the correct options
when compiling and linking:
<pre>
// compile the library components // compile the library components
g++ -fPIC -c a.cc g++ -fPIC -c a.cc
g++ -fPIC -c b.cc g++ -fPIC -c b.cc
@ -743,10 +744,9 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o
// link the executable // link the executable
g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre></p> g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre>
</a>
<hr> <hr />
<h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2> <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2>
<p>If you have found a bug in the library and you think you have <p>If you have found a bug in the library and you think you have
a working fix, then send it in! The main GCC site has a page a working fix, then send it in! The main GCC site has a page
@ -765,7 +765,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<a href="#2_4">testsuite</a> -- but only if such a test exists. <a href="#2_4">testsuite</a> -- but only if such a test exists.
</p> </p>
<hr> <hr />
<h1><a name="5_0">5.0 Miscellaneous</a></h1> <h1><a name="5_0">5.0 Miscellaneous</a></h1>
<h2><a name="5_1">5.1 string::iterator is not char*; <h2><a name="5_1">5.1 string::iterator is not char*;
vector&lt;T&gt;::iterator is not T*</a></h2> vector&lt;T&gt;::iterator is not T*</a></h2>
@ -786,7 +786,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
vector&lt;&gt; (but not for basic_string&lt;&gt;). vector&lt;&gt; (but not for basic_string&lt;&gt;).
</p> </p>
<hr> <hr />
<h2><a name="5_2">5.2 What's next after libstdc++-v3?</a></h2> <h2><a name="5_2">5.2 What's next after libstdc++-v3?</a></h2>
<p>Hopefully, not much. The goal of libstdc++-v3 is to produce <p>Hopefully, not much. The goal of libstdc++-v3 is to produce
a fully-compliant, fully-portable Standard Library. After that, a fully-compliant, fully-portable Standard Library. After that,
@ -802,16 +802,16 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
we add code to the library based on what the current proposed we add code to the library based on what the current proposed
resolution specifies. Those additions are listed in resolution specifies. Those additions are listed in
<a href="../ext/howto.html#5">the extensions page</a>. <a href="../ext/howto.html#5">the extensions page</a>.
</p> </p></li>
<li><p>Performance tuning. Lots of performance tuning. This too is <li><p>Performance tuning. Lots of performance tuning. This too is
already underway for post-3.0 releases, starting with memory already underway for post-3.0 releases, starting with memory
expansion in container classes and buffer usage in synchronized expansion in container classes and buffer usage in synchronized
stream objects. stream objects.
</p> </p></li>
<li><p>An ABI for libstdc++ is being developed, so that <li><p>An ABI for libstdc++ is being developed, so that
multiple binary-incompatible copies of the library can be replaced multiple binary-incompatible copies of the library can be replaced
with a single backwards-compatible library, like libgcc_s.so is. with a single backwards-compatible library, like libgcc_s.so is.
</p> </p></li>
<li><p>The current libstdc++ contains extensions to the Library which <li><p>The current libstdc++ contains extensions to the Library which
must be explicitly requested by client code (for example, the must be explicitly requested by client code (for example, the
hash tables from SGI). Other extensions may be added to hash tables from SGI). Other extensions may be added to
@ -819,7 +819,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
(For example, the &quot;long long&quot; type from C99.) (For example, the &quot;long long&quot; type from C99.)
Bugfixes and rewrites (to improve or fix thread safety, for Bugfixes and rewrites (to improve or fix thread safety, for
instance) will of course be a continuing task. instance) will of course be a continuing task.
</p> </p></li>
</ol> </ol>
<p><a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This <p><a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This
question</a> about the next libstdc++ prompted some brief but question</a> about the next libstdc++ prompted some brief but
@ -827,7 +827,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>. <a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>.
</p> </p>
<hr> <hr />
<h2><a name="5_3">5.3 What about the STL from SGI?</a></h2> <h2><a name="5_3">5.3 What about the STL from SGI?</a></h2>
<p>The <a href="http://www.sgi.com/Technology/STL/">STL from SGI</a>, <p>The <a href="http://www.sgi.com/Technology/STL/">STL from SGI</a>,
version 3.3, was the most recent merge of the STL codebase. The version 3.3, was the most recent merge of the STL codebase. The
@ -844,14 +844,15 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
recommended reading. recommended reading.
</p> </p>
<hr> <hr />
<h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2> <h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2>
<p>Headers in the <code>ext</code> and <code>backward</code> <p>Headers in the <code>ext</code> and <code>backward</code>
subdirectories should be referred to by their relative paths: subdirectories should be referred to by their relative paths:
<!-- Careful, the leading spaces in PRE show up directly. --> <!-- Careful, the leading spaces in PRE show up directly. -->
<pre> </p>
<pre>
#include &lt;ext/hash_map&gt; </pre> #include &lt;ext/hash_map&gt; </pre>
rather than using <code>-I</code> or other options. This is more <p>rather than using <code>-I</code> or other options. This is more
portable and forward-compatible. (The situation is the same as portable and forward-compatible. (The situation is the same as
that of other headers whose directories are not searched directly, that of other headers whose directories are not searched directly,
e.g., <code>&lt;sys/stat.h&gt;</code>, <code>&lt;X11/Xlib.h&gt;</code>. e.g., <code>&lt;sys/stat.h&gt;</code>, <code>&lt;X11/Xlib.h&gt;</code>.
@ -860,13 +861,13 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<a href="../ext/howto.html">their own page</a>. <a href="../ext/howto.html">their own page</a>.
</p> </p>
<hr> <hr />
<h2><a name="5_5">5.5 [removed]</a></h2> <h2><a name="5_5">5.5 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub <p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks). is here to preserve numbering (and hence links/bookmarks).
</p> </p>
<hr> <hr />
<h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2> <h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2>
<p>When the system's libc is itself thread-safe, a non-generic <p>When the system's libc is itself thread-safe, a non-generic
implementation of atomicity.h exists for the architecture, and gcc implementation of atomicity.h exists for the architecture, and gcc
@ -877,7 +878,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
what object locks must be held based on the objects referenced in what object locks must be held based on the objects referenced in
a method call. Without getting into great detail, here is an a method call. Without getting into great detail, here is an
example which requires user-level locks: example which requires user-level locks:
<pre> </p>
<pre>
library_class_a shared_object_a; library_class_a shared_object_a;
thread_main () { thread_main () {
@ -887,18 +889,17 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
} }
// Multiple copies of thread_main() are started in independent threads.</pre> // Multiple copies of thread_main() are started in independent threads.</pre>
</p>
<p>Under the assumption that object_a and object_b are never exposed to <p>Under the assumption that object_a and object_b are never exposed to
another thread, here is an example that should not require any another thread, here is an example that should not require any
user-level locks: user-level locks:
<pre> </p>
<pre>
thread_main () { thread_main () {
library_class_a object_a; library_class_a object_a;
library_class_b *object_b = new library_class_b; library_class_b *object_b = new library_class_b;
object_a.add_b (object_b); object_a.add_b (object_b);
object_a.mutate (); object_a.mutate ();
} </pre> } </pre>
</p>
<p>All library objects are safe to use in a multithreaded program as <p>All library objects are safe to use in a multithreaded program as
long as each thread carefully locks out access by any other thread long as each thread carefully locks out access by any other thread
while it uses any object visible to another thread. In general, while it uses any object visible to another thread. In general,
@ -913,7 +914,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
more information. more information.
</p> </p>
<hr> <hr />
<h2><a name="5_7">5.7 How do I get a copy of the ISO C++ Standard?</a></h2> <h2><a name="5_7">5.7 How do I get a copy of the ISO C++ Standard?</a></h2>
<p>Copies of the full ISO 14882 standard are available on line via the <p>Copies of the full ISO 14882 standard are available on line via the
ISO mirror site for committee members. Non-members, or those who ISO mirror site for committee members. Non-members, or those who
@ -931,7 +932,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<a href="http://www.iso.ch/">ISO homepage</a> and find out! <a href="http://www.iso.ch/">ISO homepage</a> and find out!
</p> </p>
<hr> <hr />
<h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2> <h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2>
<p>&quot;ABI&quot; stands for &quot;Application Binary Interface.&quot; <p>&quot;ABI&quot; stands for &quot;Application Binary Interface.&quot;
Conventionally, it refers to a great mass of details about how Conventionally, it refers to a great mass of details about how
@ -980,7 +981,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions. See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

4
libstdc++-v3/docs/html/faq/index.txt
View file

@ -106,8 +106,8 @@
The libstdc++ project is contributed to by several developers all over The libstdc++ project is contributed to by several developers all over
the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo
Paolo Carlini are the lead maintainers of the CVS archive. Carlini are the lead maintainers of the CVS archive.
Development and discussion is held on the libstdc++ mailing list. Development and discussion is held on the libstdc++ mailing list.
Subscribing to the list, or searching the list archives, is open to Subscribing to the list, or searching the list archives, is open to

69
libstdc++-v3/docs/html/install.html
View file

@ -1,12 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html> <html>
<head> <head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="README for the GNU libstdc++ effort."> <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." />
<meta name="GENERATOR" content="vi and eight fingers"> <meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 Installation Instructions</title> <title>libstdc++-v3 Installation Instructions</title>
<link rel="StyleSheet" href="lib3styles.css"> <link rel="StyleSheet" href="lib3styles.css" />
</head> </head>
<body> <body>
@ -18,21 +17,22 @@
</p> </p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<h2>Contents</h2> <h2>Contents</h2>
<ul> <ul>
<li><a href="#prereqs">Tools you will need beforehand</a> <li><a href="#prereqs">Tools you will need beforehand</a></li>
<li><a href="#srcsetup">Setting up the source directories</a> <li><a href="#srcsetup">Setting up the source directories</a></li>
<li><a href="#config">Configuring</a> <li><a href="#config">Configuring</a></li>
<li><a href="#install">Building and installing the library</a> <li><a href="#install">Building and installing the library</a></li>
<li><a href="#postinstall">Post-installation</a> <li><a href="#postinstall">Post-installation</a></li>
<li><a href="#usage">Using the library</a> <li><a href="#usage">Using the library</a></li>
</ul> </ul>
<hr> <hr />
<!-- ####################################################### --> <!-- ####################################################### -->
@ -88,8 +88,8 @@
features if the underlying support is present. features if the underlying support is present.
</p> </p>
<p>Finally, a few system-specific requirements: </p> <p>Finally, a few system-specific requirements: </p>
<dl> <dl>
<dt> linux </dt> <dt> linux </dt>
<dd>If you are using gcc 3.1 or later on linux, and are using <dd>If you are using gcc 3.1 or later on linux, and are using
@ -119,9 +119,9 @@
</li> </li>
</ul> </ul>
</dd> </dd>
</dl> </dl>
<hr> <hr />
<h2><a name="srcsetup">Setting up the source directories</a></h2> <h2><a name="srcsetup">Setting up the source directories</a></h2>
<p>The following definitions will be used throughout the rest of this <p>The following definitions will be used throughout the rest of this
@ -131,15 +131,20 @@
<li><em>gccsrcdir</em>: The directory holding the source of the <li><em>gccsrcdir</em>: The directory holding the source of the
compiler. It should have several subdirectories like compiler. It should have several subdirectories like
<em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc. <em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
</li>
<li><em>libsrcdir</em>: The directory holding the source of the <li><em>libsrcdir</em>: The directory holding the source of the
C++ library. C++ library.
</li>
<li><em>gccbuilddir</em>: The build directory for the compiler <li><em>gccbuilddir</em>: The build directory for the compiler
in <em>gccsrcdir</em>. GCC requires that it be built in in <em>gccsrcdir</em>. GCC requires that it be built in
a different directory than its sources. a different directory than its sources.
</li>
<li><em>libbuilddir</em>: The build directory for libstdc++. <li><em>libbuilddir</em>: The build directory for libstdc++.
</li>
<li><em>destdir</em>: The eventual installation directory for <li><em>destdir</em>: The eventual installation directory for
the compiler/libraries, set with the --prefix option to the compiler/libraries, set with the --prefix option to
the configure script. the configure script.
</li>
</ul> </ul>
<p> Note: </p> <p> Note: </p>
<ol> <ol>
@ -147,10 +152,12 @@
library that comes with the compiler, so <em>libsrcdir</em> library that comes with the compiler, so <em>libsrcdir</em>
and <em>libbuilddir</em> must be contained under and <em>libbuilddir</em> must be contained under
<em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively. <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
</li>
<li>The source, build, and installation directories should <li>The source, build, and installation directories should
not be parents of one another; i.e., these should all be not be parents of one another; i.e., these should all be
separate directories. Please don't build out of the separate directories. Please don't build out of the
source directory. source directory.
</li>
</ol> </ol>
<p>Check out or download the GCC sources: the resulting source directory <p>Check out or download the GCC sources: the resulting source directory
@ -175,7 +182,7 @@
mv <em>libsrcdir</em> libstdc++-v3</pre> mv <em>libsrcdir</em> libstdc++-v3</pre>
<hr> <hr />
<h2><a name="config">Configuring</a></h2> <h2><a name="config">Configuring</a></h2>
<p>If you have never done this before, you should read the basic <p>If you have never done this before, you should read the basic
<a href="http://gcc.gnu.org/install/">GCC Installation <a href="http://gcc.gnu.org/install/">GCC Installation
@ -196,7 +203,7 @@
<em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre> <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
<hr> <hr />
<h2><a name="install">Building and installing the library</a></h2> <h2><a name="install">Building and installing the library</a></h2>
<p>Now you have a few options:</p> <p>Now you have a few options:</p>
<h3>[re]building <em>everything</em></h3> <h3>[re]building <em>everything</em></h3>
@ -236,7 +243,7 @@
make install-target-libstdc++-v3</pre> make install-target-libstdc++-v3</pre>
<hr> <hr />
<h2><a name="postinstall">Post-installation</a></h2> <h2><a name="postinstall">Post-installation</a></h2>
<p>Installation will create the <em>destdir</em> directory and <p>Installation will create the <em>destdir</em> directory and
populate it with subdirectories: populate it with subdirectories:
@ -266,7 +273,7 @@
</p> </p>
<hr> <hr />
<h2><a name="usage">Using the library</a></h2> <h2><a name="usage">Using the library</a></h2>
<h3>Find the new library at runtime (shared linking only)</h3> <h3>Find the new library at runtime (shared linking only)</h3>
<p>If you only built a static library (libstdc++.a), or if you <p>If you only built a static library (libstdc++.a), or if you
@ -279,23 +286,25 @@
the usual ones are printed to the screen during installation. the usual ones are printed to the screen during installation.
They include: They include:
</p> </p>
<ul> <ul>
<li>At runtime set LD_LIBRARY_PATH in your environment correctly, <li>At runtime set LD_LIBRARY_PATH in your environment correctly,
so that the shared library for libstdc++ can be found and so that the shared library for libstdc++ can be found and
loaded. Be certain that you understand all of the other loaded. Be certain that you understand all of the other
implications and behavior of LD_LIBRARY_PATH first (few implications and behavior of LD_LIBRARY_PATH first (few
people do, and they get into trouble). people do, and they get into trouble).
</li>
<li>Compile the path to find the library at runtime into the <li>Compile the path to find the library at runtime into the
program. This can be done by passing certain options to g++, program. This can be done by passing certain options to g++,
which will in turn pass them on to the linker. The exact which will in turn pass them on to the linker. The exact
format of the options is dependent on which linker you use: format of the options is dependent on which linker you use:
<ul> <ul>
<li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code> <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li>
<li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code> <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li>
<li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code> <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
<li>More...? Let us know! <li>More...? Let us know!</li>
</ul> </ul>
</ul> </li>
</ul>
<p>Use the <code>ldd(1)</code> utility to show which library the system <p>Use the <code>ldd(1)</code> utility to show which library the system
thinks it will get at runtime. thinks it will get at runtime.
</p> </p>
@ -306,7 +315,7 @@
<!-- <!--
<hr> <hr />
<h2><a name=""></a></h2> <h2><a name=""></a></h2>
<p> <p>
</p> </p>
@ -315,7 +324,7 @@
<!-- ####################################################### --> <!-- ####################################################### -->
<hr> <hr />
<p class="fineprint"><em> <p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions. See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to Comments and suggestions are welcome, and may be sent to

6
libstdc++-v3/docs/html/makedoc.awk
View file

@ -9,7 +9,7 @@
BEGIN { BEGIN {
state = "looking"; state = "looking";
entries = 0; entries = 0;
printf (" <li>%s</li>\n", title); printf (" <li>%s\n", title);
printf (" <ul>\n"); printf (" <ul>\n");
} }
@ -39,7 +39,7 @@ state == "entries" && /^<\/ul>/ {
END { END {
for (i = 0; i < entries; i++) for (i = 0; i < entries; i++)
printf (" %s\n", entry[i]); printf (" %s\n", entry[i]);
printf (" </ul>\n\n"); printf (" </ul>\n </li>\n\n");
} }
function extract_info(line) { function extract_info(line) {
@ -58,7 +58,7 @@ function extract_info(line) {
} }
# visible text # visible text
gsub("</a>","",line); gsub("</a></li>","",line);
start = index(line,"\">") + 2; start = index(line,"\">") + 2;
thistext = substr(line,start); thistext = substr(line,start);