OpenE2K
/
gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Makefile: Use more portable shell wildcard. 

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
Show Stats 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>
* 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>
<head>
<title>How to contribute</title>
</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>
<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:
</p>
<p>
<hr>
<hr />
<h4>ONE : read the documentation</h4>
<p>
<p>
<ul>
<li> Get and read the relevant sections of the C++ language
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>
(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>
</li>
<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>
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>
<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>
<li> And last but certainly not least, read the library-specific information found <a href="../documentation.html"> here.</a>
</li>
</ul>
<p>
<hr>
<hr />
<h4>TWO : copyright assignment</h4>
<p>
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
Kosnik</a> if you are confused about the assignment or have general
licensing questions.
</p>
<p>
<hr>
<hr />
<h4>THREE : submitting patches</h4>
<p>
<p>
Every patch must have several pieces of information before it can be
properly evaluated. Ideally (and to ensure the fastest possible
response from the maintainers) it would have all of these pieces:
<p>
</p>
<ul>
<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
for format and content. If using you are using emacs as your editor,
simply position the insertion point at the beginning of your change
and hit CX-4a to bring up the appropriate ChangeLog
entry. See--magic! Similar functionality also exists for vi.
entry. See--magic! Similar functionality also exists for vi. </li>
<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
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
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
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>
</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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 17</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -21,18 +20,18 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#2">The Standard C++ header files</a>
<li><a href="#3">The Standard C++ library and multithreading</a>
<li><a href="#4"><code>&lt;foo&gt;</code> vs <code>&lt;foo.h&gt;</code></a>
<li><a href="porting-howto.html">Porting HOWTO</a>
<li><a href="#5">Behavior specific to libstdc++-v3</a>
<li><a href="#6">Preprocessor macros controlling the library</a>
<li><a href="#2">The Standard C++ header files</a></li>
<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>
<li><a href="porting-howto.html">Porting HOWTO</a></li>
<li><a href="#5">Behavior specific to libstdc++-v3</a></li>
<li><a href="#6">Preprocessor macros controlling the library</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -51,7 +50,7 @@
all compile and run.
</p>
<hr>
<hr />
<h2><a name="3">The Standard C++ library and multithreading</a></h2>
<p>This section discusses issues surrounding the proper compilation
of multithreaded applications which use the Standard C++
@ -129,16 +128,17 @@
relevant message in the thread; from there you can use
&quot;Thread Next&quot; to move down the thread. This farm is in
latest-to-oldest order.
</p>
<ul>
<li>Our threading expert Loren gives a breakdown of
<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">
This message</a> inspired a recent updating of issues with threading
and the SGI STL library. It also contains some example
POSIX-multithreaded STL code.
POSIX-multithreaded STL code.</li>
</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
people with access to the backup tapes have been too swamped with work
to restore them. Many of the points have been superseded anyhow.)
@ -150,7 +150,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
itself fully supports namespaces, including <code>std::</code>.
@ -164,16 +164,18 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="5">Behavior specific to libstdc++-v3</a></h2>
<p>The ISO standard defines the following phrase:
</p>
<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
depends on the implementation <strong>and that each implementation
shall document</strong>.
</dd>
</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
implementation&quot; are documented elsewhere. Everything listed in
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
back to the runtime loader. Talk to the compiler people. :-)
</p>
<p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br>
<strong>[18.5.2]/5</strong> (bad_cast),<br>
<strong>[18.5.3]/5</strong> (bad_typeid),<br>
<strong>[18.6.1]/8</strong> (exception),<br>
<p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br />
<strong>[18.5.2]/5</strong> (bad_cast),<br />
<strong>[18.5.3]/5</strong> (bad_typeid),<br />
<strong>[18.6.1]/8</strong> (exception),<br />
<strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
member function of class <code>std::exception</code>, and these other
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
they behave.
</p>
<p><strong>[21.1.3.1]/3,4</strong>,<br>
<strong>[21.1.3.2]/2</strong>,<br>
<strong>[23.*]'s foo::iterator</strong>,<br>
<strong>[27.*]'s foo::*_type</strong>,<br>
<p><strong>[21.1.3.1]/3,4</strong>,<br />
<strong>[21.1.3.2]/2</strong>,<br />
<strong>[23.*]'s foo::iterator</strong>,<br />
<strong>[27.*]'s foo::*_type</strong>,<br />
<strong>others...</strong>
Nope, these types are called implementation-defined because you
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
advantage of this yet.
</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>
The effects of <code>pubsetbuf/setbuf</code> are described
<a href="../27_io/howto.html#2">in this chapter</a>.
@ -269,7 +271,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="6">Preprocessor macros controlling the library</a></h2>
<p>Some of the semantics of the libstdc++-v3 implementation are
controlled by preprocessor macros, both during build/installation and
@ -297,6 +299,7 @@
The default state of the symbol is listed. &quot;Configurable&quot;
(or &quot;Not configurable&quot;) means that the symbol is initially
chosen (or not) based on --enable/--disable options at configure time.
</p>
<dl>
<dt><code>_GLIBCPP_DEPRECATED</code></dt>
<dd>Undefined by default. Not configurable. Turning this on enables
@ -329,7 +332,6 @@
</dd>
-->
</dl>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
@ -338,7 +340,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="libstdc++, license, licence">
<meta name="DESCRIPTION" content="Copying restrictions for libstdc++.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, license, licence" />
<meta name="DESCRIPTION" content="Copying restrictions for libstdc++." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 copying</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -21,7 +20,7 @@
writing this page is a programmer, not a lawyer.
</p>
<hr>
<hr />
<h2>The Code: Runtime GPL</h2>
@ -29,7 +28,8 @@
<a href="COPYING">GNU General Public License</a>, with the so-called
&quot;runtime exception,&quot; as follows (or see any header or
implementation file):
<pre>
</p>
<pre>
As a special exception, you may use this file as part of a free software
library without restriction. Specifically, if other files instantiate
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
invalidate any other reasons why the executable file might be covered by
the GNU General Public License.
</pre>
</p>
</pre>
<p>Hopefully that text is self-explanatory. If it isn't, you need to speak
to your lawyer, or the Free Software Foundation.
@ -50,14 +49,14 @@
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>
<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.
</p>
<p><strong>Q: How is that different from the GNU {Lesser,Library}
GPL?</strong>
<!-- 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
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
@ -68,11 +67,11 @@
<p><strong>Q: I see. So, what restrictions <em>are</em> there on
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.
</p>
<hr>
<hr />
<h2>The Docs: FDL</h2>
@ -92,7 +91,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
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>.

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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 18</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -24,17 +23,17 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Types</a>
<li><a href="#2">Implementation properties</a>
<li><a href="#3">Start and Termination</a>
<li><a href="#4">Dynamic memory management</a>
<li><a href="#5">RTTI, the ABI, and demangling</a>
<li><a href="#1">Types</a></li>
<li><a href="#2">Implementation properties</a></li>
<li><a href="#3">Start and Termination</a></li>
<li><a href="#4">Dynamic memory management</a></li>
<li><a href="#5">RTTI, the ABI, and demangling</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -55,12 +54,13 @@
always a pointer.)
</p>
<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
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
before it matches integers:
<pre>
</p>
<pre>
const // this is a const object...
class {
public:
@ -77,7 +77,8 @@
// taken (see Item 27)...
} 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
Effective C++ CD</a>, reproduced here with permission.)
</p>
@ -93,7 +94,7 @@
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
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
valid! Even though it has no data members, it still needs a
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>.
</p>
<hr>
<hr />
<h2><a name="2">Implementation properties</a></h2>
<p>
<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
traits classes -- fourteen in total -- are all specilizations of the
template class <code>numeric_limits</code> defined as follows:
</p>
<pre>
template&lt;typename T&gt; struct class {
static const bool is_specialized;
@ -150,12 +151,11 @@
static const bool tinyness_before;
static const float_round_style round_style;
};</pre>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="3">Start and Termination</a></h2>
<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
@ -166,11 +166,14 @@
</p>
<p>The good old <code>exit()</code> function can be a bit funky, too, until
you look closer. Basically, three points to remember are:
</p>
<ol>
<li>Static objects are destroyed in reverse order of their creation.
</li>
<li>Functions registered with <code>atexit()</code> are called in
reverse order of registration, once per registration call.
(This isn't actually new.)
</li>
<li>The previous two actions are &quot;interleaved,&quot; that is,
given this pseudocode:
<pre>
@ -181,12 +184,13 @@
atexit(f1);
static Thing obj2;
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
will be destroyed. If f1 or f2 allow an exception to propagate
out of them, Bad Things happen.
</li>
</ol>
</p>
<p>Note also that <code>atexit()</code> is only required to store 32
functions, and the compiler/library might already be using some of
those slots. If you think you may run out, we recommend using
@ -196,21 +200,22 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="4">Dynamic memory management</a></h2>
<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
descriptions of <code>new</code>:
<ul>
<li>single object form, throwing a <code>bad_alloc</code> on errors;
this is what most people are used to using
<li>single object &quot;nothrow&quot; form, returning NULL on errors
<li>array new, throwing <code>bad_alloc</code> on errors
<li>array nothrow new, returning NULL on errors
<li>placement new, which does nothing (like it's supposed to)
<li>placement array new, which also does nothing
</ul>
They are distinguished by the parameters that you pass to them, like
</p>
<ul>
<li>single object form, throwing a <code>bad_alloc</code> on errors;
this is what most people are used to using</li>
<li>single object &quot;nothrow&quot; form, returning NULL on errors</li>
<li>array new, throwing <code>bad_alloc</code> on errors</li>
<li>array nothrow new, returning NULL on errors</li>
<li>placement new, which does nothing (like it's supposed to)</li>
<li>placement array new, which also does nothing</li>
</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>
are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (They match up for
@ -225,7 +230,8 @@
<code>bad_alloc</code> exception (or, technically, some class derived
from it). You can change this by writing your own function (called a
new-handler) and then registering it with <code>set_new_handler()</code>:
<pre>
</p>
<pre>
typedef void (*PFV)(void);
static char* safety;
@ -247,8 +253,7 @@
old_handler = set_new_handler (&amp;my_new_handler);
...
}
</pre>
</p>
</pre>
<p><code>bad_alloc</code> is derived from the base <code>exception</code>
class defined in Chapter 19.
</p>
@ -256,7 +261,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="5">RTTI, the ABI, and demangling</a></h2>
<p>If you have read the <a href="../documentation.html#4">source
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
are when you're seeing <code>typeid</code> strings in RTTI, or when
you're handling the runtime-support exception classes. For example:
<pre>
</p>
<pre>
#include &lt;exception&gt;
#include &lt;iostream&gt;
#include &lt;cxxabi.h&gt;
@ -304,11 +310,12 @@ int main()
free(realname);
return 0;
}</pre></p>
<p>With GCC 3.1 and later, this prints<pre>
St13bad_exception =&gt; std::bad_exception : 0
3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 0</pre>
}</pre>
<p>With GCC 3.1 and later, this prints
</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
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
@ -322,7 +329,7 @@ int main()
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 19</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -20,16 +19,16 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Adding data to exceptions</a>
<li><a href="#2">Exception class hierarchy diagram</a>
<li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a>
<li><a href="#4">Verbose <code>terminate</code></a>
<li><a href="#1">Adding data to exceptions</a></li>
<li><a href="#2">Exception class hierarchy diagram</a></li>
<li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a></li>
<li><a href="#4">Verbose <code>terminate</code></a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -56,7 +55,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
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>.
</p>
<hr>
<hr />
<h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2>
<p>Better taste! Less fat! Literally!</p>
<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.
</p>
<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
<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
@ -109,12 +108,13 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="4">Verbose <code>terminate</code></a></h2>
<p>If you are having difficulty with uncaught exceptions and want a
little bit of help debugging the causes of the core dumps, you can
make use of a GNU extension in GCC 3.1 and later:
<pre>
</p>
<pre>
#include &lt;exception&gt;
int main()
@ -123,7 +123,6 @@
...
throw <em>anything</em>;
}</pre>
</p>
<p>The <code> __verbose_terminate_handler </code> function obtains the name
of the current exception, attempts to demangle it, and prints it to
stderr. If the exception is derived from <code> std::exception </code>
@ -133,7 +132,8 @@
without returning; this one calls abort.
</p>
<p>For example:
<pre>
</p>
<pre>
#include &lt;exception&gt;
#include &lt;stdexcept&gt;
@ -151,9 +151,9 @@
else
throw argc;
}</pre>
</p>
<p>In GCC 3.1 and later, this gives
<pre>
</p>
<pre>
% ./a.out
terminate called after throwing a `int'
Aborted
@ -162,7 +162,7 @@
what(): argc is greater than 5!
Aborted
%</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>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
@ -171,7 +171,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 20</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -19,16 +18,16 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1"><code>auto_ptr</code> is not omnipotent</a>
<li><a href="#2"><code>auto_ptr</code> inside container classes</a>
<li><a href="#3">Functors</a>
<li><a href="#4">Pairs</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>
<li><a href="#3">Functors</a></li>
<li><a href="#4">Pairs</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -47,7 +46,8 @@
</p>
<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:
<pre>
</p>
<pre>
// not a recommend naming scheme, but good for web-based FAQs
typedef std::auto_ptr&lt;MyClass&gt; APMC;
@ -62,21 +62,24 @@
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
unwound past <code>func()</code>.
</p>
<p>Changing that code as follows is <em>not</em> AP-friendly:
<pre>
</p>
<pre>
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:
<pre>
</p>
<pre>
char* array = new char[10]; // array new...
...
delete array; // ...but single-object delete
</pre>
</p>
</pre>
<p>AP cannot tell whether the pointer you've passed at creation points
to one or many things. If it points to many things, you are about
to die. AP is trivial to write, however, so you could write your
@ -87,18 +90,19 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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>
described in the standard library require their contained types
to have, among other things, a copy constructor like this:
<pre>
</p>
<pre>
struct My_Type
{
My_Type (My_Type const&amp;);
};
</pre>
Note the const keyword; the object being copied shouldn't change.
</pre>
<p>Note the const keyword; the object being copied shouldn't change.
The template class <code>auto_ptr</code> (called AP here) does not
meet this requirement. Creating a new AP by copying an existing
one transfers ownership of the pointed-to object, which means that
@ -113,7 +117,8 @@
<a href="../19_diagnostics/howto.html#3">concept checks</a> built
in to this implementation will issue an error if you try to
compile code like this:
<pre>
</p>
<pre>
#include &lt;vector&gt;
#include &lt;memory&gt;
@ -121,14 +126,14 @@
{
std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int;
}
</pre>
Should you try this with the checks enabled, you will see an error.
</pre>
<p>Should you try this with the checks enabled, you will see an error.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="3">Functors</a></h2>
<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
@ -141,7 +146,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="4">Pairs</a></h2>
<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
@ -151,16 +156,20 @@
</p>
<p>Construction is simple. The default ctor initializes each member
with its respective default ctor. The other simple ctor,
<pre>
</p>
<pre>
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>.
</p>
<p>There is a copy constructor, but it requires that your compiler
handle member function templates:
<pre>
</p>
<pre>
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.
</p>
<p>The comparison operators are done for you. Equality
@ -170,24 +179,25 @@
<code>operator==</code> functions (for types like MyClass) or builtin
comparisons (for types like int, char, etc).
</p>
<a name="pairlt">
<p>The less-than operator is a bit odd the first time you see it. It
<p><a name="pairlt">
The less-than operator is a bit odd the first time you see it. It
is defined as evaluating to:
<pre>
</a>
</p>
<pre>
x.first &lt; y.first ||
( !(y.first &lt; x.first) &amp;&amp; x.second &lt; y.second )
</pre>
The other operators are not defined using the <code>rel_ops</code>
</pre>
<p>The other operators are not defined using the <code>rel_ops</code>
functions above, but their semantics are the same.
</p>
</a>
<p>Finally, there is a template function called <code>make_pair</code>
that takes two references-to-const objects and returns an
instance of a pair instantiated on their respective types:
<pre>
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre>
</p>
<pre>
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
@ -197,7 +207,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 21</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -18,17 +17,17 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">MFC's CString</a>
<li><a href="#2">A case-insensitive string class</a>
<li><a href="#3">Breaking a C++ string into tokens</a>
<li><a href="#4">Simple transformations</a>
<li><a href="#5">Making strings of arbitrary character types</a>
<li><a href="#1">MFC's CString</a></li>
<li><a href="#2">A case-insensitive string class</a></li>
<li><a href="#3">Breaking a C++ string into tokens</a></li>
<li><a href="#4">Simple transformations</a></li>
<li><a href="#5">Making strings of arbitrary character types</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -43,24 +42,29 @@
<p>Things are not as bad as they seem. In
<a href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this
message</a>, Joe Buck points out a few very important things:
</p>
<ul>
<li>The Standard <code>string</code> supports all the operations
that CString does, with three exceptions.
</li>
<li>Two of those exceptions (whitespace trimming and case
conversion) are trivial to implement. In fact, we do so
on this page.
</li>
<li>The third is <code>CString::Format</code>, which allows formatting
in the style of <code>sprintf</code>. This deserves some mention:
</li>
</ul>
</p>
<a name="1.1internal"> <!-- Coming from Chapter 27 -->
<p>The old libg++ library had a function called form(), which did much
<p><a name="1.1internal"> <!-- Coming from Chapter 27 -->
The old libg++ library had a function called form(), which did much
the same thing. But for a Standard solution, you should use the
stringstream classes. These are the bridge between the iostream
hierarchy and the string class, and they operate with regular
streams seamlessly because they inherit from the iostream
hierarchy. An quick example:
<pre>
</a>
</p>
<pre>
#include &lt;iostream&gt;
#include &lt;string&gt;
#include &lt;sstream&gt;
@ -80,10 +84,10 @@
return output_stream.str();
} </pre>
</p></a>
<p>A serious problem with CString is a design bug in its memory
allocation. Specifically, quoting from that same message:
<pre>
</p>
<pre>
CString suffers from a common programming error that results in
poor performance. Consider the following code:
@ -104,22 +108,25 @@
If you replace CString with string in the above function, the
performance is O(n).
</pre>
</p>
</pre>
<p>Joe Buck also pointed out some other things to keep in mind when
comparing CString and the Standard string class:
</p>
<ul>
<li>CString permits access to its internal representation; coders
who exploited that may have problems moving to <code>string</code>.
</li>
<li>Microsoft ships the source to CString (in the files
MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation
bug and rebuild your MFC libraries.
<em><B>Note:</B> It looks like the the CString shipped with
VC++6.0 has fixed this, although it may in fact have been one
of the VC++ SPs that did it.</em>
<em><strong>Note:</strong> It looks like the the CString shipped
with VC++6.0 has fixed this, although it may in fact have been
one of the VC++ SPs that did it.</em>
</li>
<li><code>string</code> operations like this have O(n) complexity
<em>if the implementors do it correctly</em>. The libstdc++
implementors did it correctly. Other vendors might not.
</li>
<li>While parts of the SGI STL are used in libstdc++-v3, their
string class is not. The SGI <code>string</code> is essentially
<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
is all before any allocator or traits customizations! (More
choices than you can shake a stick at -- want fries with that?)
</li>
</ul>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
<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
case-insensitive in the same way as the (common but nonstandard)
C function stricmp():&quot;
<pre>
</p>
<pre>
ci_string s( "AbCdE" );
// case insensitive
@ -154,7 +162,6 @@
// still case-preserving, of course
assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre>
</p>
<p>The solution is surprisingly easy. The original answer pages
on the GotW website were removed into cold storage, in
@ -189,7 +196,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
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
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:
<pre>
</p>
<pre>
std::list&lt;string&gt; ls;
stringtok (ls, " this \t is\t\n a test ");
for (std::list&lt;string&gt;const_iterator i = ls.begin();
i != ls.end(); ++i)
{
std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\n";
}</pre>
You would see this as output:
<pre>
} </pre>
<p>You would see this as output:
</p>
<pre>
:this:
:is:
:a:
:test:</pre>
with all the whitespace removed. The original <code>s</code> is still
:test: </pre>
<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
<code>ls.size()</code> will return how many tokens there were.
</p>
@ -248,7 +257,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="4">Simple transformations</a></h2>
<p>Here are Standard, simple, and portable ways to perform common
transformations on a <code>string</code> instance, such as &quot;convert
@ -258,7 +267,8 @@
</p>
<p>This code will go through some iterations (no pun). Here's the
simplistic version usually seen on Usenet:
<pre>
</p>
<pre>
#include &lt;string&gt;
#include &lt;algorithm&gt;
#include &lt;cctype&gt; // old &lt;ctype.h&gt;
@ -276,7 +286,7 @@
std::string capital_s;
capital_s.reserve(s.size());
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
<code>toupper/tolower</code>. This is absolutely guaranteed to work --
but <em>only</em> if the string contains <em>only</em> characters
@ -287,12 +297,12 @@
characters (hahahahahaha), then you're done.
</p>
<p>At minimum, you can write short wrappers like
<pre>
</p>
<pre>
char toLower (char c)
{
return tolower(static_cast&lt;unsigned char&gt;(c));
}</pre>
</p>
} </pre>
<p>The correct method is to use a facet for a particular locale
and call its conversion functions. These are discussed more in
Chapter 22; the specific part is
@ -304,7 +314,8 @@
like transformations, this task is trivial with the use of string's
<code>find</code> family. These examples are broken into multiple
statements for readability:
<pre>
</p>
<pre>
std::string str (" \t blah blah blah \n ");
// trim leading whitespace
@ -314,7 +325,7 @@
// trim trailing whitespace
notwhite = str.find_last_not_of(" \t\n");
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
optimize named temporaries out of existence.
</p>
@ -322,7 +333,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
go through and pull the examples together
@ -335,7 +346,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<title>
Notes on the codecvt implementation.
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<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>
<body>
<h1>
Notes on the codecvt implementation.
</h1>
<p>
<I>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000
</I>
</em>
</p>
<h2>
1. Abstract
@ -33,26 +36,25 @@ wide and narrow characters and the implementation-provided extended
functionality are given.
</p>
<p>
<h2>
2. What the standard says
</h2>
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]
</BLOCKQUOTE>
</blockquote>
The text around the codecvt definition gives some clues:
<BLOCKQUOTE>
<I>
<blockquote>
<em>
-1- The class codecvt&lt;internT,externT,stateT&gt; is for use when
converting from one codeset to another, such as from wide characters
to multibyte characters, between wide character encodings such as
Unicode and EUC.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
Hmm. So, in some unspecified way, Unicode encodings and
@ -60,18 +62,18 @@ translations between other character sets should be handled by this
class.
</p>
<BLOCKQUOTE>
<I>
<blockquote>
<em>
-2- The stateT argument selects the pair of codesets being mapped between.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
Ah ha! Another clue...
</p>
<BLOCKQUOTE>
<I>
<blockquote>
<em>
-3- The instantiations required in the Table ??
(lib.locale.category), namely codecvt&lt;wchar_t,char,mbstate_t&gt; and
codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
@ -83,11 +85,12 @@ mbstate_t perform conversion between encodings known to the library
implementor. Other encodings can be converted by specializing on a
user-defined stateT type. The stateT object can contain any state that
is useful to communicate to or from the specialized do_convert member.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
At this point, a couple points become clear:
</p>
<p>
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
mcsrtombs and wcsrtombs in particular.</p>
<p>
<h2>
3. Some thoughts on what would be useful
</h2>
@ -121,15 +123,19 @@ represent wide characters, and use an internal encoding of
UCS4. (GNU/Linux systems using glibc, in particular.) The C
programming language (and thus C++) does not specify a specific size
for the type wchar_t.
</p>
<p>
Thus, portable C++ code cannot assume a byte size (or endianness) either.
</p>
<p>
Getting back to the frequently asked question: What about Unicode strings?
</p>
<p>
What magic spell will do this conversion?
</p>
<p>
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
operating system allows bi-directional mapping between far more than
the following tantalizing possibilities:
</p>
<p>
(An edited list taken from <code>`iconv --list`</code> on a Red Hat 6.2/Intel system:
</p>
<BLOCKQUOTE>
<PRE>
<blockquote>
<pre>
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
@ -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,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16).
</PRE>
</BLOCKQUOTE>
</pre>
</blockquote>
<p>
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,
non-iconv implementations a table of enumerated values or some other
mechanism may be required.
</p>
</li>
<li>
Maximum length of the identifying string literal.
</li>
<li>
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
UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
however implementations, most notably Microsoft, vary.)
</li>
<li>
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
conversion descriptor encodes more information than a simple encoding
state type.
</li>
<li>
Conversion descriptors for both directions of encoding. (ie, both
UCS-2 to UTF-8 and UTF-8 to UCS-2.)
</li>
<li>
Something to indicate if the conversion requested if valid.
</li>
<li>
Something to represent if the conversion descriptors are valid.
</li>
<li>
Some way to enforce strict type checking on the internal and
external types. As part of this, the size of the internal and
external types will need to be known.
</li>
</ul>
<p>
<h2>
4. Problems with &quot;C&quot; code conversions : thread safety, global
locales, termination.
@ -224,11 +240,13 @@ when implemented using standard &quot;C&quot; functions.
<p>
Three problems arise, one big, one of medium importance, and one small.
</p>
<p>
First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue.
</p>
<p>
Of medium concern, in the grand scope of things, is that the functions
@ -236,6 +254,7 @@ used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise
incorrect. Yikes!
</p>
<p>
The last, and fundamental problem, is the assumption of a global
@ -247,14 +266,15 @@ the GNU C++ library would like to offer a solution that allows
multiple locales and or simultaneous usage with computationally
correct results. In short, libstdc++-v3 is trying to offer, as an
option, a high-quality implementation, damn the additional complexity!
</p>
<p>
For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements.
</p>
<p>
<h2>
5. Design
</h2>
@ -264,25 +284,30 @@ The two required specializations are implemented as follows:
<code>
codecvt&lt;char, char, mbstate_t&gt;
</code>
</p>
<p>
This is a degenerate (ie, does nothing) specialization. Implementing
this was a piece of cake.
</p>
<p>
<code>
codecvt&lt;char, wchar_t, mbstate_t&gt;
</code>
</p>
<p>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p>
<p>
Neither of these two required specializations deals with Unicode
characters. As such, libstdc++-v3 implements a partial specialization
of the codecvt class with and iconv wrapper class, __enc_traits as the
third template parameter.
</p>
<p>
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
(see 21.1.2 traits typedefs) only indicate that this type be copy
constructible.
</p>
<p>
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 is just a wrapper class for iconv, and provides an easy interface
to iconv functionality.
</p>
<p>
There are two constructors for __enc_traits:
</p>
<p>
<code>
__enc_traits() : __in_desc(0), __out_desc(0)
</code>
</p>
<p>
This default constructor sets the internal encoding to some default
(currently UCS4) and the external encoding to whatever is returned by
nl_langinfo(CODESET).
</p>
<p>
<code>
__enc_traits(const char* __int, const char* __ext)
</code>
</p>
<p>
This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for
either argument.
</p>
<p>
One of the issues with iconv is that the string literals identifying
@ -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
encodings. It is up to the user to make sure that these strings are
valid on the target system.
</p>
<p>
<code>
void
_M_init()
</code>
</p>
<p>
Strangely enough, this member function attempts to open conversion
descriptors for a given __enc_traits object. If the conversion
descriptors are not valid, the conversion descriptors returned will
not be valid and the resulting calls to the codecvt conversion
functions will return error.
</p>
<p>
<code>
bool
_M_good()
</code>
</p>
<p>
Provides a way to see if the given __enc_traits object has been
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
descriptors, this will also return false. Otherwise, the object is
ready to convert and will return true.
</p>
<p>
<code>
__enc_traits(const __enc_traits&amp;)
</code>
</p>
<p>
As iconv allocates memory and sets up conversion descriptors, the copy
constructor can only copy the member data pertaining to the internal
and external code conversions, and not the conversion descriptors
themselves.
</p>
<p>
Definitions for all the required codecvt member functions are provided
for this specialization, and usage of codecvt&lt;internal character type,
external character type, __enc_traits&gt; is consistent with other
codecvt usage.
</p>
<p>
<h2>
6. Examples
</h2>
<ul>
<li>
a. conversions involving string literals
<li>
a. conversions involving string literals
<pre>
typedef codecvt_base::result result;
typedef unsigned short unicode_t;
typedef unicode_t int_type;
typedef char ext_type;
typedef __enc_traits enc_type;
typedef codecvt&lt;int_type, ext_type, enc_type&gt; unicode_codecvt;
typedef codecvt_base::result result;
typedef unsigned short unicode_t;
typedef unicode_t int_type;
typedef char ext_type;
typedef __enc_traits enc_type;
typedef codecvt&lt;int_type, ext_type, enc_type&gt; unicode_codecvt;
const ext_type* e_lit = "black pearl jasmine tea";
int size = strlen(e_lit);
int_type i_lit_base[24] =
const ext_type* e_lit = "black pearl jasmine tea";
int size = strlen(e_lit);
int_type i_lit_base[24] =
{ 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
25856, 24832, 2560
};
const int_type* i_lit = i_lit_base;
const int_type* i_lit = i_lit_base;
const ext_type* efrom_next;
const int_type* ifrom_next;
ext_type* e_arr = new ext_type[size + 1];
ext_type* eto_next;
int_type* i_arr = new int_type[size + 1];
int_type* ito_next;
ext_type* e_arr = new ext_type[size + 1];
ext_type* eto_next;
int_type* i_arr = new int_type[size + 1];
int_type* ito_next;
// construct a locale object with the specialized facet.
locale loc(locale::classic(), new unicode_codecvt);
locale loc(locale::classic(), new unicode_codecvt);
// sanity check the constructed locale has the specialized facet.
VERIFY( has_facet&lt;unicode_codecvt&gt;(loc) );
const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(loc);
@ -414,70 +453,80 @@ codecvt usage.
unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
initialize_state(state01);
result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
i_arr, i_arr + size, ito_next);
i_arr, i_arr + size, ito_next);
VERIFY( r1 == codecvt_base::ok );
VERIFY( !int_traits::compare(i_arr, i_lit, size) );
VERIFY( efrom_next == e_lit + size );
VERIFY( ito_next == i_arr + size );
</pre>
<li>
b. conversions involving std::string
<li>
c. conversions involving std::filebuf and std::ostream
</li>
<li>
b. conversions involving std::string
</li>
<li>
c. conversions involving std::filebuf and std::ostream
</li>
</ul>
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/codecvt_char_char.cc
<li> testsuite/22_locale/codecvt_unicode_wchar_t.cc
<li> testsuite/22_locale/codecvt_unicode_char.cc
<li> testsuite/22_locale/codecvt_wchar_t_char.cc
<li> testsuite/22_locale/codecvt_char_char.cc </li>
<li> testsuite/22_locale/codecvt_unicode_wchar_t.cc </li>
<li> testsuite/22_locale/codecvt_unicode_char.cc </li>
<li> testsuite/22_locale/codecvt_wchar_t_char.cc </li>
</ul>
<p>
<h2>
7. Unresolved Issues
</h2>
<ul>
<li>
a. things that are sketchy, or remain unimplemented:
do_encoding, max_length and length member functions
are only weakly implemented. I have no idea how to do
this correctly, and in a generic manner. Nathan?
a. things that are sketchy, or remain unimplemented:
do_encoding, max_length and length member functions
are only weakly implemented. I have no idea how to do
this correctly, and in a generic manner. Nathan?
</li>
<li>
b. conversions involving std::string
b. conversions involving std::string
<ul>
<li>
how should operators != and == work for string of
different/same encoding?
<ul>
<li>
how should operators != and == work for string of
different/same encoding?
</li>
<li>
what is equal? A byte by byte comparison or an
encoding then byte comparison?
<li>
conversions between narrow, wide, and unicode strings
</ul>
<li>
what is equal? A byte by byte comparison or an
encoding then byte comparison?
</li>
<li>
conversions between narrow, wide, and unicode strings
</li>
</ul>
</li>
<li>
c. conversions involving std::filebuf and std::ostream
<ul>
<li>
how to initialize the state object in a
standards-conformant manner?
c. conversions involving std::filebuf and std::ostream
<ul>
<li>
how to initialize the state object in a
standards-conformant manner?
</li>
<li>
how to synchronize the &quot;C&quot; and &quot;C++&quot;
conversion information?
<li>
how to synchronize the &quot;C&quot; and &quot;C++&quot;
conversion information?
</li>
<li>
wchar_t/char internal buffers and conversions between
internal/external buffers?
</ul>
<li>
wchar_t/char internal buffers and conversions between
internal/external buffers?
</li>
</ul>
</li>
</ul>
<p>
<h2>
8. Acknowledgments
</h2>
@ -485,7 +534,6 @@ Ulrich Drepper for the iconv suggestions and patient answering of
late-night questions, Jason Merrill for the template partial
specialization hints, language clarification, and wchar_t fixes.
<p>
<h2>
9. Bibliography / Referenced Documents
</h2>
@ -494,35 +542,44 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
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
</p>
<p>
Haible, Bruno, &quot;The Unicode HOWTO&quot; v0.18, 4 August 2000
ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
Khun, Markus, &quot;UTF-8 and Unicode FAQ for Unix/Linux&quot;
http://www.cl.cam.ac.uk/~mgk25/unicode.html
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html
</p>
</body>
</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>
<head>
<title>
Notes on the ctype implementation.
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<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>
<body>
<h1>
Notes on the ctype implementation.
</h1>
<I>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
</I>
</em>
<p>
<h2>
1. Abstract
</h2>
@ -21,13 +22,11 @@ prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
Woe is me.
</p>
<p>
<h2>
2. What the standard says
</h2>
<p>
<h2>
3. Problems with &quot;C&quot; ctype : global locales, termination.
</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
on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements.
</p>
<p>
<h2>
4. Design
</h2>
@ -48,24 +47,28 @@ The two required specializations are implemented as follows:
<code>
ctype&lt;char&gt;
</code>
</p>
<p>
This is simple specialization. Implementing this was a piece of cake.
</p>
<p>
<code>
ctype&lt;wchar_t&gt;
</code>
</p>
<p>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p>
<p>
Neither of these two required specializations deals with Unicode
characters. As such, libstdc++-v3 implements
</p>
<p>
<h2>
5. Examples
</h2>
@ -76,50 +79,47 @@ characters. As such, libstdc++-v3 implements
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/ctype_char_members.cc
<li> testsuite/22_locale/ctype_wchar_t_members.cc
<li> testsuite/22_locale/ctype_char_members.cc </li>
<li> testsuite/22_locale/ctype_wchar_t_members.cc </li>
</ul>
<p>
<h2>
6. Unresolved Issues
</h2>
<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.
what is know about this type?
<li> mask typedef in codecvt_base, argument types in codecvt.
what is know about this type? </li>
<li> why mask* argument in codecvt?
<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
this class?
<li> why mask* argument in codecvt? </li>
<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
this class? </li>
<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
somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt;
<li> rename abstract base class. See if just smash-overriding
is a better approach. Clarify, add sanity to naming.
<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
somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt; </li>
<li> rename abstract base class. See if just smash-overriding
is a better approach. Clarify, add sanity to naming. </li>
</ul>
<p>
<h2>
7. Acknowledgments
</h2>
Ulrich Drepper for patient answering of late-night questions, skeletal
examples, and C language expertise.
<p>
<h2>
8. Bibliography / Referenced Documents
</h2>
@ -128,23 +128,29 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html
</p>
</body>
</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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 22</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -16,33 +15,33 @@
<p>Chapter 22 deals with the C++ localization facilities.
</p>
<!-- 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.
-->
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">class locale</a>
<li><a href="#2">class codecvt</a>
<li><a href="#3">class ctype</a>
<li><a href="#4">class messages</a>
<li><a href="#5">Bjarne Stroustrup on Locales</a>
<li><a href="#6">Nathan Myers on Locales</a>
<li><a href="#7">Correct Transformations</a>
<li><a href="#1">class locale</a></li>
<li><a href="#2">class codecvt</a></li>
<li><a href="#3">class ctype</a></li>
<li><a href="#4">class messages</a></li>
<li><a href="#5">Bjarne Stroustrup on Locales</a></li>
<li><a href="#6">Nathan Myers on Locales</a></li>
<li><a href="#7">Correct Transformations</a></li>
</ul>
<!-- ####################################################### -->
<hr>
<hr />
<h2><a name="1">class locale</a></h2>
<p>Notes made during the implementation of locales can be found
<a href="locale.html">here</a>.
</p>
<hr>
<hr />
<h2><a name="2">class codecvt</a></h2>
<p>Notes made during the implementation of codecvt can be found
<a href="codecvt.html">here</a>.
@ -66,19 +65,19 @@
implementation-provided extended functionality are given.
</blockquote>
<hr>
<hr />
<h2><a name="3">class ctype</a></h2>
<p>Notes made during the implementation of ctype can be found
<a href="ctype.html">here</a>.
</p>
<hr>
<hr />
<h2><a name="4">class messages</a></h2>
<p>Notes made during the implementation of messages can be found
<a href="messages.html">here</a>.
</p>
<hr>
<hr />
<h2><a name="5">Stroustrup on Locales</a></h2>
<p>Dr. Bjarne Stroustrup has released a
<a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a>
@ -96,14 +95,14 @@
avoid it.
</em></blockquote>
<hr>
<hr />
<h2><a name="6">Nathan Myers on Locales</a></h2>
<p>An article entitled &quot;The Standard C++ Locale&quot; was
published in Dr. Dobb's Journal and can be found
<a href="http://www.cantrip.org/locale.html">here</a>.
</p>
<hr>
<hr />
<h2><a name="7">Correct Transformations</a></h2>
<!-- Jumping directly to here from chapter 21. -->
<p>A very common question on newsgroups and mailing lists is, &quot;How
@ -207,7 +206,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<title>
Notes on the locale implementation.
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<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>
<body>
<h1>
Notes on the locale implementation.
</h1>
<I>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I>
</em>
<p>
<h2>
1. Abstract Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
@ -22,14 +23,12 @@ class _Impl.
<p>
</p>
<p>
<h2>
2. What the standard says
See Chapter 22 of the standard.
</h2>
See Chapter 22 of the standard.
<p>
<h2>
3. Problems with &quot;C&quot; locales : global locales, termination.
</h2>
@ -40,7 +39,7 @@ design ontop of POSIX and other relevant stanards, which include the
Single Unix (nee X/Open.)
Because POSIX falls down so completely, portibility is an issue.
<p>
</p>
<h2>
4. Design
@ -74,7 +73,6 @@ Provides an index for looking up specific facets.
class _Impl
<p>
<h2>
5. Examples
</h2>
@ -85,43 +83,40 @@ class _Impl
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/ctype_char_members.cc
<li> testsuite/22_locale/ctype_wchar_t_members.cc
<li> testsuite/22_locale/ctype_char_members.cc </li>
<li> testsuite/22_locale/ctype_wchar_t_members.cc </li>
</ul>
<p>
<h2>
6. Unresolved Issues
</h2>
<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,
_S_global get initialized? Can named locales assume this
initialization has already taken place?
<li> locale initialization: at what point does _S_classic,
_S_global get initialized? Can named locales assume this
initialization has already taken place? </li>
<li> document how named locales error check when filling data
members. Ie, a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention?
<li> document how named locales error check when filling data
members. Ie, a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention? </li>
<li> explain how locale aliasing happens. When does "de_DE"
use "de" information? What is the rule for locales composed of
just an ISO language code (say, "de") and locales with both an
ISO language code and ISO country code (say, "de_DE").
<li> explain how locale aliasing happens. When does "de_DE"
use "de" information? What is the rule for locales composed of
just an ISO language code (say, "de") and locales with both an
ISO language code and ISO country code (say, "de_DE"). </li>
<li> what should non-required facet instantiations do? If the
generic implemenation is provided, then how to end-users
provide specializations?
<li> what should non-required facet instantiations do? If the
generic implemenation is provided, then how to end-users
provide specializations? </li>
</ul>
<p>
<h2>
7. Acknowledgments
</h2>
<p>
<h2>
8. Bibliography / Referenced Documents
</h2>
@ -130,20 +125,31 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. C
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
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>
<head>
<title>
Notes on the messages implementation.
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<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>
<body>
<h1>
Notes on the messages implementation.
</h1>
<I>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I>
</em>
<p>
<h2>
1. Abstract
</h2>
@ -23,7 +24,6 @@ equivalent to Java's java.text.MessageFormat .using either GNU gettext
or IEEE 1003.1-200 functions.
</p>
<p>
<h2>
2. What the standard says
</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>
during program execution.
<BLOCKQUOTE>
<blockquote>
22.2.7.1 - Template class messages [lib.locale.messages]
</BLOCKQUOTE>
</blockquote>
This class has three public member functions, which directly
correspond to three protected virtual member functions.
@ -45,51 +45,57 @@ The public member functions are:
<p>
<code>catalog open(const string&amp;, const locale&amp;) const</code>
</p>
<p>
<code>string_type get(catalog, int, int, const string_type&amp;) const</code>
</p>
<p>
<code>void close(catalog) const</code>
</p>
<p>
While the virtual functions are:
</p>
<p>
<code>catalog do_open(const string&amp;, const locale&amp;) const</code>
<BLOCKQUOTE>
<I>
</p>
<blockquote>
<em>
-1- Returns: A value that may be passed to get() to retrieve a
message, from the message catalog identified by the string name
according to an implementation-defined mapping. The result can be used
until it is passed to close(). Returns a value less than 0 if no such
catalog can be opened.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
<code>string_type do_get(catalog, int, int, const string_type&amp;) const</code>
<BLOCKQUOTE>
<I>
</p>
<blockquote>
<em>
-3- Requires: A catalog cat obtained from open() and not yet closed.
-4- Returns: A message identified by arguments set, msgid, and dfault,
according to an implementation-defined mapping. If no such message can
be found, returns dfault.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
<code>void do_close(catalog) const</code>
<BLOCKQUOTE>
<I>
</p>
<blockquote>
<em>
-5- Requires: A catalog cat obtained from open() and not yet closed.
-6- Effects: Releases unspecified resources associated with cat.
-7- Notes: The limit on such resources, if any, is implementation-defined.
</I>
</BLOCKQUOTE>
</em>
</blockquote>
<p>
<h2>
3. Problems with &quot;C&quot; messages: thread safety,
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
<code>catopen</code>, but not for others. Fortunately, it's not heavily
used and so only a minor irritant.
</p>
<p>
Second, by making the member functions <code>const</code>, it is
impossible to save state in them. Thus, storing away information used
in the 'open' member function for use in 'get' is impossible. This is
unfortunate.
</p>
<p>
The 'open' member function in particular seems to be oddly
@ -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
'open' member function, for instance. Quite murky and unclear, on
reflection.
</p>
<p>
Lastly, it seems odd that messages, which explicitly require code
conversion, don't use the codecvt facet. Because the messages facet
has only one template parameter, it is assumed that ctype, and not
codecvt, is to be used to convert between character sets.
</p>
<p>
It is implicitly assumed that the locale for the default message
string in 'get' is in the "C" locale. Thus, all source code is assumed
to be written in English, so translations are always from "en_US" to
other, explicitly named locales.
</p>
<p>
<h2>
4. Design and Implementation Details
</h2>
@ -145,35 +155,39 @@ dependent on the capabilities of the underlying operating system.
<p>
Three different mechanisms have been provided, selectable via
configure flags:
</p>
<ul>
<li> generic
<p>
This model does very little, and is what is used by default.
</p>
<li> generic
<p>
This model does very little, and is what is used by default.
</p>
</li>
<li> gnu
<p>
The gnu model is complete and fully tested. It's based on the
GNU gettext package, which is part of glibc. It uses the functions
<code>textdomain, bindtextdomain, gettext</code>
to implement full functionality. Creating message
catalogs is a relatively straight-forward process and is
lightly documented below, and fully documented in gettext's
distributed documentation.
</p>
<li> gnu
<p>
The gnu model is complete and fully tested. It's based on the
GNU gettext package, which is part of glibc. It uses the functions
<code>textdomain, bindtextdomain, gettext</code>
to implement full functionality. Creating message
catalogs is a relatively straight-forward process and is
lightly documented below, and fully documented in gettext's
distributed documentation.
</p>
</li>
<li> ieee_1003.1-200x
<p>
This is a complete, though untested, implementation based on
the IEEE standard. The functions
<code>catopen, catgets, catclose</code>
are used to retrieve locale-specific messages given the
appropriate message catalogs that have been constructed for
their use. Note, the script <code> po2msg.sed</code> that is part
of the gettext distribution can convert gettext catalogs into
catalogs that <code>catopen</code> can use.
</p>
<li> ieee_1003.1-200x
<p>
This is a complete, though untested, implementation based on
the IEEE standard. The functions
<code>catopen, catgets, catclose</code>
are used to retrieve locale-specific messages given the
appropriate message catalogs that have been constructed for
their use. Note, the script <code> po2msg.sed</code> that is part
of the gettext distribution can convert gettext catalogs into
catalogs that <code>catopen</code> can use.
</p>
</li>
</ul>
<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
message catalog. This simplifies calling conventions for the gnu
model.
</p>
<p>
The rest of this document discusses details of the GNU model.
</p>
<p>
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
bits of the "C" mask (ie <code>LC_ALL</code>) are set before retrieving
messages.
</p>
<p>
Making the message catalogs can be initially tricky, but become quite
simple with practice. For complete info, see the gettext
documentation. Here's an idea of what is required:
</p>
<ul>
<LI > Make a source file with the required string literals
that need to be translated. See
<code>intl/string_literals.cc</code> for an example.
<li> Make a source file with the required string literals
that need to be translated. See
<code>intl/string_literals.cc</code> for an example.
</li>
<p>
<li> Make initial catalog (see "4 Making the PO Template File"
from the gettext docs).
<p>
<code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
<p>
<li> Make language and country-specific locale catalogs.
<p>
<code>cp libstdc++.pot fr_FR.po</code>
<p>
<code>cp libstdc++.pot de_DE.po</code>
<li> Make initial catalog (see "4 Making the PO Template File"
from the gettext docs).
<p>
<code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
</p>
</li>
<li> Make language and country-specific locale catalogs.
<p>
<code>cp libstdc++.pot fr_FR.po</code>
</p>
<p>
<code>cp libstdc++.pot de_DE.po</code>
</p>
</li>
<p>
<li> Edit localized catalogs in emacs so that strings are
translated.
<p>
<code>emacs fr_FR.po</code>
<p>
<li> Make the binary mo files.
<p>
<code>msgfmt fr_FR.po -o fr_FR.mo</code>
<p>
<code>msgfmt de_DE.po -o de_DE.mo</code>
<li> Edit localized catalogs in emacs so that strings are
translated.
<p>
<code>emacs fr_FR.po</code>
</p>
</li>
<li> Make the binary mo files.
<p>
<code>msgfmt fr_FR.po -o fr_FR.mo</code>
</p>
<p>
<code>msgfmt de_DE.po -o de_DE.mo</code>
</p>
</li>
<p>
<li> Copy the binary files into the correct directory structure.
<p>
<code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code>
<p>
<code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code>
<li> Copy the binary files into the correct directory structure.
<p>
<code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code>
</p>
<p>
<code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code>
</p>
</li>
<p>
<li> Use the new message catalogs.
<p>
<code>locale loc_de("de_DE");</code>
<p>
<code>
use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
</code>
<li> Use the new message catalogs.
<p>
<code>locale loc_de("de_DE");</code>
</p>
<p>
<code>
use_facet&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
</code>
</p>
</li>
</ul>
<p>
<h2>
5. Examples
</h2>
<ul>
<li> message converting, simple example using the GNU model.
<li> message converting, simple example using the GNU model.
<pre>
#include &lt;iostream&gt;
@ -276,82 +304,87 @@ void test01()
mssg_de.close(cat_de);
}
</pre>
</li>
</ul>
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/messages.cc
<li> testsuite/22_locale/messages_byname.cc
<li> testsuite/22_locale/messages_char_members.cc
<li> testsuite/22_locale/messages.cc </li>
<li> testsuite/22_locale/messages_byname.cc </li>
<li> testsuite/22_locale/messages_char_members.cc </li>
</ul>
<p>
<h2>
6. Unresolved Issues
</h2>
<ul>
<li> Things that are sketchy, or remain unimplemented:
<ul>
<li>_M_convert_from_char, _M_convert_to_char are in
flux, depending on how the library ends up doing
character set conversions. It might not be possible to
do a real character set based conversion, due to the
fact that the template parameter for messages is not
enough to instantiate the codecvt facet (1 supplied,
need at least 2 but would prefer 3).
<li> Things that are sketchy, or remain unimplemented:
<ul>
<li>_M_convert_from_char, _M_convert_to_char are in
flux, depending on how the library ends up doing
character set conversions. It might not be possible to
do a real character set based conversion, due to the
fact that the template parameter for messages is not
enough to instantiate the codecvt facet (1 supplied,
need at least 2 but would prefer 3).
</li>
<li> There are issues with gettext needing the global
locale set to extract a message. This dependence on
the global locale makes the current "gnu" model non
MT-safe. Future versions of glibc, ie glibc 2.3.x will
fix this, and the C++ library bits are already in
place.
</ul>
<p>
<li> Development versions of the GNU "C" library, glibc 2.3 will allow
a more efficient, MT implementation of std::messages, and will
allow the removal of the _M_name_messages data member. If this
is done, it will change the library ABI. The C++ parts to
support glibc 2.3 have already been coded, but are not in use:
once this version of the "C" library is released, the marked
parts of the messages implementation can be switched over to
the new "C" library functionality.
<p>
<li> There are issues with gettext needing the global
locale set to extract a message. This dependence on
the global locale makes the current "gnu" model non
MT-safe. Future versions of glibc, ie glibc 2.3.x will
fix this, and the C++ library bits are already in
place.
</li>
</ul>
</li>
<li> Development versions of the GNU "C" library, glibc 2.3 will allow
a more efficient, MT implementation of std::messages, and will
allow the removal of the _M_name_messages data member. If this
is done, it will change the library ABI. The C++ parts to
support glibc 2.3 have already been coded, but are not in use:
once this version of the "C" library is released, the marked
parts of the messages implementation can be switched over to
the new "C" library functionality.
</li>
<li> At some point in the near future, std::numpunct will probably use
std::messages facilities to implement truename/falename
correctly. This is currently not done, but entries in
libstdc++.pot have already been made for "true" and "false"
string literals, so all that remains is the std::numpunct
coding and the configure/make hassles to make the installed
library search its own catalog. Currently the libstdc++.mo
catalog is only searched for the testsuite cases involving
messages members.
std::messages facilities to implement truename/falename
correctly. This is currently not done, but entries in
libstdc++.pot have already been made for "true" and "false"
string literals, so all that remains is the std::numpunct
coding and the configure/make hassles to make the installed
library search its own catalog. Currently the libstdc++.mo
catalog is only searched for the testsuite cases involving
messages members.
</li>
<p>
<li> The following member functions:
<li> The following member functions:
<p>
<code>
<p>
<code>
catalog
open(const basic_string&lt;char&gt;&amp; __s, const locale&amp; __loc) const
</code>
</code>
</p>
<p>
<code>
catalog
open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
</code>
<p>
<code>
catalog
open(const basic_string&lt;char&gt;&amp;, const locale&amp;, const char*) const;
</code>
</p>
<p>
Don't actually return a "value less than 0 if no such catalog
can be opened" as required by the standard in the "gnu"
model. As of this writing, it is unknown how to query to see
if a specified message catalog exists using the gettext
package.
<p>
Don't actually return a "value less than 0 if no such catalog
can be opened" as required by the standard in the "gnu"
model. As of this writing, it is unknown how to query to see
if a specified message catalog exists using the gettext
package.
</p>
</li>
</ul>
<p>
<h2>
7. Acknowledgments
</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.
<p>
<h2>
8. Bibliography / Referenced Documents
</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
draft document describing the design of glibc 2.3 MT locale
functionality.
</p>
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In
particular, java.util.Properties, java.text.MessageFormat,
java.util.Locale, java.util.ResourceBundle.
http://java.sun.com/j2se/1.3/docs/api
</p>
<p>
System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
In particular see lines 5268-5427.
http://www.opennc.org/austin/docreg.html
</p>
<p> GNU gettext tools, version 0.10.38, Native Language Support
Library and Tools.
http://sources.redhat.com/gettext
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales,
Advanced Programmer's Guide and Reference, Addison Wesley Longman,
Inc. 2000. See page 725, Internationalized Messages.
</p>
<p>
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 23</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -18,19 +17,19 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Making code unaware of the container/array difference</a>
<li><a href="#2">Variable-sized bitmasks</a>
<li><a href="#3">Containers and multithreading</a>
<li><a href="#4">&quot;Hinting&quot; during insertion</a>
<li><a href="#5">Bitmasks and string arguments</a>
<li><a href="#6"><code>std::list::size()</code> is O(n)!</a>
<li><a href="#7">Space overhead management for vectors</a>
<li><a href="#1">Making code unaware of the container/array difference</a></li>
<li><a href="#2">Variable-sized bitmasks</a></li>
<li><a href="#3">Containers and multithreading</a></li>
<li><a href="#4">&quot;Hinting&quot; during insertion</a></li>
<li><a href="#5">Bitmasks and string arguments</a></li>
<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>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -65,9 +64,10 @@
code size or execution time.
</p>
<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>
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
client code.
</p>
@ -86,19 +86,21 @@
give the extra three lines and avoid confusion.
</p>
<p>Second, the line
<pre>
</p>
<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>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="2">Variable-sized bitmasks</a></h2>
<p>No, you cannot write code of the form
</p>
<!-- Careful, the leading spaces in PRE show up directly. -->
<pre>
<pre>
#include &lt;bitset&gt;
void foo (size_t n)
@ -106,19 +108,19 @@
std::bitset&lt;n&gt; bits;
....
} </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
<em>is</em> a feature.)
</p>
<p>There are a couple of ways to handle this kind of thing. Please
consider all of them before passing judgement. They include, in
no particular order:
<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>
<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
<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
@ -192,7 +194,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="3">Containers and multithreading</a></h2>
<p>This section discusses issues surrounding the design of
multithreaded applications which use Standard C++ containers.
@ -204,14 +206,14 @@
multithreading as it relates to libstdc++, including details on
the proper compilation of threaded code (and compatibility between
threaded and non-threaded code), see Chapter 17.
</p>
</p>
<p>Two excellent pages to read when working with the Standard C++
containers and threads are
<a href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
http://www.sgi.com/tech/stl/thread_safety.html</a> and
<a href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
http://www.sgi.com/tech/stl/Allocators.html</a>.
</p>
</p>
<p><em>However, please ignore all discussions about the user-level
configuration of the lock implementation inside the STL
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
longer be done unless you really know what you are doing and
assume all responsibility.</em>
</p>
</p>
<p>Since the container implementation of libstdc++-v3 uses the SGI
code, we use the same definition of thread safety as SGI when
discussing design. A key point that beginners may miss is the
@ -235,7 +237,7 @@
element is constructed uses an internal lock obtained and
released solely within libstdc++-v3 code (in fact, this is the
reason STL requires any knowledge of the thread configuration).
</p>
</p>
<p>For implementing a container which does its own locking, it is
trivial to provide a wrapper class which obtains the lock (as
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
support multi-threading, then please consult all commentary in
include/bits/stl_alloc.h and the allocators link below.
<blockquote>
</p>
<blockquote>
<p>(Explicit warning since so many people get confused while
attempting this:)
</p>
@ -271,8 +274,8 @@
one-definition rule of C/C++ and you might cause yourself untold
problems.
</p>
</blockquote>
If you find any platform where gcc reports a
</blockquote>
<p>If you find any platform where gcc reports a
threading model other than single, and where libstdc++-v3 builds
a buggy container allocator when used with threads unless you
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>.
</p>
<hr>
<hr />
<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
for all of the associative containers (map, set, etc):
<pre>
</p>
<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
pointing to where the insert should start to search,&quot; but
specifies nothing more. (LWG Issue #233, currently in review,
@ -321,23 +325,26 @@
their new meanings in the next paragraph. *grin*
</p>
<p>If the <code>hint</code> parameter ('p' above) is equivalent to:
</p>
<ul>
<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
be inserted at the beginning of the container, becoming the new
entry at <code>begin()</code>.
</li>
<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
be inserted at the end of the container, becoming the new entry
at <code>end()</code>.
</li>
<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
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
item preceding <code>h</code>. The new item will be inserted
between <code>h</code> and <code>h</code>'s predecessor.
</li>
</ul>
</p>
<p>For <code>multimap</code> and <code>multiset</code>, the restrictions are
slightly looser: &quot;greater than&quot; should be replaced by
&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>.
</p>
<hr>
<hr />
<h2><a name="5">Bitmasks and string arguments</a></h2>
<p>Bitmasks do not take char* nor const char* arguments in their
constructors. This is something of an accident, but you can read
@ -383,6 +390,7 @@
</p>
<p>For now you can simply make a temporary string object using the
constructor expression:
</p>
<pre>
std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) );
</pre>
@ -390,17 +398,17 @@
<pre>
std::bitset&lt;5&gt; b ( &quot;10110&quot; ); // invalid
</pre>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
we imported SGI's STL implementation. The following is quoted from
<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
proportional to the number of elements in the list. This was a
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.
</p>
<p>One implication of linear time size(): you should never write
</p>
<pre>
if (L.size() == 0)
...</pre>
@ -426,15 +435,13 @@
<pre>
if (L.empty())
...</pre>
</p>
</blockquote>
</p>
</blockquote>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<h2><a name="7">Space overhead management for vectors</h2>
<hr />
<h2><a name="7">Space overhead management for vectors</a></h2>
<p>In
<a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this
message to the list</a>, Daniel Kostecky announced work on an
@ -457,7 +464,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 24</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -19,14 +18,14 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">They ain't pointers!</a>
<li><a href="#2">It ends <em>where?</em></a>
<li><a href="#1">They ain't pointers!</a></li>
<li><a href="#2">It ends <em>where?</em></a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -67,41 +66,46 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="2">It ends <em>where?</em></a></h2>
<p>This starts off sounding complicated, but is actually very easy,
especially towards the end. Trust me.
</p>
</p>
<p>Beginners usually have a little trouble understand the whole
'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.
</p>
<p>First, some history, and a reminder of some of the funkier rules in
C and C++ for builtin arrays. The following rules have always been
true for both languages:
<ol>
<li>You can point anywhere in the array, <em>or to the first element
past the end of the array</em>. A pointer that points to one
past the end of the array is guaranteed to be as unique as a
pointer to somewhere inside the array, so that you can compare
such pointers safely.
<li>You can only dereference a pointer that points into an array.
If your array pointer points outside the array -- even to just
one past the end -- and you dereference it, Bad Things happen.
<li>Strictly speaking, simply pointing anywhere else invokes
undefined behavior. Most programs won't puke until such a
pointer is actually dereferenced, but the standards leave that
up to the platform.
</ol>
The reason this past-the-end addressing was allowed is to make it
</p>
<ol>
<li>You can point anywhere in the array, <em>or to the first element
past the end of the array</em>. A pointer that points to one
past the end of the array is guaranteed to be as unique as a
pointer to somewhere inside the array, so that you can compare
such pointers safely.
</li>
<li>You can only dereference a pointer that points into an array.
If your array pointer points outside the array -- even to just
one past the end -- and you dereference it, Bad Things happen.
</li>
<li>Strictly speaking, simply pointing anywhere else invokes
undefined behavior. Most programs won't puke until such a
pointer is actually dereferenced, but the standards leave that
up to the platform.
</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.,
while (*d++ = *s++);.
</p>
<p>So, when you think of two pointers delimiting an array, don't think
of them as indexing 0 through n-1. Think of them as <em>boundary
markers</em>:
<pre>
</p>
<pre>
beginning end
| |
@ -121,8 +125,8 @@
| | dereference 'end'.
beginning end
</pre>
See? Everything between the boundary markers is part of the array.
</pre>
<p>See? Everything between the boundary markers is part of the array.
Simple.
</p>
<p>Now think back to your junior-high school algebra course, when you
@ -171,7 +175,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 25</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -19,14 +18,14 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Prerequisites</a>
<li><a href="#2">Special <code>swap</code>s</a>
<li><a href="#1">Prerequisites</a></li>
<li><a href="#2">Special <code>swap</code>s</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -34,16 +33,18 @@
<p>The neatest accomplishment of the algorithms chapter is that all the
work is done via iterators, not containers directly. This means two
important things:
<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>
<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
string class has specialized versions of many of these functions (for
example, <code>string::find()</code>). Most of the examples on this
@ -67,7 +68,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
containers, then the call will automatically be replaced by a call to
@ -90,7 +91,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 26</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -15,29 +14,32 @@
<p>Chapter 26 deals with building block abstractions to aid in
numerical computing:
<ul>
<li>Template data structures such as <code>valarray&lt;&gt;</code>
and <code>complex&lt;&gt;</code>.
<li>Template numerical functions such as <code>accumulate</code>,
<code>inner_product</code>, <code>partial_sum</code>, and
<code>adjacent_difference</code>.
</ul>
All of the Standard C math functions are of course included in C++,
</p>
<ul>
<li>Template data structures such as <code>valarray&lt;&gt;</code>
and <code>complex&lt;&gt;</code>.
</li>
<li>Template numerical functions such as <code>accumulate</code>,
<code>inner_product</code>, <code>partial_sum</code>, and
<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
<code>long double</code> have been added for all of them.
</p>
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Complex Number Processing</a>
<li><a href="#2">Array Processing</a>
<li><a href="#3">Numerical Functions</a>
<li><a href="#4">C99</a>
<li><a href="#1">Complex Number Processing</a></li>
<li><a href="#2">Array Processing</a></li>
<li><a href="#3">Numerical Functions</a></li>
<li><a href="#4">C99</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -62,7 +64,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="2">Array Processing</a></h2>
<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
@ -87,22 +89,23 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="3">Numerical Functions</a></h2>
<p>There are four generalized functions in the &lt;numeric&gt; header
that follow the same conventions as those in &lt;algorithm&gt;. Each
of them is overloaded: one signature for common default operations,
and a second for fully general operations. Their names are
self-explanatory to anyone who works with numerics on a regular basis:
<ul>
<li><code>accumulate</code>
<li><code>inner_product</code>
<li><code>partial_sum</code>
<li><code>adjacent_difference</code>
</ul>
</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>.
<pre>
</p>
<pre>
int ar[50];
int someval = somefunction();
@ -111,8 +114,8 @@
int sum = std::accumulate(ar,ar+50,0);
int sum_stuff = std::accumulate(ar,ar+50,someval);
int product = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
</pre>
The first call adds all the members of the array, using zero as an
</pre>
<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
<code>someval</code> as the starting value (thus, <code>sum_stuff == sum +
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>.
</p>
<hr>
<hr />
<h2><a name="4">C99</a></h2>
<p>In addition to the other topics on this page, we'll note here some
of the C99 features that appear in libstdc++-v3.
@ -151,7 +154,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Chapter 27</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -19,20 +18,20 @@
<!-- ####################################################### -->
<hr>
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Copying a file</a>
<li><a href="#2">The buffering is screwing up my program!</a>
<li><a href="#3">Binary I/O</a>
<li><a href="#5">What is this &lt;sstream&gt;/stringstreams thing?</a>
<li><a href="#6">Deriving a stream buffer</a>
<li><a href="#7">More on binary I/O</a>
<li><a href="#8">Pathetic performance? Ditch C.</a>
<li><a href="#9">Threads and I/O</a>
<li><a href="#1">Copying a file</a></li>
<li><a href="#2">The buffering is screwing up my program!</a></li>
<li><a href="#3">Binary I/O</a></li>
<li><a href="#5">What is this &lt;sstream&gt;/stringstreams thing?</a></li>
<li><a href="#6">Deriving a stream buffer</a></li>
<li><a href="#7">More on binary I/O</a></li>
<li><a href="#8">Pathetic performance? Ditch C.</a></li>
<li><a href="#9">Threads and I/O</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -40,27 +39,29 @@
<p>So you want to copy a file quickly and easily, and most important,
completely portably. And since this is C++, you have an open
ifstream (call it IN) and an open ofstream (call it OUT):
<pre>
</p>
<pre>
#include &lt;fstream&gt;
std::ifstream IN ("input_file");
std::ofstream OUT ("output_file"); </pre>
</p>
<p>Here's the easiest way to get it completely wrong:
<pre>
</p>
<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
create a simple text file called &quot;input_file&quot; containing
the sentence
</p>
<pre>
The quick brown fox jumped over the lazy dog.</pre>
surrounded by blank lines. Code it up and try it. The contents
The quick brown fox jumped over the lazy dog.</pre>
<p>surrounded by blank lines. Code it up and try it. The contents
of &quot;output_file&quot; may surprise you.
</p>
<p>Seriously, go do it. Get surprised, then come back. It's worth it.
</p>
<hr width="60%">
<hr width="60%" />
<p>The thing to remember is that the <code>basic_[io]stream</code> classes
handle formatting, nothing else. In particular, they break up on
whitespace. The actual reading, writing, and storing of data is
@ -76,9 +77,9 @@
as well as the streams themselves. The pointer is easily retrieved
using the <code>rdbuf()</code> member function. Therefore, the easiest
way to copy the file is:
<pre>
OUT &lt;&lt; IN.rdbuf();</pre>
</p>
<pre>
OUT &lt;&lt; IN.rdbuf();</pre>
<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.
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
address (quite a big surprise). Others don't compile at all.
</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
basic_ostream class and are therefore available with all possible
descendents.
@ -98,7 +99,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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.
@ -122,35 +123,38 @@
is the effect you want when writing to a screen -- get the text
out as soon as possible, etc -- but the buffering is largely
wasted when doing this to a file:
<pre>
</p>
<pre>
output &lt;&lt; &quot;a line of text&quot; &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>
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.
If you need a newline, just write a newline:
<pre>
</p>
<pre>
output &lt;&lt; &quot;a line of text\n&quot;
&lt;&lt; some_data_variable &lt;&lt; '\n'
&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
the start of the quoted text on the thing line, for example.
</p>
<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
yourself:
<pre>
</p>
<pre>
output &lt;&lt; ...... &lt;&lt; flush; // can use std::flush manipulator
output.flush(); // or call a member fn </pre>
</p>
<p>On the other hand, there are times when writing to a file should
be like writing to standard error; no buffering should be done
because the data needs to appear quickly (a prime example is a
log file for security-related information). The way to do this is
just to turn off the buffering <em>before any I/O operations at
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::ifstream is (&quot;/qux/quux/quuux&quot;);
int i;
@ -160,7 +164,6 @@
...
os &lt;&lt; &quot;this data is written immediately\n&quot;;
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
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
@ -189,7 +192,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="3">Binary I/O</a></h2>
<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
@ -234,25 +237,28 @@
of <em>formatting</em> functions and classes to perform something
which <em>requires</em> that formatting not be done? There are a
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>
<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
document (at least for now), but while streambufs go a long way,
they still leave a couple of things up to you, the programmer.
@ -287,7 +293,7 @@
made are good ones.)
</p>
<hr>
<hr />
<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>)
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
<code>&lt;&lt;</code>/<code>&gt;&gt;</code> functions correctly, though,
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
file streams, but with nothing else -- including stringstreams.
</p>
@ -324,7 +330,7 @@
support them, and 2) if you use them, people will laugh at you.
</p>
<hr>
<hr />
<h2><a name="6">Deriving a stream buffer</a></h2>
<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
@ -339,7 +345,8 @@
transforms everything sent through it to uppercase. This version
assumes many things about the nature of the character type being
used (for more information, read the books or the newsgroups):
<pre>
</p>
<pre>
#include &lt;iostream&gt;
#include &lt;streambuf&gt;
#include &lt;locale&gt;
@ -377,11 +384,11 @@
return 0;
}
</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>.
</p>
<hr>
<hr />
<h2><a name="7">More on binary I/O</a></h2>
<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
@ -406,22 +413,23 @@
a portable binary format.
</p>
<hr>
<hr />
<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.
I'm just saying it to get your attention.
</p>
<p>Because the C++ library includes the C library, both C-style and
C++-style I/O have to work at the same time. For example:
<pre>
</p>
<pre>
#include &lt;iostream&gt;
#include &lt;cstdio&gt;
std::cout &lt;&lt; &quot;Hel&quot;;
std::printf (&quot;lo, worl&quot;);
std::cout &lt;&lt; &quot;d!\n&quot;;
</pre>
This must do what you think it does.
</pre>
<p>This must do what you think it does.
</p>
<p>Alert members of the audience will immediately notice that buffering
is going to make a hash of the output unless special steps are taken.
@ -440,12 +448,12 @@
when both libraries' facilities are in use. If your program only uses
C++ I/O, then there's no need to sync with the C streams. The right
thing to do in this case is to call
<pre>
</p>
<pre>
#include <em>any of the I/O headers such as ios, iostream, etc</em>
std::ios::sync_with_stdio(false);
</pre>
</p>
</pre>
<p>You must do this before performing any I/O via the C++ stream objects.
Once you call this, the C++ streams will operate independently of the
(unused) C streams. For GCC 3.x, this means that <code>cout</code> and
@ -459,7 +467,7 @@
buffered.
</p>
<hr>
<hr />
<h2><a name="9">Threads and I/O</a></h2>
<p>I'll assume that you have already read the
<a href="../17_intro/howto.html#3">general notes on library threads</a>,
@ -548,7 +556,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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 '/endlist/,$$p' $@ > tmp.bottom
echo ' <ul>' > tmp.middle
for i in [[:digit:]]*/howto.html; do \
for i in [0-9]*/howto.html; do \
title=`grep 'h1 ' $$i |\
sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\
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>
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++">
<meta name="DESCRIPTION" content="Configuration options for libstdc++-v3.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="Configuration options for libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 configure options</title>
<link rel="StyleSheet" href="lib3styles.css">
<link rel="StyleSheet" href="lib3styles.css" />
</head>
<body>
@ -19,10 +18,10 @@ options</a></h1>
</p>
<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.
Keep in mind that
<!-- This SECnn should be the "Choosing Package Options" section. -->
@ -37,15 +36,16 @@ options</a></h1>
</p>
<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
compilers. As such, targets like &quot;powerpc-elf&quot; will have
libstdc++ built many different ways: &quot;-msoft-float&quot;
and not, etc. A different libstdc++ will be built for each of
the different multilib versions. This option is on by default.
</p>
</dd>
<dt><code>--enable-debug </code>
<dt><code>--enable-debug </code></dt>
<dd><p>The configure script will automatically detect the highest
level of optimization that the compiler in use can use.
This --enable flag will disable all optimizations and instruct
@ -55,13 +55,15 @@ options</a></h1>
configuration difference:
<code>make CXXFLAGS='-g -O0' all</code>
</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>
(described next).
</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
snapshot 3.0.96, the choices are 'libio' to specify the GNU
I/O package (from
@ -70,32 +72,36 @@ options</a></h1>
abstraction. The default is 'stdio'. A longer explanation
is <a href="explanations.html#cstdio">here</a>.
</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
at all possible, the new, frame unwinding exception handling routines
should be used instead, as they significantly reduce both runtime
memory usage and executable size.
</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>
(described next).
</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
choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix
(IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets,
'gnu' to specify a model based on functionality from the GNU C
library (langinfo/iconv/gettext) (from <A
library (langinfo/iconv/gettext) (from <a
href="http://sources.redhat.com/glibc/">glibc</a>, the GNU C
library), or 'generic' to use a generic &quot;C&quot;
abstraction which consists of &quot;C&quot; locale info. The
default is 'generic'.
</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
with many other functions for wide characters, and math
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
necessary.
</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
provided as a GNU extension to C++98 in g++. This flag builds
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
CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
</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
used. Options are: c, c_std, and c_shadow. These correspond
to the source directory's include/c, include/c_std, and
include/c_shadow directories. The default is c_std.
</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>
(described next).
</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
general <a href="http://gcc.gnu.org/install/configure.html">compiler
configuration instructions</a>.
</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
compiler-specific subdirectory (i.e.,
<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
@ -151,17 +162,18 @@ options</a></h1>
unless you also specify
<code>--with-gxx-include-dir=<em>dirname</em></code> during configuration.
</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,
the following puts all the libstdc++ headers into a directory
called &quot;2.97-20001008&quot; instead of the usual
&quot;g++-v3&quot;.
</p>
<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)
flags to the compiler to use when building libstdc++. FLAGS
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++
mailing list) if you discover more!
</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
character conversion support. This is tricky and currently
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
ISO. By default, this option is on.
</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
library templates, in the form of specialized templates,
<a href="19_diagnostics/howto.html#3">described here</a>. They
can help users discover when they break the rules of the STL, before
their programs run.
</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
shared library has been requested). The only 'style' currently
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
on. Hopefully people will volunteer to do other 'style' options.
</p>
</dd>
</dl>
<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>.
@ -222,7 +238,7 @@ options</a></h1>
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<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>
<link rel="StyleSheet" href="lib3styles.css">
<link rel="StyleSheet" href="lib3styles.css" />
</head>
<body>
@ -15,40 +14,40 @@
automatically-generated source documentation, available separately.
</p>
<hr />
<br>
<br />
<h2><a name="1">Introduction</a></h2>
<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.
</p>
<ul>
<li><a href="17_intro/COPYING">License</a>
- GPL v2 license terms
<li><a href="abi.txt">ABI Policy and Guidelines</a>
<li><a href="17_intro/BUGS">BUGS</a>
- GPL v2 license terms</li>
<li><a href="abi.txt">ABI Policy and Guidelines</a></li>
<li><a href="17_intro/BUGS">BUGS</a></li>
<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
of the web pages. Punt. -->
<li>README - directory structure
<li>README - directory structure</li>
<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>
- tasks yet undone
- tasks yet undone</li>
</ul>
<hr />
<br>
<br />
<h2><a name="2">Configuring, Building, Installing</a></h2>
<ul>
<li><a href="configopts.html">Configure options</a>
<li><a href="install.html">Getting started: configure, build, install</a>
</ul>
<ul>
<li><a href="configopts.html">Configure options</a></li>
<li><a href="install.html">Getting started: configure, build, install</a>
</li>
</ul>
<hr />
<br>
<br />
<h2><a name="4">Source-Level Documentation</a></h2>
<p>The library sources have been specially formatted so that with the
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
file, looking at inheritance diagrams, etc.
</p>
<p>The Source-Level documentation can be viewed online:
<ul>
<p>The Source-Level documentation can be viewed online:</p>
<ul>
<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>
<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)
</ul>
</li>
</ul>
<p>This generated HTML collection, as above, is also available for download in
the libstdc++ snapshots directory at
<code>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/&gt;</code>.
@ -81,7 +83,7 @@
<hr />
<br>
<br />
<h2><a name="3">Chapter-Specific Documentation</a></h2>
<p>Information, extensions, notes and advice on specific implementation
capabilites and/or liabilities broken down into chapter names based on the
@ -95,7 +97,7 @@
-->
<!-- beginlist -->
<ul>
<li>Library Introduction (Chapter 17)</li>
<li>Library Introduction (Chapter 17)
<ul>
<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>
@ -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#6">Preprocessor macros controlling the library</a></li>
</ul>
</li>
<li>Library Support (Chapter 18)</li>
<li>Library Support (Chapter 18)
<ul>
<li><a href="18_support/howto.html#1">Types</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#5">RTTI, the ABI, and demangling</a></li>
</ul>
</li>
<li>Diagnostics (Chapter 19)</li>
<li>Diagnostics (Chapter 19)
<ul>
<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#3">Concept checkers -- <strong>new and improved!</strong></a></li>
<li><a href="19_diagnostics/howto.html#4">Verbose <code>terminate</code></a></li>
</ul>
</li>
<li>General Utilities (Chapter 20)</li>
<li>General Utilities (Chapter 20)
<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#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#4">Pairs</a></li>
</ul>
</li>
<li>Strings (Chapter 21)</li>
<li>Strings (Chapter 21)
<ul>
<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>
@ -138,19 +144,21 @@
<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>
</ul>
</li>
<li>Localization (Chapter 22)</li>
<li>Localization (Chapter 22)
<ul>
<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#3">class ctype</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#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>
</ul>
</li>
<li>Containers (Chapter 23)</li>
<li>Containers (Chapter 23)
<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#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#7">Space overhead management for vectors</a></li>
</ul>
</li>
<li>Iterators (Chapter 24)</li>
<li>Iterators (Chapter 24)
<ul>
<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>
</ul>
</li>
<li>Algorithms (Chapter 25)</li>
<li>Algorithms (Chapter 25)
<ul>
<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>
</ul>
</li>
<li>Numerics (Chapter 26)</li>
<li>Numerics (Chapter 26)
<ul>
<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#3">Numerical Functions</a></li>
<li><a href="26_numerics/howto.html#4">C99</a></li>
</ul>
</li>
<li>Input/Output (Chapter 27)</li>
<li>Input/Output (Chapter 27)
<ul>
<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>
@ -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#9">Threads and I/O</a></li>
</ul>
</li>
<li>Extensions to the Standard Library</li>
<li>Extensions to the Standard Library
<ul>
<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>
@ -202,27 +215,28 @@
<li><a href="ext/howto.html#4">Compile-time checks</a></li>
<li><a href="ext/howto.html#5">LWG Issues</a></li>
</ul>
</li>
</ul>
<!-- endlist -->
<hr />
<br>
<br />
<h2><a name="5">Contributor-Specific Information</a></h2>
<ul>
<li><a href="17_intro/contribute.html">Contributor checklist</a>
<li><a href="17_intro/libstdc++-assign.txt">Copyright assignment form for libstdc++-v3</a>
<li><a href="17_intro/BADNAMES">BADNAMES</a>
- names to avoid because of potential collisions
<li><a href="17_intro/C++STYLE">C++STYLE</a>
- coding style by example
<li><a href="17_intro/CHECKLIST">CHECKLIST</a>
- a list of required features and their status.
<li><a href="17_intro/DESIGN">DESIGN</a>
- overview of the implementation plan
<li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a>
- header naming and sub-include structure
</ul>
<ul>
<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>
<li><a href="17_intro/BADNAMES">BADNAMES</a>
- names to avoid because of potential collisions</li>
<li><a href="17_intro/C++STYLE">C++STYLE</a>
- coding style by example</li>
<li><a href="17_intro/CHECKLIST">CHECKLIST</a>
- a list of required features and their status.</li>
<li><a href="17_intro/DESIGN">DESIGN</a>
- overview of the implementation plan</li>
<li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a>
- header naming and sub-include structure</li>
</ul>
<!-- ####################################################### -->

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

@ -1,12 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++">
<meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>Explanatory notes about libstdc++-v3 design</title>
<link rel="StyleSheet" href="lib3styles.css">
<link rel="StyleSheet" href="lib3styles.css" />
</head>
<body>
@ -19,11 +18,12 @@ design</a></h1>
</p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### -->
<hr>
<a name="cstdio"><h3>&quot;I/O packages&quot;, <code>--enable-cstdio</code></h3></a>
<hr />
<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
also includes all of the I/O capabilites of C. Making them work together
can be a challenge, not only
@ -61,8 +61,8 @@ design</a></h1>
</p>
<hr>
<a name="alloc"><h3>Internal Allocators</h3></a>
<hr />
<h3><a name="alloc">Internal Allocators</a></h3>
<p>
</p>
<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>
See <a href="17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
<meta name="DESCRIPTION" content="Notes for the libstdc++ extensions.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes for the libstdc++ extensions." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 HOWTO: Extensions</title>
<link rel="StyleSheet" href="../lib3styles.css">
<link rel="StyleSheet" href="../lib3styles.css" />
</head>
<body>
@ -18,45 +17,46 @@
and some just seemed to appear on the doorstep.
</p>
<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>
<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>
<ul>
<li><a href="#1">Ropes and trees and hashes, oh my!</a>
<li><a href="#2">Added members and types</a>
<li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a>
<li><a href="#6">Allocators (version 3.3)</a>
<li><a href="#4">Compile-time checks</a>
<li><a href="#5">LWG Issues</a>
<li><a href="#1">Ropes and trees and hashes, oh my!</a></li>
<li><a href="#2">Added members and types</a></li>
<li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a></li>
<li><a href="#6">Allocators (version 3.3)</a></li>
<li><a href="#4">Compile-time checks</a></li>
<li><a href="#5">LWG Issues</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
<h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
<p>The SGI headers
<pre>
<p>The SGI headers</p>
<pre>
&lt;bvector&gt;
&lt;hash_map&gt;
&lt;hash_set&gt;
&lt;rope&gt;
&lt;slist&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
available (it's actually a typedef for the specialization now).
<code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
@ -88,25 +88,25 @@
</p>
<p>Why would you want to use a hashing class instead of the
&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>
<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
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
unorganized a fashion. Some sort of hashing will undoubtedly be
included in a future Standard.
included in a future Standard.)
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="2">Added members and types</a></h2>
<p>Some of the classes in the Standard Library have additional
publicly-available members, and some classes are themselves not in
@ -114,29 +114,32 @@
for example, additional typedefs. Those won't be described here
(or anywhere else).
</p>
<p>
<ul>
<ul>
<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
longer actively maintained, we will try and keep this code working
ourselves.</li>
<li>3.0.x <code>filebuf</code>s have another ctor with this signature:<br>
<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
<li>3.0.x <code>filebuf</code>s have another ctor with this signature:
<br />
<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
descriptors, into the IOStream buffering classes. The three
arguments are as follows:
<ul>
<li><code>__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE
</li>
<li><code>ios_base::openmode M </code>
// same as all the other uses of openmode
</li>
<li><code>int_type B </code>
// buffer size, defaults to BUFSIZ if not specified
</li>
</ul>
For those wanting to use file descriptors instead of FILE*'s, I
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
back an old extension: the <code>fd()</code> member function. The
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,
so if you perform any I/O directly, don't expect the library to be
aware of it.
</li>
<li>Beginning with 3.1, the extra <code>filebuf</code> constructor and
the <code>fd()</code> function were removed from the standard
filebuf. Instead, <code>&lt;ext/stdio_filebuf.h&gt;</code> contains
a derived class called <code>__gnu_cxx::stdio_filebuf</code>.
</ul>
</p>
</li>
</ul>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<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
mess. Where to begin?
</p>
<h3>The Rules</h3>
<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
more memory to hold them, the container makes the request via its
<code>Allocator</code> template parameter. This includes adding
char's to the string class, which acts as a regular STL container
in this respect.
</li>
<li>The default <code>Allocator</code> of every container-of-T is
<code>std::allocator&lt;T&gt;</code>.
</li>
<li>The interface of the <code>allocator&lt;T&gt;</code> class is
extremely simple. It has about 20 public declarations (nested
typedefs, member functions, etc), but the two which concern us most
@ -180,13 +187,14 @@
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>not their total size</em>.
</li>
<li>&quot;The storage is obtained by calling
<code>::operator new(size_t)</code>, but it is unspecified when or
how often this function is called. The use of <code>hint</code>
is unspecified, but intended as an aid to locality if an
implementation so desires.&quot; [20.4.1.1]/6
</ul>
</p>
</li>
</ul>
<h3>Problems and Possibilities</h3>
<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
@ -235,33 +243,39 @@
information for maintainers and contributors in addition to users.
</p>
<p>These classes are always available:
<ul>
</p>
<ul>
<li><code>__new_alloc</code> simply wraps <code>::operator new</code>
and <code>::operator delete</code>.
</li>
<li><code>__malloc_alloc_template&lt;int inst&gt;</code> simply wraps
<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
elsewhere). The <code>inst</code> parameter is described below.
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
The Standard Allocator for instances of T. It uses the internal
<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
allocator, A, which itself is an allocator for instances of T.
This is primarily used in an internal &quot;allocator traits&quot;
class which helps encapsulate the different styles of allocators.
</li>
<li><code>__debug_alloc&lt;A&gt;</code> is also a wrapper around an
arbitrary allocator A. It passes on slightly increased size
requests to A, and uses the extra memory to store size information.
When a pointer is passed to <code>deallocate()</code>, the stored
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
allocator classes have a consistent yet non-standard interface.
Such classes can be changed to a conforming interface with this
wrapper: <code>__allocator&lt;T, __alloc&gt;</code> is thus the
same as <code>allocator&lt;T&gt;</code>.
</ul>
</p>
</li>
</ul>
<p>An internal typedef, <code> __mem_interface </code>, is defined to be
<code>__new_alloc</code> by default.
</p>
@ -297,15 +311,15 @@
<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
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>
<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>
<p>Depending on your application (a specific program, a generic library,
etc), allocator classes tend to be one of two styles: &quot;SGI&quot;
@ -326,12 +340,12 @@
(but nonportable)
method of specifying that only malloc/free should be used instead of
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>
Likewise, a debugging form of whichever allocator is currently in use:
<pre>
std::deque &lt;my_type, std::__debug_alloc&lt;std::__alloc&gt; &gt; debug_deque;</pre>
</p>
<h3><code>inst</code></h3>
<p>The <code>__malloc_alloc_template</code> and
<code>__default_alloc_template</code> classes take an integer parameter,
@ -339,11 +353,12 @@
</p>
<p>The point of the number is to allow multiple instantiations of the
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,1&gt; private;
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)
remains separate.
</p>
@ -365,7 +380,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="6">Allocators (version 3.3)</a></h2>
<p>Changes are coming...
</p>
@ -373,7 +388,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="4">Compile-time checks</a></h2>
<p>Currently libstdc++-v3 uses the concept checkers from the Boost
library to perform <a href="../19_diagnostics/howto.html#3">optional
@ -384,7 +399,7 @@
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr>
<hr />
<h2><a name="5">LWG Issues</a></h2>
<p>Everybody's got issues. Even the C++ Standard Library.
</p>
@ -418,134 +433,188 @@
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.
</p>
<p><dl>
<dl>
<dt><a href="lwg-defects.html#5">5</a>:
<em>string::compare specification questionable</em>
</dt>
<dd>This should be two overloaded functions rather than a single function.
</dd>
<dt><a href="lwg-defects.html#17">17</a>:
<em>Bad bool parsing</em>
</dt>
<dd>Apparently extracting Boolean values was messed up...
</dd>
<dt><a href="lwg-defects.html#22">22</a>:
<em>Member open vs flags</em>
</dt>
<dd>Re-opening a file stream does <em>not</em> clear the state flags.
</dd>
<dt><a href="lwg-defects.html#25">25</a>:
<em>String operator&lt;&lt; uses width() value wrong</em>
</dt>
<dd>Padding issues.
</dd>
<dt><a href="lwg-defects.html#48">48</a>:
<em>Use of non-existent exception constructor</em>
</dt>
<dd>An instance of <code>ios_base::failure</code> is constructed instead.
</dd>
<dt><a href="lwg-defects.html#49">49</a>:
<em>Underspecification of ios_base::sync_with_stdio</em>
</dt>
<dd>The return type is the <em>previous</em> state of synchronization.
</dd>
<dt><a href="lwg-defects.html#50">50</a>:
<em>Copy constructor and assignment operator of ios_base</em>
</dt>
<dd>These members functions are declared <code>private</code> and are
thus inaccessible. Specifying the correct semantics of
&quot;copying stream state&quot; was deemed too complicated.
</dd>
<dt><a href="lwg-defects.html#68">68</a>:
<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
[27.6.1.2.3]/7.
</dd>
<dt><a href="lwg-defects.html#74">74</a>:
<em>Garbled text for codecvt::do_max_length</em>
</dt>
<dd>The text of the standard was gibberish. Typos gone rampant.
</dd>
<dt><a href="lwg-defects.html#83">83</a>:
<em>string::npos vs. string::max_size()</em>
</dt>
<dd>Safety checks on the size of the string should test against
<code>max_size()</code> rather than <code>npos</code>.
</dd>
<dt><a href="lwg-defects.html#109">109</a>:
<em>Missing binders for non-const sequence elements</em>
</dt>
<dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
<code>operator()</code> taking a non-const parameter.
</dd>
<dt><a href="lwg-defects.html#110">110</a>:
<em>istreambuf_iterator::equal not const</em>
</dt>
<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
overloaded version with identical contents.
</dd>
<dt><a href="lwg-defects.html#117">117</a>:
<em>basic_ostream uses nonexistent num_put member functions</em>
</dt>
<dd><code>num_put::put()</code> was overloaded on the wrong types.
</dd>
<dt><a href="lwg-defects.html#118">118</a>:
<em>basic_istream uses nonexistent num_get member functions</em>
</dt>
<dd>Same as 117, but for <code>num_get::get()</code>.
</dd>
<dt><a href="lwg-defects.html#129">129</a>:
<em>Need error indication from seekp() and seekg()</em>
</dt>
<dd>These functions set <code>failbit</code> on error now.
</dd>
<dt><a href="lwg-defects.html#136">136</a>:
<em>seekp, seekg setting wrong streams?</em>
</dt>
<dd><code>seekp</code> should only set the output stream, and
<code>seekg</code> should only set the input stream.
</dd>
<!--<dt><a href="lwg-defects.html#159">159</a>:
<em>Strange use of underflow()</em>
</dt>
<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>:
<em>Improper use of traits_type::length()</em>
</dt>
<dd><code>op&lt;&lt;</code> with a <code>const char*</code> was
calculating an incorrect number of characters to write.
</dd>
<dt><a href="lwg-defects.html#181">181</a>:
<em>make_pair() unintended behavior</em>
</dt>
<dd>This function used to take its arguments as reference-to-const, now
it copies them (pass by value).
</dd>
<dt><a href="lwg-defects.html#195">195</a>:
<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>
<dt><a href="lwg-defects.html#211">211</a>:
<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
sets <code>failbit</code> (which can cause an exception, etc, etc).
</dd>
<dt><a href="lwg-defects.html#214">214</a>:
<em>set::find() missing const overload</em>
</dt>
<dd>Both <code>set</code> and <code>multiset</code> were missing
overloaded find, lower_bound, upper_bound, and equal_range functions
for const instances.
</dd>
<dt><a href="lwg-defects.html#251">251</a>:
<em>basic_stringbuf missing allocator_type</em>
</dt>
<dd>This nested typdef was originally not specified.
</dd>
<dt><a href="lwg-defects.html#265">265</a>:
<em>std::pair::pair() effects overly restrictive</em>
</dt>
<dd>The default ctor would build its members from copies of temporaries;
now it simply uses their respective default ctors.
</dd>
<dt><a href="lwg-defects.html#266">266</a>:
<em>bad_exception::~bad_exception() missing Effects clause</em>
</dt>
<dd>The <code>bad_</code>* classes no longer have destructors (they
are trivial), since no description of them was ever given.
</dd>
<dt><a href="lwg-defects.html#275">275</a>:
<em>Wrong type in num_get::get() overloads</em>
</dt>
<dd>Similar to 118.
</dd>
<!--
<dt><a href="lwg-defects.html#"></a>:
<em></em>
</dt>
<dd>
</dd>
-->
</dl></p>
</dl>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
@ -553,7 +622,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI">
<meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI" />
<meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>SGI extensions to the library in libstdc++-v3</title>
<link rel="StyleSheet" href="lib3styles.css">
<link rel="StyleSheet" href="lib3styles.css" />
</head>
<body>
@ -25,7 +24,7 @@ libstdc++-v3</a></h1>
for a description). Not every chapter may have extensions, and 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
$Date: 2001/11/23 16:29:01 $ (UTC).
$Date: 2001/11/28 00:02:04 $ (UTC).
</p>
<p>Descriptions range from the scanty to the verbose. You should also check
@ -36,30 +35,33 @@ libstdc++-v3</a></h1>
</p>
<p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>.
</p>
<!-- ####################################################### -->
<hr>
<a name="ch20"><h3>Chapter 20</h3></a>
<hr />
<h3><a name="ch20">Chapter 20</a></h3>
<p>The &lt;functional&gt; header contains many additional functors and
helper functions, extending section 20.3. They are implemented in the
file stl_function.h:
<ul>
<li><code>identity_element</code> for addition and multiplication. *
<li>The functor <code>identity</code>, whose op() returns the argument
unchanged. *
</p>
<ul>
<li><code>identity_element</code> for addition and multiplication. * </li>
<li>The functor <code>identity</code>, whose <code>operator()</code>
returns the argument unchanged. * </li>
<li>Composition functors <code>unary_function</code> and
<code>binary_function</code>, and their helpers <code>compose1</code>
and <code>compose2</code>. *
<li><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
<li><code>project1st</code> and <code>project2nd</code>. *
and <code>compose2</code>. * </li>
<li><code>select1st</code> and <code>select2nd</code>, to strip pairs. * </li>
<li><code>project1st</code> and <code>project2nd</code>. * </li>
<li>A set of functors/functions which always return the same result. They
are <code>constant_void_fun, constant_binary_fun, constant_unary_fun,
constant0, constant1, and constant2. *
<li>The class <code>subtractive_rng</code>. *
<li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for
backwards compatibility.
</ul></p>
are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
<code>constant_unary_fun</code>, <code>constant0</code>,
<code>constant1</code>, and <code>constant2</code>. * </li>
<li>The class <code>subtractive_rng</code>. * </li>
<li>mem_fun adaptor helpers <code>mem_fun1</code> and
<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
main extensions page.
</p>
@ -68,12 +70,12 @@ libstdc++-v3</a></h1>
is a pointer, which is ignored, but can be used to specify the template
type (instead of using explicit function template arguments like the
standard version does). That is, in addition to
</p>
<pre>
get_temporary_buffer&lt;int&gt;(5);</pre>
you can also use
<pre>
get_temporary_buffer(5, (int*)0);</pre>
</p>
<p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
</p>
<p>The specialized algorithms of section 20.4.4 are extended with
@ -84,8 +86,8 @@ libstdc++-v3</a></h1>
</p>
<hr>
<a name="ch23"><h3>Chapter 23</h3></a>
<hr />
<h3><a name="ch23">Chapter 23</a></h3>
<p>A few extensions and nods to backwards-compatibility have been made with
containers. Those dealing with older SGI-style allocators are dealt with
elsewhere. The remaining ones all deal with bits:
@ -105,18 +107,18 @@ libstdc++-v3</a></h1>
versions of single-bit test, set, reset, and flip member functions which
do no range-checking. If we call them member functions of an instantiation
of &quot;bitset&lt;N&gt;,&quot; then their names and signatures are:
</p>
<pre>
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos, int val);
bitset&lt;N&gt;&amp; _Unchecked_reset (size_t pos);
bitset&lt;N&gt;&amp; _Unchecked_flip (size_t pos);
bool _Unchecked_test (size_t pos);</pre>
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
reason to).
</p>
<p>
The semantics of member function <code>operator[]</code> are not specified
<p>The semantics of member function <code>operator[]</code> are not specified
in the C++ standard. A long-standing defect report calls for sensible
obvious semantics, which are already implemented here: <code>op[]</code>
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
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:
</p>
<pre>
size_t _Find_first() const;
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>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
<hr>
<a name="ch24"><h3>Chapter 24</h3></a>
<hr />
<h3><a name="ch24">Chapter 24</a></h3>
<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
time). For backwards compatibility, base classes are provided which
declare the same nested typedefs:
<ul>
<li>input_iterator
<li>output_iterator
<li>forward_iterator
<li>bidirectional_iterator
<li>random_access_iterator
</ul>
</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
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
@ -162,50 +165,53 @@ libstdc++-v3</a></h1>
</p>
<hr>
<a name="ch25"><h3>Chapter 25</h3></a>
<hr />
<h3><a name="ch25">Chapter 25</a></h3>
<p>25.1.6 (count, count_if) is extended with two more versions of count
and count_if. The standard versions return their results. The
additional signatures return void, but take a final parameter by
reference to which they assign their results, e.g.,
</p>
<pre>
void count (first, last, value, n);</pre>
</p>
<p>25.2 (mutating algorithms) is extended with two families of signatures,
random_sample and random_sample_n.
</p>
<p>25.2.1 (copy) is extended with
</p>
<pre>
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>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
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>
<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>
<pre>
lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
_InputIter2 first2, _InputIter2 last2)</pre>
which does... what?
<p>which does... what?
</p>
<p>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
<hr>
<a name="ch26"><h3>Chapter 26</h3></a>
<hr />
<h3><a name="ch26">Chapter 26</a></h3>
<p>26.4, the generalized numeric operations such as accumulate, are extended
with the following functions:
</p>
<pre>
power (x, n);
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
monoid operation. The two-argument signature uses multiplication (for
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.
That is, it assigns value to *first, value + 1 to *(first + 1) and so
on.&quot; Quoted from SGI documentation.
</p>
<pre>
void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre>
</p>
<p>Return <a href="howto.html">to the main extensions page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
@ -225,7 +231,7 @@ libstdc++-v3</a></h1>
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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>
<head>
<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="DESCRIPTION" content="FAQ for the GNU libstdc++ effort.">
<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="DESCRIPTION" content="FAQ for the GNU libstdc++ effort." />
<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
** answers 1_1, 1_4, 4_1.
@ -23,84 +23,92 @@
</p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### -->
<hr>
<hr />
<h1>Questions</h1>
<ol>
<li><a href="#1_0">General Information</a>
<!-- I suspect these will mostly be links to/into existing documents. -->
<ol>
<li><a href="#1_1">What is libstdc++-v3?</a>
<li><a href="#1_2">Why should I use libstdc++?</a>
<li><a href="#1_3">Who's in charge of it?</a>
<li><a href="#1_4">How do I get libstdc++?</a>
<li><a href="#1_5">When is libstdc++ going to be finished?</a>
<li><a href="#1_6">How do I contribute to the effort?</a>
<li><a href="#1_7">What happened to libg++? I need that!</a>
<li><a href="#1_8">What if I have more questions?</a>
<li><a href="#1_9">What are the license terms for 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>
<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>
<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>
<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>
<li><a href="#1_9">What are the license terms for libstdc++-v3?</a> </li>
</ol>
</li>
<li><a href="#2_0">Installation</a>
<ol>
<li><a href="#2_1">How do I install libstdc++-v3?</a>
<li><a href="#2_2">[removed]</a>
<li><a href="#2_1">How do I install libstdc++-v3?</a> </li>
<li><a href="#2_2">[removed]</a> </li>
<li><a href="#2_3">What is this CVS thing that you keep
mentioning?</a>
<li><a href="#2_4">How do I know if it works?</a>
<li><a href="#2_5">This library is HUGE! And what's libsupc++?</a>
mentioning?</a> </li>
<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>
</ol>
</li>
<li><a href="#3_0">Platform-Specific Issues</a>
<ol>
<li><a href="#3_1">Can libstdc++-v3 be used with &lt;my
favorite compiler&gt;?</a>
<li><a href="#3_2">[removed]</a>
<li><a href="#3_3">[removed]</a>
<li><a href="#3_4">I can't use 'long long' on Solaris</a>
favorite compiler&gt;?</a> </li>
<li><a href="#3_2">[removed]</a> </li>
<li><a href="#3_3">[removed]</a> </li>
<li><a href="#3_4">I can't use 'long long' on Solaris</a> </li>
<li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
<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>
</li>
<li><a href="#4_0">Known Bugs and Non-Bugs</a>
<ol>
<li><a href="#4_1">What works already?</a>
<li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a>
<li><a href="#4_3">Bugs in the C++ language/lib specification</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>
<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_iostreamclear">reopening a stream fails</a>
<li><a href="#4_4_Weff">-Weffc++ complains too much</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>
<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
<strong>not ours</strong></a>
<li><a href="#4_4_glibc">compilation errors from streambuf.h</a>
<strong>not ours</strong></a> </li>
<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
<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
in a dynamically-loaded library</a>
in a dynamically-loaded library</a> </li>
</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>
</li>
<li><a href="#5_0">Miscellaneous</a>
<ol>
<li><a href="#5_1">string::iterator is not char*;
vector&lt;T&gt;::iterator is not T*</a>
<li><a href="#5_2">What's next after libstdc++-v3?</a>
<li><a href="#5_3">What about the STL from SGI?</a>
<li><a href="#5_4">Extensions and Backward Compatibility</a>
<li><a href="#5_5">[removed]</a>
<li><a href="#5_6">Is libstdc++-v3 thread-safe?</a>
<li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a>
<li><a href="#5_8">What's an ABI and why is it so messy?</a>
vector&lt;T&gt;::iterator is not T*</a> </li>
<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>
<li><a href="#5_4">Extensions and Backward Compatibility</a> </li>
<li><a href="#5_5">[removed]</a> </li>
<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>
<li><a href="#5_8">What's an ABI and why is it so messy?</a> </li>
</ol>
</li>
</ol>
<hr>
<hr />
<!-- ####################################################### -->
@ -127,7 +135,7 @@
official <a href="../17_intro/DESIGN">design document</a>.
</p>
<hr>
<hr />
<h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2>
<p>The completion of the ISO C++ standardization gave the
C++ community a powerful set of reuseable tools in the form
@ -153,7 +161,7 @@
nor be worried about platform-specific incompatibilities.
</p>
<hr>
<hr />
<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
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!
</p>
<hr>
<hr />
<h2><a name="1_4">1.4 How do I get libstdc++?</a></h2>
<p>The fourteenth (and latest) snapshot of libstdc++-v3 is
<a href="http://gcc.gnu.org/libstdc++/index.html#download">available
@ -183,9 +191,9 @@
of the SGI STL.
</p>
<hr>
<hr />
<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
Usenet article</a>.</p>
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>
</p>
<hr>
<hr />
<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
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!
</p>
<hr>
<hr />
<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
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.
</p>
<hr>
<hr />
<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
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>.
</p>
<hr>
<hr />
<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>
for these and related questions.
</p>
<hr>
<hr />
<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>
<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]
series was. If you are using GCC 2.95, you can still
build earlier snapshots of libstdc++.
</li>
<li> GNU Make is recommended, but should not be required.
</li>
<li> The GNU Autotools are needed if you are messing with
the configury or makefiles.
</li>
</ul>
<p>The file <a href="../documentation.html">documentation.html</a>
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.
</p>
<hr>
<hr />
<h2><a name="2_2">2.2 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks).
</p>
<hr>
<hr />
<h2><a name="2_3">2.3 What is this CVS thing that you
keep mentioning?</a></h2>
<p>The <em>Concurrent Versions System</em> is one of several revision
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
the GNU software catalogue</a> has a better description as
well as a
@ -321,7 +332,7 @@ which is no longer available, thanks deja...-->
<!-- wonder how long that'll live -->
</p>
<hr>
<hr />
<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
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!
</p>
<hr>
<hr />
<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
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.
</p>
<hr>
<hr />
<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
favorite compiler&gt;?</a></h2>
@ -409,19 +420,19 @@ which is no longer available, thanks deja...-->
GCC/g++, however.
</p>
<hr>
<hr />
<h2><a name="3_2">3.2 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks).
</p>
<hr>
<hr />
<h2><a name="3_3">3.3 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks).
</p>
<hr>
<hr />
<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.
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>
<hr>
<hr />
<h2><a name="3_5">3.5 <code>_XOPEN_SOURCE</code> / <code>_GNU_SOURCE</code>
/ etc is always defined</a></h2>
<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.
</p>
<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>This method is something of a wart. We'd like to find a cleaner
solution, but nobody yet has contributed the time.
</p>
<hr>
<hr />
<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,
the patch is quite simple, and well-known.
@ -479,7 +490,7 @@ which is no longer available, thanks deja...-->
link to the solution.</a>
</p>
<hr>
<hr />
<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
nature of an open-source project. For the latest information, join
@ -571,7 +582,7 @@ New:
</pre>
<hr>
<hr />
<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
mentions some problems that users may encounter when building
@ -596,7 +607,7 @@ New:
experiences. :-)</li>
</ul>
<hr>
<hr />
<h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2>
<p>Yes, unfortunately, there are some. In a
<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>.
</p>
<hr>
<hr />
<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
the language specification (4.3), but aren't really bugs in
libstdc++, either. Really! Please do not report these as bugs.
</p>
<a name="4_4_Weff">
<p><strong>-Weffc++</strong>
The biggest of these is the quadzillions of warnings about the
library headers emitted when <code>-Weffc++</code> is used. Making
libstdc++ &quot;-Weffc++-clean&quot; is not a goal of the project,
for a few reasons. Mainly, that option tries to enforce
object-oriented programming, while the Standard Library isn't
necessarily trying to be OO.
</p>
</a>
<a name="4_4_iostreamclear">
<p><strong>reopening a stream fails</strong>
Did I just say that -Weffc++ was our biggest false-bug report? I
lied. (It used to be.) Today it seems to be reports that after
executing a sequence like
<pre>
<p><a name="4_4_Weff"><strong>-Weffc++</strong></a>
The biggest of these is the quadzillions of warnings about the
library headers emitted when <code>-Weffc++</code> is used. Making
libstdc++ &quot;-Weffc++-clean&quot; is not a goal of the project,
for a few reasons. Mainly, that option tries to enforce
object-oriented programming, while the Standard Library isn't
necessarily trying to be OO.
</p>
<p><a name="4_4_iostreamclear"><strong>reopening a stream fails</strong>
</a> Did I just say that -Weffc++ was our biggest false-bug report?
I lied. (It used to be.) Today it seems to be reports that after
executing a sequence like
</p>
<pre>
#include &lt;fstream&gt;
...
std::fstream fs(&quot;a_file&quot;);
@ -645,59 +654,54 @@ New:
// .
fs.close();
fs.open(&quot;a_new_file&quot;);</pre>
all operations on the re-opened <code>fs</code> will fail, or at
least act very strangely. Yes, they often will, especially if
<code>fs</code> reached the EOF state on the previous file. The
reason is that the state flags are <strong>not</strong> cleared
on a successful call to open(). The standard unfortunately did
not specify behavior in this case, and to everybody's great sorrow,
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
to <code>fs.clear()</code> between the calls to close() and open(),
and then everything will work like we all expect it to work.
</p>
</a>
<a name="4_4_rel_ops">
<p><strong>rel_ops</strong>
Another is the <code>rel_ops</code> namespace and the template
comparison operator functions contained therein. If they become
visible in the same namespace as other comparison functions
(e.g., '<code>using</code>' them and the &lt;iterator&gt; header),
then you will suddenly be faced with huge numbers of ambiguity
errors. This was discussed on the -v3 list; Nathan Myers
<a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
things up here</a>. The collisions with vector/string iterator
types have been fixed for 3.1. <!-- more links to email here -->
</p>
</a>
<a name="4_4_interface"><h3>The g++-3 headers are
<em>not ours</em></h3>
<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
<p>all operations on the re-opened <code>fs</code> will fail, or at
least act very strangely. Yes, they often will, especially if
<code>fs</code> reached the EOF state on the previous file. The
reason is that the state flags are <strong>not</strong> cleared
on a successful call to open(). The standard unfortunately did
not specify behavior in this case, and to everybody's great sorrow,
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
to <code>fs.clear()</code> between the calls to close() and open(),
and then everything will work like we all expect it to work.
</p>
<p><a name="4_4_rel_ops"><strong>rel_ops</strong></a>
Another is the <code>rel_ops</code> namespace and the template
comparison operator functions contained therein. If they become
visible in the same namespace as other comparison functions
(e.g., '<code>using</code>' them and the &lt;iterator&gt; header),
then you will suddenly be faced with huge numbers of ambiguity
errors. This was discussed on the -v3 list; Nathan Myers
<a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
things up here</a>. The collisions with vector/string iterator
types have been fixed for 3.1. <!-- more links to email here -->
</p>
<h3><a name="4_4_interface">The g++-3 headers are <em>not ours</em></a></h3>
<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>).
</p>
<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>
or <code>libstdc++-libc6-2.10.so</code>,
then you are using the old libstdc++-v2 library, which is nonstandard
and unmaintained. Do not report problems with -v2 to the -v3
mailing list.
</p>
<p>Currently our header files are installed in
<code>${prefix}/include/g++-v3</code> (see the 'v'?). This may
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
question has not yet been decided</a>.
</p>
</a>
<a name="4_4_glibc">
<p><strong>glibc</strong>
If you're on a GNU/Linux system and have just upgraded to
glibc 2.2, but are still using gcc 2.95.2, then you should have
read the glibc FAQ, specifically 2.34:
<pre>
</p>
<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>
or <code>libstdc++-libc6-2.10.so</code>,
then you are using the old libstdc++-v2 library, which is nonstandard
and unmaintained. Do not report problems with -v2 to the -v3
mailing list.
</p>
<p>Currently our header files are installed in
<code>${prefix}/include/g++-v3</code> (see the 'v'?). This may
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
question has not yet been decided</a>.
</p>
<p><a name="4_4_glibc"><strong>glibc</strong></a>
If you're on a GNU/Linux system and have just upgraded to
glibc 2.2, but are still using gcc 2.95.2, then you should have
read the glibc FAQ, specifically 2.34:
</p>
<pre>
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
@ -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
http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
</pre>
Note that 2.95.x shipped with the
<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
requires a separate patch for libstdc++-v3.
</p>
</a>
<a name="4_4_checks">
<p><strong>concept checks</strong>
If you see compilation errors containing messages about
<code> <em>foo</em>Concept </code>and a<code> constraints </code>
member function, then most likely you have violated one of the
requirements for types used during instantiation of template
containers and functions. For example, EqualityComparableConcept
appears if your types must be comparable with == and you have not
provided this capability (a typo, or wrong visibility, or you
just plain forgot, etc).
</p>
<p>More information, including how to optionally enable/disable the
checks, is available
<a href="../19_diagnostics/howto.html#3">here</a>.
</p>
</a>
<a name="4_4_dlsym">
<p><strong>dlopen/dlsym</strong>
If you are using the C++ library across dynamically-loaded
objects, make certain that you are passing the correct options
when compiling and linking:
<pre>
<p>Note that 2.95.x shipped with the
<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
requires a separate patch for libstdc++-v3.
</p>
<p><a name="4_4_checks"><strong>concept checks</strong></a>
If you see compilation errors containing messages about
<code> <em>foo</em>Concept </code>and a<code> constraints </code>
member function, then most likely you have violated one of the
requirements for types used during instantiation of template
containers and functions. For example, EqualityComparableConcept
appears if your types must be comparable with == and you have not
provided this capability (a typo, or wrong visibility, or you
just plain forgot, etc).
</p>
<p>More information, including how to optionally enable/disable the
checks, is available
<a href="../19_diagnostics/howto.html#3">here</a>.
</p>
<p><a name="4_4_dlsym"><strong>dlopen/dlsym</strong></a>
If you are using the C++ library across dynamically-loaded
objects, make certain that you are passing the correct options
when compiling and linking:
</p>
<pre>
// compile the library components
g++ -fPIC -c a.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
// link the executable
g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre></p>
</a>
g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre>
<hr>
<hr />
<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
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.
</p>
<hr>
<hr />
<h1><a name="5_0">5.0 Miscellaneous</a></h1>
<h2><a name="5_1">5.1 string::iterator is not char*;
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;).
</p>
<hr>
<hr />
<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
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
resolution specifies. Those additions are listed in
<a href="../ext/howto.html#5">the extensions page</a>.
</p>
</p></li>
<li><p>Performance tuning. Lots of performance tuning. This too is
already underway for post-3.0 releases, starting with memory
expansion in container classes and buffer usage in synchronized
stream objects.
</p>
</p></li>
<li><p>An ABI for libstdc++ is being developed, so that
multiple binary-incompatible copies of the library can be replaced
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
must be explicitly requested by client code (for example, the
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.)
Bugfixes and rewrites (to improve or fix thread safety, for
instance) will of course be a continuing task.
</p>
</p></li>
</ol>
<p><a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This
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>.
</p>
<hr>
<hr />
<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>,
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.
</p>
<hr>
<hr />
<h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2>
<p>Headers in the <code>ext</code> and <code>backward</code>
subdirectories should be referred to by their relative paths:
<!-- Careful, the leading spaces in PRE show up directly. -->
<pre>
</p>
<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
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>.
@ -860,13 +861,13 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
<a href="../ext/howto.html">their own page</a>.
</p>
<hr>
<hr />
<h2><a name="5_5">5.5 [removed]</a></h2>
<p>This question has become moot and has been removed. The stub
is here to preserve numbering (and hence links/bookmarks).
</p>
<hr>
<hr />
<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
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
a method call. Without getting into great detail, here is an
example which requires user-level locks:
<pre>
</p>
<pre>
library_class_a shared_object_a;
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>
</p>
<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
user-level locks:
<pre>
</p>
<pre>
thread_main () {
library_class_a object_a;
library_class_b *object_b = new library_class_b;
object_a.add_b (object_b);
object_a.mutate ();
} </pre>
</p>
<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
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.
</p>
<hr>
<hr />
<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
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!
</p>
<hr>
<hr />
<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;
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>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
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 world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and
Paolo Carlini are the lead maintainers of the CVS archive.
Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo
Carlini are the lead maintainers of the CVS archive.
Development and discussion is held on the libstdc++ mailing list.
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>
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++">
<meta name="DESCRIPTION" content="README for the GNU libstdc++ effort.">
<meta name="GENERATOR" content="vi and eight fingers">
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" />
<meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++-v3 Installation Instructions</title>
<link rel="StyleSheet" href="lib3styles.css">
<link rel="StyleSheet" href="lib3styles.css" />
</head>
<body>
@ -18,21 +17,22 @@
</p>
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
</p>
<!-- ####################################################### -->
<hr>
<hr />
<h2>Contents</h2>
<ul>
<li><a href="#prereqs">Tools you will need beforehand</a>
<li><a href="#srcsetup">Setting up the source directories</a>
<li><a href="#config">Configuring</a>
<li><a href="#install">Building and installing the library</a>
<li><a href="#postinstall">Post-installation</a>
<li><a href="#usage">Using the library</a>
<li><a href="#prereqs">Tools you will need beforehand</a></li>
<li><a href="#srcsetup">Setting up the source directories</a></li>
<li><a href="#config">Configuring</a></li>
<li><a href="#install">Building and installing the library</a></li>
<li><a href="#postinstall">Post-installation</a></li>
<li><a href="#usage">Using the library</a></li>
</ul>
<hr>
<hr />
<!-- ####################################################### -->
@ -88,8 +88,8 @@
features if the underlying support is present.
</p>
<p>Finally, a few system-specific requirements: </p>
<dl>
<p>Finally, a few system-specific requirements: </p>
<dl>
<dt> linux </dt>
<dd>If you are using gcc 3.1 or later on linux, and are using
@ -119,9 +119,9 @@
</li>
</ul>
</dd>
</dl>
</dl>
<hr>
<hr />
<h2><a name="srcsetup">Setting up the source directories</a></h2>
<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
compiler. It should have several subdirectories like
<em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc.
</li>
<li><em>libsrcdir</em>: The directory holding the source of the
C++ library.
</li>
<li><em>gccbuilddir</em>: The build directory for the compiler
in <em>gccsrcdir</em>. GCC requires that it be built in
a different directory than its sources.
</li>
<li><em>libbuilddir</em>: The build directory for libstdc++.
</li>
<li><em>destdir</em>: The eventual installation directory for
the compiler/libraries, set with the --prefix option to
the configure script.
</li>
</ul>
<p> Note: </p>
<ol>
@ -147,10 +152,12 @@
library that comes with the compiler, so <em>libsrcdir</em>
and <em>libbuilddir</em> must be contained under
<em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively.
</li>
<li>The source, build, and installation directories should
not be parents of one another; i.e., these should all be
separate directories. Please don't build out of the
source directory.
</li>
</ol>
<p>Check out or download the GCC sources: the resulting source directory
@ -175,7 +182,7 @@
mv <em>libsrcdir</em> libstdc++-v3</pre>
<hr>
<hr />
<h2><a name="config">Configuring</a></h2>
<p>If you have never done this before, you should read the basic
<a href="http://gcc.gnu.org/install/">GCC Installation
@ -196,7 +203,7 @@
<em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
<hr>
<hr />
<h2><a name="install">Building and installing the library</a></h2>
<p>Now you have a few options:</p>
<h3>[re]building <em>everything</em></h3>
@ -236,7 +243,7 @@
make install-target-libstdc++-v3</pre>
<hr>
<hr />
<h2><a name="postinstall">Post-installation</a></h2>
<p>Installation will create the <em>destdir</em> directory and
populate it with subdirectories:
@ -266,7 +273,7 @@
</p>
<hr>
<hr />
<h2><a name="usage">Using the library</a></h2>
<h3>Find the new library at runtime (shared linking only)</h3>
<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.
They include:
</p>
<ul>
<ul>
<li>At runtime set LD_LIBRARY_PATH in your environment correctly,
so that the shared library for libstdc++ can be found and
loaded. Be certain that you understand all of the other
implications and behavior of LD_LIBRARY_PATH first (few
people do, and they get into trouble).
</li>
<li>Compile the path to find the library at runtime into the
program. This can be done by passing certain options to g++,
which will in turn pass them on to the linker. The exact
format of the options is dependent on which linker you use:
<ul>
<li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code>
<li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code>
<li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code>
<li>More...? Let us know!
<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>
<li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
<li>More...? Let us know!</li>
</ul>
</ul>
</li>
</ul>
<p>Use the <code>ldd(1)</code> utility to show which library the system
thinks it will get at runtime.
</p>
@ -306,7 +315,7 @@
<!--
<hr>
<hr />
<h2><a name=""></a></h2>
<p>
</p>
@ -315,7 +324,7 @@
<!-- ####################################################### -->
<hr>
<hr />
<p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to

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

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