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

configopts.html: HTML to XHTML change.

Browse source 
2001-09-17  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/configopts.html:  HTML to XHTML change.  Lowercase tags.
	* docs/html/documentation.html:  Likewise.
	* docs/html/explanations.html:  Likewise.
	* docs/html/install.html:  Likewise.
	* docs/html/17_intro/howto.html:  Likewise.
	* docs/html/18_support/howto.html:  Likewise.
	* docs/html/19_diagnostics/howto.html:  Likewise.
	* docs/html/20_util/howto.html:  Likewise.
	* docs/html/21_strings/howto.html:  Likewise.
	* docs/html/22_locale/codecvt.html:  Likewise.
	* docs/html/22_locale/ctype.html:  Likewise.
	* docs/html/22_locale/howto.html:  Likewise.
	* docs/html/22_locale/locale.html:  Likewise.
	* docs/html/22_locale/messages.html:  Likewise.
	* docs/html/23_containers/howto.html:  Likewise.
	* docs/html/24_iterators/howto.html:  Likewise.
	* docs/html/25_algorithms/howto.html:  Likewise.
	* docs/html/26_numerics/howto.html:  Likewise.
	* docs/html/27_io/howto.html:  Likewise.
	* docs/html/ext/howto.html:  Likewise.
	* docs/html/faq/index.html:  Likewise.
	* docs/html/faq/index.txt:  Regenerated.

From-SVN: r45668
This commit is contained in:
Phil Edwards 2001-09-17 23:24:40 +00:00
parent 5c701bb10c
commit 5d5e5e4e42
23 changed files with 2632 additions and 2607 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
libstdc++-v3/ChangeLog
View file

@ -1,3 +1,28 @@
2001-09-17 Phil Edwards <pme@gcc.gnu.org>
* docs/html/configopts.html: HTML to XHTML change. Lowercase tags.
* docs/html/documentation.html: Likewise.
* docs/html/explanations.html: Likewise.
* docs/html/install.html: Likewise.
* docs/html/17_intro/howto.html: Likewise.
* docs/html/18_support/howto.html: Likewise.
* docs/html/19_diagnostics/howto.html: Likewise.
* docs/html/20_util/howto.html: Likewise.
* docs/html/21_strings/howto.html: Likewise.
* docs/html/22_locale/codecvt.html: Likewise.
* docs/html/22_locale/ctype.html: Likewise.
* docs/html/22_locale/howto.html: Likewise.
* docs/html/22_locale/locale.html: Likewise.
* docs/html/22_locale/messages.html: Likewise.
* docs/html/23_containers/howto.html: Likewise.
* docs/html/24_iterators/howto.html: Likewise.
* docs/html/25_algorithms/howto.html: Likewise.
* docs/html/26_numerics/howto.html: Likewise.
* docs/html/27_io/howto.html: Likewise.
* docs/html/ext/howto.html: Likewise.
* docs/html/faq/index.html: Likewise.
* docs/html/faq/index.txt: Regenerated.
2001-09-14 Phil Edwards <pme@sources.redhat.com>
* docs/html/17_intro/headers_cc.txt: "Sync"/copy real file over.

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

@ -1,76 +1,76 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.6 2001/06/08 03:53:35 ljrittle Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.7 2001/09/15 00:41:10 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 17: Library Introduction</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 17: Library Introduction</a></h1>
<P>Chapter 17 is actually a list of definitions and descriptions used
<p>Chapter 17 is actually a list of definitions and descriptions used
in the following chapters of the Standard when describing the actual
library. Here, we use &quot;Introduction&quot; as an introduction
to the <EM>GNU implementation of</EM> the ISO Standard C++ Library.
</P>
to the <em>GNU implementation of</em> the ISO Standard C++ Library.
</p>
<!-- ####################################################### -->
<HR>
<H1>Contents</H1>
<UL>
<LI><A HREF="#2">The Standard C++ header files</A>
<LI><A HREF="#3">Thread-safety</A>
<LI><A HREF="#4"><TT>&lt;foo&gt;</TT> vs <TT>&lt;foo.h&gt;</TT></A>
<LI><A HREF="porting-howto.html">Porting-howto</A>
</UL>
<hr>
<h1>Contents</h1>
<ul>
<li><a href="#2">The Standard C++ header files</a>
<li><a href="#3">Thread-safety</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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="2">The Standard C++ header files</A></H2>
<P>The Standard C++ Library specifies 50 header files that must be
<h2><a name="2">The Standard C++ header files</a></h2>
<p>The Standard C++ Library specifies 50 header files that must be
available to all hosted implementations. Actually, the word
&quot;files&quot; is a misnomer, since the contents of the headers
don't necessarily have to be in any kind of external file. The
only rule is that when you <TT>#include</TT> a certain header, the
only rule is that when you <code>#include</code> a certain header, the
contents of that header, as defined by the Standard, become
available to you, no matter how.
</P>
<P>The names of the headers can be easily seen in
<A HREF="headers_cc.txt"><TT>testsuite/17_intro/headers.cc</TT></A>,
</p>
<p>The names of the headers can be easily seen in
<a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>,
which is a small testbed we use to make certain that the headers
all compile and run.
</P>
</p>
<HR>
<H2><A NAME="3">Thread-safety</A></H2>
<P>This is a thorny issue that gets brought up on the libstdc++-v3
<hr>
<h2><a name="3">Thread-safety</a></h2>
<p>This is a thorny issue that gets brought up on the libstdc++-v3
and gcc mailing lists on a regular basis (probably by a cron job).
This entry will mention a very little bit about the general MT
issues with libstdc++. The latest status and quick notes will be
in FAQ 5.6. Some discussion about thread-safe containers will be
in section 6.8 (the HOWTOs on containers). This section only applies
when gcc and libstdc++-v3 were configured with --enable-threads.
</P>
<P>The libstdc++ code (all of it, not just the containers) has been
</p>
<p>The libstdc++ code (all of it, not just the containers) has been
designed so that thread-safety will be easily possible. The first
(!) problem is finding a <EM>fast</EM> method of implementation
(!) problem is finding a <em>fast</em> method of implementation
portable to all platforms. A minor problem that pops up every so
often is different interpretations of what &quot;thread-safe&quot;
means for a library (not a general program). We currently use the
<A HREF="http://www.sgi.com/tech/stl/thread_safety.html">same
definition that SGI</A> uses for their STL subset.
<EM>Please see the many cautions given in HOWTOs on containers.</EM>
</P>
<P>Here is another attempt at explaining the dangers of using the
<a href="http://www.sgi.com/tech/stl/thread_safety.html">same
definition that SGI</a> uses for their STL subset.
<em>Please see the many cautions given in HOWTOs on containers.</em>
</p>
<p>Here is another attempt at explaining the dangers of using the
STL with threading support without understanding some important
details. The STL implementation is currently configured to use
the high-speed caching memory allocator. If you absolutely
@ -80,8 +80,8 @@
fully aware that you may change the external or internal ABI of
libstdc++-v3 when you provide -D__USE_MALLOC on the command line
or make a change to that configuration file.
</P>
<P>If you don't like caches of objects being retained inside the STL, then
</p>
<p>If you don't like caches of objects being retained inside the STL, then
you might be tempted to define __USE_MALLOC either on the command
line or by rebuilding c++config.h. Please note, once you define
__USE_MALLOC, only the malloc allocator is visible to application code
@ -96,96 +96,96 @@
<PRE>
std::list &lt;void*, std::malloc_alloc&gt; my_malloc_based_list;
</PRE>
</P>
<P>A recent journal article has described &quot;atomic integer
</p>
<p>A recent journal article has described &quot;atomic integer
operations,&quot; which would allow us to, well, perform updates
on integers atomically, and without requiring an explicit mutex
lock. This appears promising, but the major difficulty is that
these operations &quot;may not be available on all systems, and
if they are, may have different interfaces.&quot; [quoting from
mailing list messages]
</P>
<P>Here is a small link farm to threads (no pun) in the mail archives
</p>
<p>Here is a small link farm to threads (no pun) in the mail archives
that discuss the threading problem. Each link is to the first
relevent 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.
<UL>
<LI><A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
<ul>
<li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
inspired this most recent updating of issues with threading
and the SGI STL library. It also contains some example
POSIX-multithreaded STL code.</A>
<LI> <A HREF="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
POSIX-multithreaded STL code.</a>
<li> <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
an early analysis of why __USE_MALLOC should be disabled for
the 3.0 release of libstdc++.</A>
</UL>
<BR>
the 3.0 release of libstdc++.</a>
</ul>
<br>
Here are discussions that took place before the current snapshot;
they are still relevant and instructive. (Some of them may not work;
as the drive containing some of the 1999 archives crashed, and nobody
has had time to recover the backups.)
<BR>
<UL>
<LI>One way of preventing memory leaks by the old default memory
<br>
<ul>
<li>One way of preventing memory leaks by the old default memory
allocator in multithreaded code is
<A HREF="http://gcc.gnu.org/ml/gcc/1999-11n/msg00431.html">discussed here</A>.
<LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00167.html">This thread
concerns strings</A>.
<LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00339.html">So does this
one</A>. This initial message also refers to another
<a href="http://gcc.gnu.org/ml/gcc/1999-11n/msg00431.html">discussed here</a>.
<li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00167.html">This thread
concerns strings</a>.
<li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00339.html">So does this
one</a>. This initial message also refers to another
thread in the GCC mailing list...
<LI><A HREF="http://gcc.gnu.org/ml/gcc/1999-06n/msg00680.html">which is here</A>,
<li><a href="http://gcc.gnu.org/ml/gcc/1999-06n/msg00680.html">which is here</a>,
and goes on for some time. Ironically, the initial message
in this thread also mentions another threading thread...
<LI><A HREF="http://gcc.gnu.org/ml/gcc-bugs/1999-04n/msg00777.html">beginning here</A>,
<li><a href="http://gcc.gnu.org/ml/gcc-bugs/1999-04n/msg00777.html">beginning here</a>,
and talking about pthreads. (Note that a much more recent
message from the first thread in this list notes that
<A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00176.html">pthreads
should not be used as a starting point</A> for making
<a href="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00176.html">pthreads
should not be used as a starting point</a> for making
libstdc++ threadsafe.)
<LI><A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00168.html">This
message</A>,
<A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00159.html">this one</A>,
and <A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00156.html">this one</A>
<li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00168.html">This
message</a>,
<a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00159.html">this one</a>,
and <a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00156.html">this one</a>
are the tops of related threads (all within the same time
period) discussing threading and the IO library. Much of it
is dealing with the C library, but C++ is included as well.
</UL>
</P>
<P>This section will be updated as new and interesting issues come
</ul>
</p>
<p>This section will be updated as new and interesting issues come
to light.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="4"><TT>&lt;foo&gt;</TT> vs <TT>&lt;foo.h&gt;</TT></A></H2>
<P>The new-style headers are fully supported in libstdc++-v3. The compiler
itself fully supports namespaces, including <TT>std::</TT>.
</P>
<P>For those of you new to ISO C++98, no, that isn't a typo, the headers
<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>.
</p>
<p>For those of you new to ISO C++98, no, that isn't a typo, the headers
really have new names. Marshall Cline's C++ FAQ Lite has a good
explanation in
<A HREF="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
<a href="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</a>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.6 2001/06/08 03:53:35 ljrittle Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.7 2001/09/15 00:41:10 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,61 +1,61 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.3 2001/05/30 21:54:58 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 18: Library Support</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 18: Library Support</a></h1>
<P>Chapter 18 deals with the functions called and objects created
<p>Chapter 18 deals with the functions called and objects created
automatically during the course of a program's existence.
</P>
<P>While we can't reproduce the contents of the Standard here (you need to
</p>
<p>While we can't reproduce the contents of the Standard here (you need to
get your own copy from your nation's member body; see our homepage for
help), we can mention a couple of changes in what kind of support a C++
program gets from the Standard Library.
</P>
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Types</A></H2>
<P>All the types that you're used to in C are here in one form or
<h2><a name="1">Types</a></h2>
<p>All the types that you're used to in C are here in one form or
another. The only change that might affect people is the type of
NULL: while it is required to be a macro, the definition of that
macro is <EM>not</EM> allowed to be <TT>(void*)0</TT>, which is
macro is <em>not</em> allowed to be <code>(void*)0</code>, which is
often used in C.
</P>
<P>In g++, NULL is #define'd to be <TT>__null</TT>, a magic keyword
</p>
<p>In g++, NULL is #define'd to be <code>__null</code>, a magic keyword
extension of g++.
</P>
<P>The biggest problem of #defining NULL to be something like
</p>
<p>The biggest problem of #defining NULL to be something like
&quot;0L&quot; is that the compiler will view that as a long integer
before it views it as a pointer, so overloading won't do what you
expect. (This is why g++ has a magic extension, so that NULL is
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>,
</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>,
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
@ -78,36 +78,36 @@
} NULL; // and whose name is NULL
</PRE>(Cribbed from the published version of
<A HREF="http://www.awlonline.com/cseng/meyerscddemo/">the
Effective C++ CD</A>, reproduced here with permission.)
</P>
<P>If you aren't using g++ (why?), but you do have a compiler which
<a href="http://www.awlonline.com/cseng/meyerscddemo/">the
Effective C++ CD</a>, reproduced here with permission.)
</p>
<p>If you aren't using g++ (why?), but you do have a compiler which
supports member function templates, then you can use this definition
of NULL (be sure to #undef any existing versions). It only helps if
you actually use NULL in function calls, though; if you make a call of
<TT>foo(0);</TT> instead of <TT>foo(NULL);</TT>, then you're back
<code>foo(0);</code> instead of <code>foo(NULL);</code>, then you're back
where you started.
</P>
<P><B>Added Note:</B> When we contacted Dr. Meyers to ask permission to
</p>
<p><B>Added Note:</B> When we contacted Dr. Meyers to ask permission to
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
article to Usenet</A> after discovering that the code above is not
<a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&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
after all). The ctor can have an empty body; it just needs to be
there. (Stupid requirement? We think so too, and this will probably
be changed in the language itself.)
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="2">Implementation properties</A></H2>
<P>
<H3><CODE>&lt;limits&gt;</CODE></H3>
<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
implementation defined-aspects of the fundamental types. The
traits classes -- fourteen in total -- are all specilizations of the
@ -149,28 +149,28 @@
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>
</p>
<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="3">Start and Termination</A></H2>
<P>Not many changes here to <TT>&lt;cstdlib&gt;</TT> (the old stdlib.h).
You should note that the <TT>abort()</TT> function does not call
<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
the destructors of automatic nor static objects, so if you're depending
on those to do cleanup, it isn't going to happen. (The functions
registered with <TT>atexit()</TT> don't get called either, so you
registered with <code>atexit()</code> don't get called either, so you
can forget about that possibility, too.)
</P>
<P>The good old <TT>exit()</TT> function can be a bit funky, too, until
</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:
<OL>
<LI>Static objects are destroyed in reverse order of their creation.
<LI>Functions registered with <TT>atexit()</TT> are called in
<ol>
<li>Static objects are destroyed in reverse order of their creation.
<li>Functions registered with <code>atexit()</code> are called in
reverse order of registration, once per registration call.
(This isn't actually new.)
<LI>The previous two actions are &quot;interleaved,&quot; that is,
<li>The previous two actions are &quot;interleaved,&quot; that is,
given this pseudocode:
<PRE>
extern "C or C++" void f1 (void);
@ -180,50 +180,50 @@
atexit(f1);
static Thing obj2;
atexit(f2);
</PRE>then at a call of <TT>exit()</TT>, 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 propogate
out of them, Bad Things happen.
</OL>
</P>
<P>Note also that <TT>atexit()</TT> is only required to store 32
</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
the xatexit/xexit combination from libiberty, which has no such limit.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="4">Dynamic memory management</A></H2>
<P>There are six flavors each of <TT>new</TT> and <TT>delete</TT>, so
<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 <TT>new</TT>:
<UL>
<LI>single object form, throwing a <TT>bad_alloc</TT> on errors;
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 <TT>bad_alloc</TT> 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>
<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
any other overloaded function. The six flavors of <TT>delete</TT>
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
completeness' sake.)
</P>
<P>Remember that it is perfectly okay to call <TT>delete</TT> on a
</p>
<p>Remember that it is perfectly okay to call <code>delete</code> on a
NULL pointer! Nothing happens, by definition. That is not the
same thing as deleting a pointer twice.
</P>
<P>By default, if one of the &quot;throwing <TT>new</TT>s&quot; can't
</p>
<p>By default, if one of the &quot;throwing <code>new</code>s&quot; can't
allocate the memory requested, it tosses an instance of a
<TT>bad_alloc</TT> exception (or, technically, some class derived
<code>bad_alloc</code> exception (or, technically, some class derived
from it). You can change this by writing your own function (called
a new-handler) and then registering it with <TT>set_new_handler()</TT>:
a new-handler) and then registering it with <code>set_new_handler()</code>:
<PRE>
typedef void (*PFV)(void);
@ -247,13 +247,13 @@
...
}
</PRE>
</P>
<P><TT>bad_alloc</TT> is derived from the base <TT>exception</TT>
</p>
<p><code>bad_alloc</code> is derived from the base <code>exception</code>
class defined in Chapter 19.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
@ -261,13 +261,13 @@
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.3 2001/05/30 21:54:58 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,44 +1,44 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.4 2001/05/30 21:54:59 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.5 2001/09/15 00:41:11 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 19: Diagnostics</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 19: Diagnostics</a></h1>
<P>Chapter 19 deals with program diagnostics, such as exceptions
<p>Chapter 19 deals with program diagnostics, such as exceptions
and assertions. You know, all the things we wish weren't even
necessary at all.
</P>
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Adding data to exceptions</A></H2>
<P>The standard exception classes carry with them a single string as
<h2><a name="1">Adding data to exceptions</a></h2>
<p>The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
place). It's good to remember that you can add your own data to
these exceptions when extending the heirarchy:
</P>
</p>
<PRE>
using std::runtime_error;
struct My_Exception : public runtime_error
@ -53,71 +53,71 @@
DBID id; // some user-defined type
};
</PRE>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
<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="2">Exception class hierarchy diagram</A></H2>
<P>At one point we were going to make up a PDF of the exceptions
<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.
Time was our enemy. Since then we've moved to Doxygen, which has
the useful property of not sucking. Specifically, when the source
code is changed, the diagrams are automatically brought up to date.
For the old way, we had to update the diagrams separately.
</P>
<P>There are several links to the Doxygen-generated pages from
<A HREF="../documentation.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>There are several links to the Doxygen-generated pages from
<a href="../documentation.html">here</a>.
</p>
<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="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
<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
of the STL: code which checked the template parameters of
instantiated pieces of the STL, in order to insure that the parameters
being used met the requirements of the standard. For example,
the Standard requires that types passed as template parameters to
<TT>vector</TT> be &quot;Assignable&quot; (which means what you think
<code>vector</code> be &quot;Assignable&quot; (which means what you think
it means). The checking was done during compilation, and none of
the code was executed at runtime.
</P>
<P>Unfortunately, the size of the compiler files grew significantly
</p>
<p>Unfortunately, the size of the compiler files grew significantly
as a result. The checking code itself was cumbersome. And bugs
were found in it on more than one occasion.
</P>
<P>The primary author of the checking code, Jeremy Siek, had already
</p>
<p>The primary author of the checking code, Jeremy Siek, had already
started work on a replcement 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
<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
GNU C++ library.
</P>
<P>The new version imposes a much smaller space overhead on the generated
</p>
<p>The new version imposes a much smaller space overhead on the generated
object file. The checks are also cleaner and easier to read and
understand.
</P>
<P>Right now they are off by default. More will be added once
</p>
<p>Right now they are off by default. More will be added once
GCC 3.0 is released and we have time to revisit this topic.
</P>
</p>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.4 2001/05/30 21:54:59 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.5 2001/09/15 00:41:11 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,53 +1,53 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.3 2001/04/03 00:26:55 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.4 2001/05/30 21:55:00 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 20: General Utilities</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 20: General Utilities</a></h1>
<P>Chapter 20 deals with utility classes and functions, such as
the oft-debated <TT>auto_ptr&lt;&gt;</TT>.
</P>
<p>Chapter 20 deals with utility classes and functions, such as
the oft-debated <code>auto_ptr&lt;&gt;</code>.
</p>
<!-- ####################################################### -->
<HR>
<H1>Contents</H1>
<UL>
<LI><A HREF="#1"><TT>auto_ptr</TT> is not omnipotent</A>
<LI><A HREF="#2"><TT>auto_ptr</TT> inside container classes</A>
<LI><A HREF="#3">Functors</A>
<LI><A HREF="#4">Pairs</A>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1"><TT>auto_ptr</TT> is not omnipotent</A></H2>
<P>I'm not going to try and explain all of the fun and delicious
<h2><a name="1"><code>auto_ptr</code> is not omnipotent</a></h2>
<p>I'm not going to try and explain all of the fun and delicious
things that can happen with misuse of the auto_ptr class template
(called AP here), nor am I going to try and teach you how to use
AP safely in the presence of copying. The AP class is a really
nifty idea for a smart pointer, but it is one of the dumbest of
all the smart pointers -- and that's fine.
</P>
<P>AP is not meant to be a supersmart solution to all resource
</p>
<p>AP is not meant to be a supersmart solution to all resource
leaks everywhere. Neither is it meant to be an effective form
of garbage collection (although it can help, a little bit).
And it can <EM>not</EM> be used for arrays!
</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:
And it can <em>not</em> be used for arrays!
</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>
// not a recommend naming scheme, but good for web-based FAQs
typedef std::auto_ptr&lt;MyClass&gt; APMC;
@ -64,10 +64,10 @@
function_taking_MyClass_pointer (ap.get());
}
</PRE>When an exception gets thrown, the instance of MyClass that's
been created on the heap will be <TT>delete</TT>'d as the stack is
unwound past <TT>func()</TT>.
</P>
<P>Changing that code as follows is <EM>not</EM> AP-friendly:
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>
APMC ap (new MyClass[22]);
</PRE>You will get the same problems as you would without the use
@ -77,20 +77,20 @@
...
delete array; // ...but single-object delete
</PRE>
</P>
<P>AP cannot tell whether the pointer you've passed at creation points
</p>
<p>AP cannot tell whether the pointer you've passed at creation points
to one or many things. If it points to many things, you are about
to die. AP is trivial to write, however, so you could write your
own <TT>auto_array_ptr</TT> for that situation (in fact, this has
own <code>auto_array_ptr</code> for that situation (in fact, this has
been done many times; check the mailing lists, Usenet, Boost, etc).
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="2"><TT>auto_ptr</TT> inside container classes</A></H2>
<P>All of the <A HREF="../23_containers/howto.html">containers</A>
<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 contructor like this:
<PRE>
@ -100,18 +100,18 @@
};
</PRE>
Note the const keyword; the object being copied shouldn't change.
The template class <TT>auto_ptr</TT> (called AP here) does not
The template class <code>auto_ptr</code> (called AP here) does not
meet this requirement. Creating a new AP by copying an existing
one transfers ownership of the pointed-to object, which means that
the AP being copied must change, which in turn means that the
copy ctors of AP do not take const objects.
</P>
<P>The resulting rule is simple: <EM>Never ever use a container of
auto_ptr objects.</EM> The standard says that undefined behavior
</p>
<p>The resulting rule is simple: <em>Never ever use a container of
auto_ptr objects.</em> The standard says that undefined behavior
is the result, but it is guaranteed to be messy.
</P>
<P>To prevent you from doing this to yourself, the
<A HREF="../19_diagnostics/howto.html#3">concept checks</A> built
</p>
<p>To prevent you from doing this to yourself, the
<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>
@ -124,85 +124,85 @@
}
</PRE>
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>
</p>
<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="3">Functors</A></H2>
<P>If you don't know what functors are, you're not alone. Many people
<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
the wheel, we will refer you to the introduction to the functor
concept written by SGI as part of their STL, in
<A HREF="http://www.sgi.com/Technology/STL/functors.html">their
http://www.sgi.com/Technology/STL/functors.html</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
<a href="http://www.sgi.com/Technology/STL/functors.html">their
http://www.sgi.com/Technology/STL/functors.html</a>.
</p>
<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="4">Pairs</A></H2>
<P>The <TT>pair&lt;T1,T2&gt;</TT> is a simple and handy way to
<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
type T2; they may be the same type, but you don't get anything
extra if they are. The two members can be accessed directly, as
<TT>.first</TT> and <TT>.second</TT>.
</P>
<P>Construction is simple. The default ctor initializes each member
<code>.first</code> and <code>.second</code>.
</p>
<p>Construction is simple. The default ctor initializes each member
with its respective default ctor. The other simple ctor,
<PRE>
pair (const T1&amp; x, const T2&amp; y);
</PRE>does what you think it does, <TT>first</TT> getting <TT>x</TT>
and <TT>second</TT> getting <TT>y</TT>.
</P>
<P>There is a copy constructor, but it requires that your compiler
</PRE>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>
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
V to T2 in order to perform the respective initializations.
</P>
<P>The comparison operators are done for you. Equality
of two <TT>pair&lt;T1,T2&gt;</TT>s is defined as both <TT>first</TT>
members comparing equal and both <TT>second</TT> members comparing
</p>
<p>The comparison operators are done for you. Equality
of two <code>pair&lt;T1,T2&gt;</code>s is defined as both <code>first</code>
members comparing equal and both <code>second</code> members comparing
equal; this simply delegates responsibility to the respective
<TT>operator==</TT> functions (for types like MyClass) or builtin
<code>operator==</code> functions (for types like MyClass) or builtin
comparisons (for types like int, char, etc).
</P>
<P>The less-than operator is a bit odd the first time you see it. It
</p>
<p>The less-than operator is a bit odd the first time you see it. It
is defined as evaluating to:
<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 <TT>rel_ops</TT>
The other operators are not defined using the <code>rel_ops</code>
functions above, but their semantics are the same.
</P>
<P>Finally, there is a template function called <TT>make_pair</TT>
</p>
<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>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.3 2001/04/03 00:26:55 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.4 2001/05/30 21:55:00 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,60 +1,60 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.2 2001/02/07 00:03:20 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.3 2001/04/03 00:26:55 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 21: Strings</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 21: Strings</a></h1>
<P>Chapter 21 deals with the C++ strings library (a welcome relief).
</P>
<p>Chapter 21 deals with the C++ strings library (a welcome relief).
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">MFC's CString</A></H2>
<P>A common lament seen in various newsgroups deals with the Standard
<h2><a name="1">MFC's CString</a></h2>
<p>A common lament seen in various newsgroups deals with the Standard
string class as opposed to the Microsoft Foundation Class called
CString. Often programmers realize that a standard portable
answer is better than a proprietary nonportable one, but in porting
their application from a Win32 platform, they discover that they
are relying on special functons offered by the CString class.
</P>
<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:
<UL>
<LI>The Standard <TT>string</TT> supports all the operations
</p>
<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:
<ul>
<li>The Standard <code>string</code> supports all the operations
that CString does, with three exceptions.
<LI>Two of those exceptions (whitespace trimming and case
<li>Two of those exceptions (whitespace trimming and case
conversion) are trivial to implement. In fact, we do so
on this page.
<LI>The third is <TT>CString::Format</TT>, which allows formatting
in the style of <TT>sprintf</TT>. This deserves some mention:
</UL>
</P>
<A NAME="1.1internal"> <!-- Coming from Chapter 27 -->
<P>The old libg++ library had a function called form(), which did much
<li>The third is <code>CString::Format</code>, which allows formatting
in the style of <code>sprintf</code>. This deserves some mention:
</ul>
</p>
<a name="1.1internal"> <!-- Coming from Chapter 27 -->
<p>The old libg++ library had a function called form(), which did much
the same thing. But for a Standard solution, you should use the
stringstream classes. These are the bridge between the iostream
hierarchy and the string class, and they operate with regular
@ -80,8 +80,8 @@
return output_stream.str();
} </PRE>
</P></A>
<P>A serious problem with CString is a design bug in its memory
</p></a>
<p>A serious problem with CString is a design bug in its memory
allocation. Specifically, quoting from that same message:
<PRE>
CString suffers from a common programming error that results in
@ -105,40 +105,40 @@
If you replace CString with string in the above function, the
performance is O(n).
</PRE>
</P>
<P>Joe Buck also pointed out some other things to keep in mind when
</p>
<p>Joe Buck also pointed out some other things to keep in mind when
comparing CString and the Standard string class:
<UL>
<LI>CString permits access to its internal representation; coders
who exploited that may have problems moving to <TT>string</TT>.
<LI>Microsoft ships the source to CString (in the files
<ul>
<li>CString permits access to its internal representation; coders
who exploited that may have problems moving to <code>string</code>.
<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
<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>
<LI><TT>string</TT> operations like this have O(n) complexity
<EM>if the implementors do it correctly</EM>. The libstdc++
of the VC++ SPs that did it.</em>
<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>While parts of the SGI STL are used in libstdc++-v3, their
string class is not. The SGI <TT>string</TT> is essentially
<TT>vector&lt;char&gt;</TT> and does not do any reference
<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
counting like libstdc++-v3's does. (It is O(n), though.)
So if you're thinking about SGI's string or rope classes,
you're now looking at four possibilities: CString, the
libstdc++ string, the SGI string, and the SGI rope, and this
is all before any allocator or traits customizations! (More
choices than you can shake a stick at -- want fries with that?)
</UL>
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</ul>
</p>
<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="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>
<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>
discussions held on Usenet covered this topic in January of 1998.
Briefly, the challenge was, &quot;write a 'ci_string' class which
is identical to the standard 'string' class, but is
@ -154,57 +154,57 @@
// still case-preserving, of course
assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
assert( strcmp( s.c_str(), "abcde" ) != 0 ); </PRE>
</P>
</p>
<P>The solution is surprisingly easy. The original answer pages
<p>The solution is surprisingly easy. The original answer pages
on the GotW website were removed into cold storage, in
preparation for
<A HREF="http://cseng.aw.com/bookpage.taf?ISBN=0-201-61562-2">a
published book of GotW notes</A>. Before being
<a href="http://cseng.aw.com/bookpage.taf?ISBN=0-201-61562-2">a
published book of GotW notes</a>. Before being
put on the web, of course, it was posted on Usenet, and that
posting containing the answer is <A HREF="gotw29a.txt">available
here</A>.
</P>
<P>See? Told you it was easy!</P>
<P><B>Added June 2000:</B> The May issue of <U>C++ Report</U> contains
a fascinating article by Matt Austern (yes, <EM>the</EM> Matt Austern)
posting containing the answer is <a href="gotw29a.txt">available
here</a>.
</p>
<p>See? Told you it was easy!</p>
<p><B>Added June 2000:</B> The May issue of <U>C++ Report</U> contains
a fascinating article by Matt Austern (yes, <em>the</em> Matt Austern)
on why case-insensitive comparisons are not as easy as they seem,
and why creating a class is the <EM>wrong</EM> way to go about it in
and why creating a class is the <em>wrong</em> way to go about it in
production code. (The GotW answer mentions one of the principle
difficulties; his article mentions more.)
</P>
<P>Basically, this is &quot;easy&quot; only if you ignore some things,
</p>
<p>Basically, this is &quot;easy&quot; only if you ignore some things,
things which may be too important to your program to ignore. (I chose
to ignore them when originally writing this entry, and am surprised
that nobody ever called me on it...) The GotW question and answer
remain useful instructional tools, however.
</P>
<P><B>Added September 2000:</B> James Kanze provided a link to a
<A HREF="http://www.unicode.org/unicode/reports/tr21/">Unicode
Technical Report discussing case handling</A>, which provides some
</p>
<p><B>Added September 2000:</B> James Kanze provided a link to a
<a href="http://www.unicode.org/unicode/reports/tr21/">Unicode
Technical Report discussing case handling</a>, which provides some
very good information.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="3">Breaking a C++ string into tokens</A></H2>
<P>The Standard C (and C++) function <TT>strtok()</TT> leaves a lot to
<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
destroys the character string on which it operates, and it requires
you to handle all the memory problems. But it does let the client
code decide what to use to break the string into pieces; it allows
you to choose the &quot;whitespace,&quot; so to speak.
</P>
<P>A C++ implementation lets us keep the good things and fix those
</p>
<p>A C++ implementation lets us keep the good things and fix those
annoyances. The implementation here is more intuitive (you only
call it once, not in a loop with varying argument), it does not
affect the original string at all, and all the memory allocation
is handled for you.
</P>
<P>It's called stringtok, and it's a template function. It's given
<A HREF="stringtok_h.txt">in this file</A> in a less-portable form than
</p>
<p>It's called stringtok, and it's a template function. It's given
<a href="stringtok_h.txt">in this file</a> in a less-portable form than
it could be, to keep this example simple (for example, see the
comments on what kind of string it will accept). The author uses
a more general (but less readable) form of it for parsing command
@ -223,39 +223,39 @@
:is:
:a:
:test:</PRE>
with all the whitespace removed. The original <TT>s</TT> is still
available for use, <TT>ls</TT> will clean up after itself, and
<TT>ls.size()</TT> will return how many tokens there were.
</P>
<P>As always, there is a price paid here, in that stringtok is not
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>
<p>As always, there is a price paid here, in that stringtok is not
as fast as strtok. The other benefits usually outweight that, however.
<A HREF="stringtok_std_h.txt">Another version of stringtok is given
here</A>, suggested by Chris King and tweaked by Petr Prikryl,
<a href="stringtok_std_h.txt">Another version of stringtok is given
here</a>, suggested by Chris King and tweaked by Petr Prikryl,
and this one uses the
transformation functions mentioned below. If you are comfortable
with reading the new function names, this version is recommended
as an example.
</P>
<P><B>Added February 2001:</B> Mark Wilden pointed out that the
standard <TT>std::getline()</TT> function can be used with standard
<A HREF="../27_io/howto.html">istringstreams</A> to perform
</p>
<p><B>Added February 2001:</B> Mark Wilden pointed out that the
standard <code>std::getline()</code> function can be used with standard
<a href="../27_io/howto.html">istringstreams</a> to perform
tokenizing as well. Build an istringstream from the input text,
and then use std::getline with varying delimiters (the three-argument
signature) to extract tokens into a string.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="4">Simple transformations</A></H2>
<P>Here are Standard, simple, and portable ways to perform common
transformations on a <TT>string</TT> instance, such as &quot;convert
<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
to all upper case.&quot; The word transformations is especially
apt, because the standard template function
<TT>transform&lt;&gt;</TT> is used.
</P>
<P>This code will go through some iterations (no pun). Here's the
<code>transform&lt;&gt;</code> is used.
</p>
<p>This code will go through some iterations (no pun). Here's the
simplistic version usually seen on Usenet:
<PRE>
#include &lt;string&gt;
@ -277,31 +277,31 @@
std::transform (s.begin(), s.end(), capital_s.begin(), tolower); </PRE>
<SPAN CLASS="larger"><B>Note</B></SPAN> that these calls all involve
the global C locale through the use of the C functions
<TT>toupper/tolower</TT>. This is absolutely guaranteed to work --
but <EM>only</EM> if the string contains <EM>only</EM> characters
from the basic source character set, and there are <EM>only</EM>
<code>toupper/tolower</code>. This is absolutely guaranteed to work --
but <em>only</em> if the string contains <em>only</em> characters
from the basic source character set, and there are <em>only</em>
96 of those. Which means that not even all English text can be
represented (certain British spellings, proper names, and so forth).
So, if all your input forevermore consists of only those 96
characters (hahahahahaha), then you're done.
</P>
<P>At minimum, you can write short wrappers like
</p>
<p>At minimum, you can write short wrappers like
<PRE>
char toLower (char c)
{
return tolower(static_cast&lt;unsigned char&gt;(c));
}</PRE>
</P>
<P>The correct method is to use a facet for a particular locale
</p>
<p>The correct method is to use a facet for a particular locale
and call its conversion functions. These are discussed more in
Chapter 22; the specific part is
<A HREF="../22_locale/howto.html#5">here</A>, which shows the
<a href="../22_locale/howto.html#5">here</a>, which shows the
final version of this code. (Thanks to James Kanze for assistance
and suggestions on all of this.)
</P>
<P>Another common operation is trimming off excess whitespace. Much
</p>
<p>Another common operation is trimming off excess whitespace. Much
like transformations, this task is trivial with the use of string's
<TT>find</TT> family. These examples are broken into multiple
<code>find</code> family. These examples are broken into multiple
statements for readability:
<PRE>
std::string str (" \t blah blah blah \n ");
@ -313,26 +313,26 @@
// trim trailing whitespace
notwhite = str.find_last_not_of(" \t\n");
str.erase(notwhite+1); </PRE>
Obviously, the calls to <TT>find</TT> could be inserted directly
into the calls to <TT>erase</TT>, in case your compiler does not
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 existance.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.2 2001/02/07 00:03:20 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.3 2001/04/03 00:26:55 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,18 +1,18 @@
<HTML>
<HEAD>
<H1>
<html>
<head>
<h1>
Notes on the codecvt implementation.
</H1>
</HEAD>
</h1>
</head>
<I>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000
</I>
<P>
<H2>
<p>
<h2>
1. Abstract
</H2>
<P>
</h2>
<p>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
attempts to detail conversions between the implementation-defined wide
@ -26,12 +26,12 @@ Unicode and UTF8. Design issues and requirements are addressed, and
examples of correct usage for both the required specializations for
wide and narrow characters and the implementation-provided extended
functionality are given.
</P>
</p>
<P>
<H2>
<p>
<h2>
2. What the standard says
</H2>
</h2>
Around page 425 of the C++ Standard, this charming heading comes into view:
<BLOCKQUOTE>
@ -49,11 +49,11 @@ Unicode and EUC.
</I>
</BLOCKQUOTE>
<P>
<p>
Hmm. So, in some unspecified way, Unicode encodings and
translations between other character sets should be handled by this
class.
</P>
</p>
<BLOCKQUOTE>
<I>
@ -61,9 +61,9 @@ class.
</I>
</BLOCKQUOTE>
<P>
<p>
Ah ha! Another clue...
</P>
</p>
<BLOCKQUOTE>
<I>
@ -81,24 +81,24 @@ is useful to communicate to or from the specialized do_convert member.
</I>
</BLOCKQUOTE>
<P>
<p>
At this point, a couple points become clear:
<P>
<p>
One: The standard clearly implies that attempts to add non-required
(yet useful and widely used) conversions need to do so through the
third template parameter, stateT.</P>
third template parameter, stateT.</p>
<P>
<p>
Two: The required conversions, by specifying mbstate_t as the third
template parameter, imply an implementation strategy that is mostly
(or wholly) based on the underlying C library, and the functions
mcsrtombs and wcsrtombs in particular.</P>
mcsrtombs and wcsrtombs in particular.</p>
<P>
<H2>
<p>
<h2>
3. Some thoughts on what would be useful
</H2>
</h2>
Probably the most frequently asked question about code conversion is:
&quot;So dudes, what's the deal with Unicode strings?&quot; The dude part is
optional, but apparently the usefulness of Unicode strings is pretty
@ -106,7 +106,7 @@ widely appreciated. Sadly, this specific encoding (And other useful
encodings like UTF8, UCS4, ISO 8859-10, etc etc etc) are not mentioned
in the C++ standard.
<P>
<p>
In particular, the simple implementation detail of wchar_t's size
seems to repeatedly confound people. Many systems use a two byte,
unsigned integral type to represent wide characters, and use an
@ -117,20 +117,20 @@ 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:
</P>
</p>
<P>
<p>
The thought that all one needs to convert between two arbitrary
codesets is two types and some kind of state argument is
unfortunate. In particular, encodings may be stateless. The naming of
@ -138,101 +138,101 @@ the third parameter as stateT is unfortunate, as what is really needed
is some kind of generalized type that accounts for the issues that
abstract encodings will need. The minimum information that is required
includes:
</P>
</p>
<UL>
<LI>
</P>
<ul>
<li>
</p>
Identifiers for each of the codesets involved in the conversion. For
example, using the iconv family of functions from the Single Unix
Specification (what used to be called X/Open) hosted on the GNU/Linux
operating system allows bi-directional mapping between far more than
the following tantalizing possibilities:
</P>
</p>
(An edited list taken from <TT>`iconv --list`</TT> on a Red Hat 6.2/Intel system:
(An edited list taken from <code>`iconv --list`</code> on a Red Hat 6.2/Intel system:
<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-CCITT, GREEK, GREEK7-OLD,
ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELITTLE, US-ASCII, US, UTF-8,
UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
UTF-16, UTF8, UTF16).
</PRE>
</BLOCKQUOTE>
<P>
<p>
For iconv-based implementations, string literals for each of the
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.
<LI>
<li>
Maximum length of the identifying string literal.
<LI>
<li>
Some encodings are require explicit endian-ness. As such, some kind
of endian marker or other byte-order marker will be necessary. See
&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
the machinery in the &quot;C&quot; library, or the conversion descriptor, for
conversions using iconv (such as the type iconv_t.) Note that the
conversion descriptor encodes more information than a simple encoding
state type.
<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.
</UL>
</ul>
<P>
<H2>
<p>
<h2>
4. Problems with &quot;C&quot; code conversions : thread safety, global
locales, termination.
</H2>
</h2>
In addition, multi-threaded and multi-locale environments also impact
the design and requirements for code conversions. In particular, they
affect the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt;
when implemented using standard &quot;C&quot; functions.
<P>
<p>
Three problems arise, one big, one of medium importance, and one small.
<P>
<p>
First, the small: mcsrtombs and wcsrtombs may not be multithread-safe
on all systems required by the GNU tools. For GNU/Linux and glibc,
this is not an issue.
<P>
<p>
Of medium concern, in the grand scope of things, is that the functions
used to implement this specialization work on null-terminated
strings. Buffers, especially file buffers, may not be null-terminated,
thus giving conversions that end prematurely or are otherwise
incorrect. Yikes!
<P>
<p>
The last, and fundamental problem, is the assumption of a global
locale for all the &quot;C&quot; functions referenced above. For something like
C++ iostreams (where codecvt is explicitly used) the notion of
@ -243,43 +243,43 @@ 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>
<H2>
<p>
<h2>
5. Design
</H2>
</h2>
The two required specializations are implemented as follows:
<P>
<TT>
<p>
<code>
codecvt&lt;char, char, mbstate_t&gt;
</TT>
<P>
</code>
<p>
This is a degenerate (ie, does nothing) specialization. Implementing
this was a piece of cake.
<P>
<TT>
<p>
<code>
codecvt&lt;char, wchar_t, mbstate_t&gt;
</TT>
<P>
</code>
<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
standard explicitly points out that instantiations on the third
template parameter, stateT, are the proper way to implement
@ -289,34 +289,34 @@ 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>
<TT>
<p>
<code>
__enc_traits() : __in_desc(0), __out_desc(0)
</TT>
<P>
</code>
<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>
<TT>
<p>
<code>
__enc_traits(const char* __int, const char* __ext)
</TT>
<P>
</code>
<p>
This constructor takes as parameters string literals that indicate the
desired internal and external encoding. There are no defaults for
either argument.
<P>
<p>
One of the issues with iconv is that the string literals identifying
conversions are not standardized. Because of this, the thought of
mandating and or enforcing some set of pre-determined valid
@ -326,24 +326,24 @@ inducing) strategy was implemented: end-users can specify any string
encodings. It is up to the user to make sure that these strings are
valid on the target system.
<P>
<TT>
<p>
<code>
void
_M_init()
</TT>
<P>
</code>
<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>
<TT>
<p>
<code>
bool
_M_good()
</TT>
<P>
</code>
<p>
Provides a way to see if the given __enc_traits object has been
properly initialized. If the string literals describing the desired
internal and external encoding are not valid, initialization will
@ -352,29 +352,29 @@ 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>
<TT>
<p>
<code>
__enc_traits(const __enc_traits&amp;)
</TT>
<P>
</code>
<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>
<H2>
<p>
<h2>
6. Examples
</H2>
</h2>
<UL>
<LI>
<ul>
<li>
a. conversions involving string literals
<pre>
@ -415,106 +415,106 @@ codecvt usage.
VERIFY( efrom_next == e_lit + size );
VERIFY( ito_next == i_arr + size );
</pre>
<LI>
<li>
b. conversions involving std::string
<LI>
<li>
c. conversions involving std::filebuf and std::ostream
</UL>
</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
</UL>
<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
</ul>
<P>
<H2>
<p>
<h2>
7. Unresolved Issues
</H2>
<UL>
<LI>
</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?
<LI>
<li>
b. conversions involving std::string
<UL>
<LI>
<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>
<li>
conversions between narrow, wide, and unicode strings
</UL>
<LI>
</ul>
<li>
c. conversions involving std::filebuf and std::ostream
<UL>
<LI>
<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>
<li>
wchar_t/char internal buffers and conversions between
internal/external buffers?
</UL>
</UL>
</ul>
</ul>
<P>
<H2>
<p>
<h2>
8. Acknowledgments
</H2>
</h2>
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>
<p>
<h2>
9. Bibliography / Referenced Documents
</H2>
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
<P>
<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

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

@ -1,144 +1,144 @@
<HTML>
<HEAD>
<H1>
<html>
<head>
<h1>
Notes on the ctype implementation.
</H1>
</HEAD>
</h1>
</head>
<I>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
</I>
<P>
<H2>
<p>
<h2>
1. Abstract
</H2>
<P>
</h2>
<p>
Woe is me.
</P>
</p>
<P>
<H2>
<p>
<h2>
2. What the standard says
</H2>
</h2>
<P>
<H2>
<p>
<h2>
3. Problems with &quot;C&quot; ctype : global locales, termination.
</H2>
</h2>
<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>
<H2>
<p>
<h2>
4. Design
</H2>
</h2>
The two required specializations are implemented as follows:
<P>
<TT>
<p>
<code>
ctype&lt;char&gt;
</TT>
<P>
</code>
<p>
This is simple specialization. Implementing this was a piece of cake.
<P>
<TT>
<p>
<code>
ctype&lt;wchar_t&gt;
</TT>
<P>
</code>
<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>
<H2>
<p>
<h2>
5. Examples
</H2>
</h2>
<pre>
typedef ctype<char> cctype;
</pre>
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
</UL>
<ul>
<li> testsuite/22_locale/ctype_char_members.cc
<li> testsuite/22_locale/ctype_wchar_t_members.cc
</ul>
<P>
<H2>
<p>
<h2>
6. Unresolved Issues
</H2>
</h2>
<UL>
<LI> how to deal with the global locale issue?
<ul>
<li> how to deal with the global locale issue?
<LI> how to deal with different types than char, wchar_t?
<li> how to deal with different types than char, wchar_t?
<LI> codecvt/ctype overlap: narrow/widen
<li> codecvt/ctype overlap: narrow/widen
<LI> mask typedef in codecvt_base, argument types in codecvt.
<li> mask typedef in codecvt_base, argument types in codecvt.
what is know about this type?
<LI> why mask* argument in codecvt?
<li> why mask* argument in codecvt?
<LI> can this be made (more) generic? is there a simple way to
<li> can this be made (more) generic? is there a simple way to
straighten out the configure-time mess that is a by-product of
this class?
<LI> get the ctype<wchar_t>::mask stuff under control. Need to
<li> get the ctype<wchar_t>::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<wchar_t>
<LI> rename abstract base class. See if just smash-overriding
<li> rename abstract base class. See if just smash-overriding
is a better approach. Clarify, add sanity to naming.
</UL>
</ul>
<P>
<H2>
<p>
<h2>
7. Acknowledgments
</H2>
</h2>
Ulrich Drepper for patient answering of late-night questions, skeletal
examples, and C language expertise.
<P>
<H2>
<p>
<h2>
8. Bibliography / Referenced Documents
</H2>
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
<P>
<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

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

@ -1,21 +1,21 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.4 2001/08/08 02:48:58 bkoz Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.5 2001/09/15 00:41:11 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 22: Localization</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 22: Localization</a></h1>
<P>Chapter 22 deals with the C++ localization facilities.
</P>
<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,
but I still think it'd be funny.
@ -23,33 +23,33 @@
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<!-- ####################################################### -->
<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>
<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>
<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>.
</P>
<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>.
</p>
<P> The following is the abstract from the implementation notes:
<p> The following is the abstract from the implementation notes:
<BLOCKQUOTE>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
@ -66,68 +66,68 @@
implementation-provided extended functionality are given.
</BLOCKQUOTE>
<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>
<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>
<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>
<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>
<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>
<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>
to Appendix D of his book,
<A HREF="http://www.research.att.com/~bs/3rd.html">The C++
Programming Language (3rd Edition)</A>. It is a detailed
<a href="http://www.research.att.com/~bs/3rd.html">The C++
Programming Language (3rd Edition)</a>. It is a detailed
description of locales and how to use them.
</P>
<P>He also writes:
<BLOCKQUOTE><EM>
</p>
<p>He also writes:
<BLOCKQUOTE><em>
Please note that I still consider this detailed description of
locales beyond the needs of most C++ programmers. It is written
with experienced programmers in mind and novices will do best to
avoid it.
</EM></BLOCKQUOTE>
</P>
</em></BLOCKQUOTE>
</p>
<HR>
<H2><A NAME="6">Nathan Myers on Locales</A></H2>
<P> An article entitled &quot;The Standard C++ Locale&quot; was
<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>
<a href="http://www.cantrip.org/locale.html">here</a>.
</p>
<HR>
<H2><A NAME="7">Correct Transformations</A></H2>
<hr>
<h2><a name="7">Correct Transformations</a></h2>
<!-- Jumping directly here from chapter 21. -->
<P>A very common question on newsgroups and mailing lists is, &quot;How
<p>A very common question on newsgroups and mailing lists is, &quot;How
do I do &lt;foo&gt; to a character string?&quot; where &lt;foo&gt; is
a task such as changing all the letters to uppercase, to lowercase,
testing for digits, etc. A skilled and conscientious programmer
will follow the question with another, &quot;And how do I make the
code portable?&quot;
</P>
<P>(Poor innocent programmer, you have no idea the depths of trouble
</p>
<p>(Poor innocent programmer, you have no idea the depths of trouble
you are getting yourself into. 'Twould be best for your sanity if
you dropped the whole idea and took up basket weaving instead. No?
Fine, you asked for it...)
</P>
<P>The task of changing the case of a letter or classifying a character
</p>
<p>The task of changing the case of a letter or classifying a character
as numeric, graphical, etc, all depends on the cultural context of the
program at runtime. So, first you must take the portability question
into account. Once you have localized the program to a particular
natural language, only then can you perform the specific task.
Unfortunately, specializing a function for a human language is not
as simple as declaring
<TT> extern &quot;Danish&quot; int tolower (int); </TT>.
</P>
<P>The C++ code to do all this proceeds in the same way. First, a locale
<code> extern &quot;Danish&quot; int tolower (int); </code>.
</p>
<p>The C++ code to do all this proceeds in the same way. First, a locale
is created. Then member functions of that locale are called to
perform minor tasks. Continuing the example from Chapter 21, we wish
to use the following convenience functions:
@ -141,19 +141,19 @@
tolower (charT c, const locale&amp; loc) const;
}</PRE>
This function extracts the appropriate &quot;facet&quot; from the
locale <EM>loc</EM> and calls the appropriate member function of that
facet, passing <EM>c</EM> as its argument. The resulting character
locale <em>loc</em> and calls the appropriate member function of that
facet, passing <em>c</em> as its argument. The resulting character
is returned.
</P>
<P>For the C/POSIX locale, the results are the same as calling the
classic C <TT>toupper/tolower</TT> function that was used in previous
</p>
<p>For the C/POSIX locale, the results are the same as calling the
classic C <code>toupper/tolower</code> function that was used in previous
examples. For other locales, the code should Do The Right Thing.
</P>
<P>Of course, these functions take a second argument, and the
</p>
<p>Of course, these functions take a second argument, and the
transformation algorithm's operator argument can only take a single
parameter. So we write simple wrapper structs to handle that.
</P>
<P>The next-to-final version of the code started in Chapter 21 looks like:
</p>
<p>The next-to-final version of the code started in Chapter 21 looks like:
<PRE>
#include &lt;iterator&gt; // for back_inserter
#include &lt;locale&gt;
@ -200,23 +200,23 @@
up
);
}</PRE>
</P>
<P>The final version of the code uses <TT>bind2nd</TT> to eliminate
</p>
<p>The final version of the code uses <code>bind2nd</code> to eliminate
the wrapper structs, but the resulting code is tricky. I have not
shown it here because no compilers currently available to me will
handle it.
</P>
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.4 2001/08/08 02:48:58 bkoz Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.5 2001/09/15 00:41:11 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,45 +1,45 @@
<HTML>
<HEAD>
<H1>
<html>
<head>
<h1>
Notes on the locale implementation.
</H1>
</HEAD>
</h1>
</head>
<I>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I>
<P>
<H2>
<p>
<h2>
1. Abstract Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</H2>
<P>
</P>
</h2>
<p>
</p>
<P>
<H2>
<p>
<h2>
2. What the standard says
See Chapter 22 of the standard.
</H2>
</h2>
<P>
<H2>
<p>
<h2>
3. Problems with &quot;C&quot; locales : global locales, termination.
</H2>
</h2>
<P>
<p>
The major problem is fitting an object-orientated and non-global locale
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>
<h2>
4. Design
</H2>
</h2>
Class locale in non-templatized and has three distinct types nested
inside of it:
@ -69,34 +69,34 @@ Provides an index for looking up specific facets.
class _Impl
<P>
<H2>
<p>
<h2>
5. Examples
</H2>
</h2>
<pre>
typedef __locale_t locale;
</pre>
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
</UL>
<ul>
<li> testsuite/22_locale/ctype_char_members.cc
<li> testsuite/22_locale/ctype_wchar_t_members.cc
</ul>
<P>
<H2>
<p>
<h2>
6. Unresolved Issues
</H2>
</h2>
<UL>
<LI> locale -a displays available locales on linux
<ul>
<li> locale -a displays available locales on linux
<LI> locale initialization: at what point does _S_classic,
<li> locale initialization: at what point does _S_classic,
_S_global get initialized? Can named locales assume this
initialization has already taken place?
<LI> document how named locales error check when filling data
<li> document how named locales error check when filling data
members. Ie, a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention?
@ -105,37 +105,37 @@ More information can be found in the following testcases:
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").
</UL>
</ul>
<P>
<H2>
<p>
<h2>
7. Acknowledgments
</H2>
</h2>
<P>
<H2>
<p>
<h2>
8. Bibliography / Referenced Documents
</H2>
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
<P>
<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

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

@ -1,32 +1,32 @@
<HTML>
<HEAD>
<H1>
<html>
<head>
<h1>
Notes on the messages implementation.
</H1>
</HEAD>
</h1>
</head>
<I>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001
</I>
<P>
<H2>
<p>
<h2>
1. Abstract
</H2>
<P>
</h2>
<p>
The std::messages facet implements message retrieval functionality
equivalent to Java's java.text.MessageFormat .using either GNU gettext
or IEEE 1003.1-200 functions.
</P>
</p>
<P>
<H2>
<p>
<h2>
2. What the standard says
</H2>
</h2>
The std::messages facet is probably the most vaguely defined facet in
the standard library. It's assumed that this facility was built into
the standard library in order to convert string literals from one
locale to the other. For instance, converting the "C" locale's
<TT>const char* c = "please"</TT> to a German-localized <TT>"bitte"</TT>
<code>const char* c = "please"</code> to a German-localized <code>"bitte"</code>
during program execution.
<BLOCKQUOTE>
@ -38,20 +38,20 @@ correspond to three protected virtual member functions.
The public member functions are:
<P>
<TT>catalog open(const basic_string<char>&, const locale&) const</TT>
<p>
<code>catalog open(const basic_string<char>&, const locale&) const</code>
<P>
<TT>string_type get(catalog, int, int, const string_type&) const</TT>
<p>
<code>string_type get(catalog, int, int, const string_type&) const</code>
<P>
<TT>void close(catalog) const</TT>
<p>
<code>void close(catalog) const</code>
<P>
<p>
While the virtual functions are:
<P>
<TT>catalog do_open(const basic_string<char>&, const locale&) const</TT>
<p>
<code>catalog do_open(const basic_string<char>&, const locale&) const</code>
<BLOCKQUOTE>
<I>
-1- Returns: A value that may be passed to get() to retrieve a
@ -62,8 +62,8 @@ catalog can be opened.
</I>
</BLOCKQUOTE>
<P>
<TT>string_type do_get(catalog, int, int, const string_type&) const</TT>
<p>
<code>string_type do_get(catalog, int, int, const string_type&) const</code>
<BLOCKQUOTE>
<I>
-3- Requires: A catalog cat obtained from open() and not yet closed.
@ -73,8 +73,8 @@ be found, returns dfault.
</I>
</BLOCKQUOTE>
<P>
<TT>void do_close(catalog) const</TT>
<p>
<code>void do_close(catalog) const</code>
<BLOCKQUOTE>
<I>
-5- Requires: A catalog cat obtained from open() and not yet closed.
@ -84,30 +84,30 @@ be found, returns dfault.
</BLOCKQUOTE>
<P>
<H2>
<p>
<h2>
3. Problems with &quot;C&quot; messages: thread safety,
over-specification, and assumptions.
</H2>
</h2>
A couple of notes on the standard.
<p>
First, why is <TT>messages_base::catalog</TT> specified as a typedef
First, why is <code>messages_base::catalog</code> specified as a typedef
to int? This makes sense for implementations that use
<TT>catopen</TT>, but not for others. Fortunately, it's not heavily
<code>catopen</code>, but not for others. Fortunately, it's not heavily
used and so only a minor irritant.
<p>
Second, by making the member functions <TT>const</TT>, it is
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>
The 'open' member function in particular seems to be oddly
designed. The signature seems quite peculiar. Why specify a <TT>const
string& </TT> argument, for instance, instead of just <TT>const
char*</TT>? Or, why specify a <TT>const locale&</TT> argument that is
designed. The signature seems quite peculiar. Why specify a <code>const
string& </code> argument, for instance, instead of just <code>const
char*</code>? Or, why specify a <code>const locale&</code> argument that is
to be used in the 'get' member function? How, exactly, is this locale
argument useful? What was the intent? It might make sense if a locale
argument was associated with a given default message string in the
@ -126,10 +126,10 @@ 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>
<H2>
<p>
<h2>
4. Design and Implementation Details
</H2>
</h2>
This is a relatively simple class, on the face of it. The standard
specifies very little in concrete terms, so generic implementations
that are conforming yet do very little are the norm. Adding
@ -137,56 +137,56 @@ functionality that would be useful to programmers and comparable to
Java's java.text.MessageFormat takes a bit of work, and is highly
dependent on the capabilities of the underlying operating system.
<P>
<p>
Three different mechanisms have been provided, selectable via
configure flags:
<UL>
<LI> generic
<P>
<ul>
<li> generic
<p>
This model does very little, and is what is used by default.
</P>
</p>
<LI> gnu
<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
<TT>textdomain, bindtextdomain, gettext</TT>
<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>
</p>
<LI> ieee_1003.1-200x
<P>
<li> ieee_1003.1-200x
<p>
This is a complete, though untested, implementation based on
the IEEE standard. The functions
<TT>catopen, catgets, catclose</TT>
<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 <TT> po2msg.sed</TT> that is part
their use. Note, the script <code> po2msg.sed</code> that is part
of the gettext distribution can convert gettext catalogs into
catalogs that <TT>catopen</TT> can use.
</P>
</UL>
catalogs that <code>catopen</code> can use.
</p>
</ul>
<P>
<p>
A new, standards-conformant non-virtual member function signature was
added for 'open' so that a directory could be specified with a given
message catalog. This simplifies calling conventions for the gnu
model.
<P>
<p>
The rest of this document discusses details of the GNU model.
<P>
<p>
The messages facet, because it is retrieving and converting between
characters sets, depends on the ctype and perhaps the codecvt facet in
a given locale. In addition, underlying "C" library locale support is
necessary for more than just the <TT>LC_MESSAGES</TT> mask:
<TT>LC_CTYPE</TT> is also necessary. To avoid any unpleasantness, all
bits of the "C" mask (ie <TT>LC_ALL</TT>) are set before retrieving
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>
@ -194,61 +194,61 @@ 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:
<UL>
<ul>
<LI > Make a source file with the required string literals
that need to be translated. See
<TT>intl/string_literals.cc</TT> for an example.
<code>intl/string_literals.cc</code> for an example.
<p>
<LI> Make initial catalog (see "4 Making the PO Template File"
<li> Make initial catalog (see "4 Making the PO Template File"
from the gettext docs).
<p>
<TT> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </TT>
<code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code>
<p>
<LI> Make language and country-specific locale catalogs.
<li> Make language and country-specific locale catalogs.
<p>
<TT>cp libstdc++.pot fr_FR.po</TT>
<code>cp libstdc++.pot fr_FR.po</code>
<p>
<TT>cp libstdc++.pot de_DE.po</TT>
<code>cp libstdc++.pot de_DE.po</code>
<p>
<LI> Edit localized catalogs in emacs so that strings are
<li> Edit localized catalogs in emacs so that strings are
translated.
<p>
<TT>emacs fr_FR.po</TT>
<code>emacs fr_FR.po</code>
<P>
<LI> Make the binary mo files.
<p>
<TT>msgfmt fr_FR.po -o fr_FR.mo</TT>
<li> Make the binary mo files.
<p>
<TT>msgfmt de_DE.po -o de_DE.mo</TT>
<code>msgfmt fr_FR.po -o fr_FR.mo</code>
<p>
<code>msgfmt de_DE.po -o de_DE.mo</code>
<P>
<LI> Copy the binary files into the correct directory structure.
<p>
<TT>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</TT>
<li> Copy the binary files into the correct directory structure.
<p>
<TT>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</TT>
<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>
<P>
<LI> Use the new message catalogs.
<p>
<TT>locale loc_de("de_DE");</TT>
<li> Use the new message catalogs.
<p>
<TT>
<code>locale loc_de("de_DE");</code>
<p>
<code>
use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir);
</TT>
</UL>
</code>
</ul>
<P>
<H2>
<p>
<h2>
5. Examples
</H2>
</h2>
<UL>
<LI> message converting, simple example using the GNU model.
<ul>
<li> message converting, simple example using the GNU model.
<pre>
#include <locale>
@ -274,23 +274,23 @@ void test01()
mssg_de.close(cat_de);
}
</pre>
</UL>
</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
</UL>
<ul>
<li> testsuite/22_locale/messages.cc
<li> testsuite/22_locale/messages_byname.cc
<li> testsuite/22_locale/messages_char_members.cc
</ul>
<P>
<H2>
<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
</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
@ -298,16 +298,16 @@ More information can be found in the following testcases:
enough to instantiate the codecvt facet (1 supplied,
need at least 2 but would prefer 3).
<LI> There are issues with gettext needing the global
<li> There are issues with gettext needing the global
locale set to extract a message. This dependence on
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>
</ul>
<p>
<LI> Development versions of the GNU "C" library, glibc 2.3 will allow
<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
@ -316,7 +316,7 @@ More information can be found in the following testcases:
parts of the messages implementation can be switched over to
the new "C" library functionality.
<p>
<LI> At some point in the near future, std::numpunct will probably use
<li> At some point in the near future, std::numpunct will probably use
std::messages facilities to implement truename/falename
correctly. This is currently not done, but entries in
libstdc++.pot have already been made for "true" and "false"
@ -327,19 +327,19 @@ More information can be found in the following testcases:
messages members.
<p>
<LI> The following member functions:
<li> The following member functions:
<p>
<TT>
<code>
catalog
open(const basic_string<char>& __s, const locale& __loc) const
</TT>
</code>
<p>
<TT>
<code>
catalog
open(const basic_string<char>&, const locale&, const char*) const;
</TT>
</code>
<p>
Don't actually return a "value less than 0 if no such catalog
@ -347,58 +347,58 @@ More information can be found in the following testcases:
model. As of this writing, it is unknown how to query to see
if a specified message catalog exists using the gettext
package.
</UL>
</ul>
<P>
<H2>
<p>
<h2>
7. Acknowledgments
</H2>
</h2>
Ulrich Drepper for the character set explanations, gettext details,
and patient answering of late-night questions, Tom Tromey for the java details.
<P>
<H2>
<p>
<h2>
8. Bibliography / Referenced Documents
</H2>
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters
&quot;7 Locales and Internationalization&quot;
<P>
<p>
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> GNU gettext tools, version 0.10.38, Native Language Support
<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

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

@ -1,101 +1,101 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.7 2001/08/24 20:34:34 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.8 2001/09/15 00:41:11 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 23: Containers</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 23: Containers</a></h1>
<P>Chapter 23 deals with container classes and what they offer.
</P>
<p>Chapter 23 deals with container classes and what they offer.
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Making code unaware of the container/array difference</A></H2>
<P>You're writing some code and can't decide whether to use builtin
<h2><a name="1">Making code unaware of the container/array difference</a></h2>
<p>You're writing some code and can't decide whether to use builtin
arrays or some kind of container. There are compelling reasons
to use one of the container classes, but you're afraid that you'll
eventually run into difficulties, change everything back to arrays,
and then have to change all the code that uses those data types to
keep up with the change.
</P>
<P>If your code makes use of the standard algorithms, this isn't as
</p>
<p>If your code makes use of the standard algorithms, this isn't as
scary as it sounds. The algorithms don't know, nor care, about
the kind of &quot;container&quot; on which they work, since the
algorithms are only given endpoints to work with. For the container
classes, these are iterators (usually <TT>begin()</TT> and
<TT>end()</TT>, but not always). For builtin arrays, these are
classes, these are iterators (usually <code>begin()</code> and
<code>end()</code>, but not always). For builtin arrays, these are
the address of the first element and the
<A HREF="../24_iterators/howto.html#2">past-the-end</A> element.
</P>
<P>Some very simple wrapper functions can hide all of that from the
<a href="../24_iterators/howto.html#2">past-the-end</a> element.
</p>
<p>Some very simple wrapper functions can hide all of that from the
rest of the code. For example, a pair of functions called
<TT>beginof</TT> can be written, one that takes an array, another
<code>beginof</code> can be written, one that takes an array, another
that takes a vector. The first returns a pointer to the first
element, and the second returns the vector's <TT>begin()</TT>
element, and the second returns the vector's <code>begin()</code>
iterator.
</P>
<P>The functions should be made template functions, and should also
</p>
<p>The functions should be made template functions, and should also
be declared inline. As pointed out in the comments in the code
below, this can lead to <TT>beginof</TT> being optimized out of
below, this can lead to <code>beginof</code> being optimized out of
existence, so you pay absolutely nothing in terms of increased
code size or execution time.
</P>
<P>The result is that if all your algorithm calls look like
</p>
<p>The result is that if all your algorithm calls look like
<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
of ints to a deque of ints and back again, without ever changing any
client code.
</P>
<P>This author has a collection of such functions, called &quot;*of&quot;
</p>
<p>This author has a collection of such functions, called &quot;*of&quot;
because they all extend the builtin &quot;sizeof&quot;. It started
with some Usenet discussions on a transparent way to find the length
of an array. A simplified and much-reduced version for easier
reading is <A HREF="wrappers_h.txt">given here</A>.
</P>
<P>Astute readers will notice two things at once: first, that the
container class is still a <TT>vector&lt;T&gt;</TT> instead of a
more general <TT>Container&lt;T&gt;</TT>. This would mean that
three functions for <TT>deque</TT> would have to be added, another
three for <TT>list</TT>, and so on. This is due to problems with
reading is <a href="wrappers_h.txt">given here</a>.
</p>
<p>Astute readers will notice two things at once: first, that the
container class is still a <code>vector&lt;T&gt;</code> instead of a
more general <code>Container&lt;T&gt;</code>. This would mean that
three functions for <code>deque</code> would have to be added, another
three for <code>list</code>, and so on. This is due to problems with
getting template resolution correct; I find it easier just to
give the extra three lines and avoid confusion.
</P>
<P>Second, the line
</p>
<p>Second, the line
<PRE>
inline unsigned int lengthof (T (&amp;)[sz]) { return sz; } </PRE>
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>
</p>
<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="2">Variable-sized bitmasks</A></H2>
<P>No, you cannot write code of the form
<hr>
<h2><a name="2">Variable-sized bitmasks</a></h2>
<p>No, you cannot write code of the form
<!-- Careful, the leading spaces in PRE show up directly. -->
<PRE>
#include &lt;bitset&gt;
@ -105,30 +105,30 @@
std::bitset&lt;n&gt; bits;
....
} </PRE>
because <TT>n</TT> must be known at compile time. Your compiler is
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
<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 <TT>bitset&lt;N&gt;</TT>.
<LI>A container&lt;bool&gt;.
<LI>Extremely weird solutions.
</UL>
</P>
<P><B>A very large N in <TT>bitset&lt;N&gt;</TT>.&nbsp;&nbsp;</B> It has
<ul>
<li>A very large N in <code>bitset&lt;N&gt;</code>.
<li>A container&lt;bool&gt;.
<li>Extremely weird solutions.
</ul>
</p>
<p><B>A very large N in <code>bitset&lt;N&gt;</code>.&nbsp;&nbsp;</B> It has
been pointed out a few times in newsgroups that N bits only takes up
(N/8) bytes on most systems, and division by a factor of eight is pretty
impressive when speaking of memory. Half a megabyte given over to a
bitset (recall that there is zero space overhead for housekeeping info;
it is known at compile time exactly how large the set is) will hold over
four million bits. If you're using those bits as status flags (e.g.,
&quot;changed&quot;/&quot;unchanged&quot; flags), that's a <EM>lot</EM>
&quot;changed&quot;/&quot;unchanged&quot; flags), that's a <em>lot</em>
of state.
</P>
<P>You can then keep track of the &quot;maximum bit used&quot; during some
</p>
<p>You can then keep track of the &quot;maximum bit used&quot; during some
testing runs on representative data, make note of how many of those bits
really need to be there, and then reduce N to a smaller number. Leave
some extra space, of course. (If you plan to write code like the
@ -136,73 +136,73 @@
may have to talk your compiler into allowing that much stack space;
there may be zero space overhead, but it's all allocated inside the
object.)
</P>
<P><B>A container&lt;bool&gt;.&nbsp;&nbsp;</B> The Committee made provision
</p>
<p><B>A container&lt;bool&gt;.&nbsp;&nbsp;</B> The Committee made provision
for the space savings possible with that (N/8) usage previously mentioned,
so that you don't have to do wasteful things like
<TT>Container&lt;char&gt;</TT> or <TT>Container&lt;short int&gt;</TT>.
Specifically, <TT>vector&lt;bool&gt;</TT> is required to be
<code>Container&lt;char&gt;</code> or <code>Container&lt;short int&gt;</code>.
Specifically, <code>vector&lt;bool&gt;</code> is required to be
specialized for that space savings.
</P>
<P>The problem is that <TT>vector&lt;bool&gt;</TT> doesn't behave like a
</p>
<p>The problem is that <code>vector&lt;bool&gt;</code> doesn't behave like a
normal vector anymore. There have been recent journal articles which
discuss the problems (the ones by Herb Sutter in the May and
July/August 1999 issues of
<EM>C++ Report</EM> cover it well). Future revisions of the ISO C++
Standard will change the requirement for <TT>vector&lt;bool&gt;</TT>
specialization. In the meantime, <TT>deque&lt;bool&gt;</TT> is
<em>C++ Report</em> cover it well). Future revisions of the ISO C++
Standard will change the requirement for <code>vector&lt;bool&gt;</code>
specialization. In the meantime, <code>deque&lt;bool&gt;</code> is
recommended (although its behavior is sane, you probably will not get
the space savings, but the allocation scheme is different than that
of vector).
</P>
<P><B>Extremely weird solutions.&nbsp;&nbsp;</B> If you have access to
</p>
<p><B>Extremely weird solutions.&nbsp;&nbsp;</B> If you have access to
the compiler and linker at runtime, you can do something insane, like
figuring out just how many bits you need, then writing a temporary
source code file. That file contains an instantiation of <TT>bitset</TT>
source code file. That file contains an instantiation of <code>bitset</code>
for the required number of bits, inside some wrapper functions with
unchanging signatures. Have your program then call the
compiler on that file using Position Independant Code, then open the
newly-created object file and load those wrapper functions. You'll have
an instantiation of <TT>bitset&lt;N&gt;</TT> for the exact <TT>N</TT>
an instantiation of <code>bitset&lt;N&gt;</code> for the exact <code>N</code>
that you need at the time. Don't forget to delete the temporary files.
(Yes, this <EM>can</EM> be, and <EM>has been</EM>, done.)
</P>
(Yes, this <em>can</em> be, and <em>has been</em>, done.)
</p>
<!-- I wonder if this next paragraph will get me in trouble... -->
<P>This would be the approach of either a visionary genius or a raving
<p>This would be the approach of either a visionary genius or a raving
lunatic, depending on your programming and management style. Probably
the latter.
</P>
<P>Which of the above techniques you use, if any, are up to you and your
</p>
<p>Which of the above techniques you use, if any, are up to you and your
intended application. Some time/space profiling is indicated if it
really matters (don't just guess). And, if you manage to do anything
along the lines of the third category, the author would love to hear
from you...
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="3">Containers and multithreading</A></H2>
<P>This section will mention some of the problems in designing MT
<hr>
<h2><a name="3">Containers and multithreading</a></h2>
<p>This section will mention some of the problems in designing MT
programs that use Standard containers. For information on other
aspects of multithreading (e.g., the library as a whole), see
the Received Wisdom on Chapter 17. This section only applies
when gcc and libstdc++-v3 were configured with --enable-threads.
</P>
<P>Two excellent pages to read when working with templatized containers
</p>
<p>Two excellent pages to read when working with templatized 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>. The
<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>. The
libstdc++-v3 uses the same definition of thread safety
when discussing design. A key point that beginners may miss is the
fourth major paragraph of the first page mentioned above
(&quot;For most clients,&quot;...), pointing
out that locking must nearly always be done outside the container,
by client code (that'd be you, not us *grin*).
<EM>However, please take caution when considering the discussion
<em>However, please take caution when considering the discussion
about the user-level configuration of the mutex lock
implementation inside the STL container-memory allocator on that
page. For the sake of this discussion, libstdc++-v3 configures
@ -222,38 +222,38 @@
but you may have two internal ABIs in play within the
application. This might produce races, memory leaks and fatal
crashes. In any multithreaded application using STL, this
is the first thing to study well before blaming the allocator.</EM>
</P>
<P>You didn't read it, did you? *sigh* I'm serious, go read the
is the first thing to study well before blaming the allocator.</em>
</p>
<p>You didn't read it, did you? *sigh* I'm serious, go read the
SGI page. It's really good and doesn't take long, and makes most
of the points that would otherwise have to be made here (and does
a better job).
</P>
<P>That's much better. Now, the issue of MT has been brought up on
</p>
<p>That's much better. Now, the issue of MT has been brought up on
the libstdc++-v3 mailing list as well as the main GCC mailing list
several times. The Chapter 17 HOWTO has some links into the mail
archives, so you can see what's been thrown around. The usual
container (or pseudo-container, depending on how you look at it)
that people have in mind is <TT>string</TT>, which is one of the
that people have in mind is <code>string</code>, which is one of the
points where libstdc++ departs from the SGI STL. As of the
2.90.8 snapshot, the libstdc++-v3 string class is safe for
certain kinds of multithreaded access.
</P>
<P>For implementing a container which does its own locking, it is
</p>
<p>For implementing a container which does its own locking, it is
trivial to (as SGI suggests) provide a wrapper class which obtains
the lock, performs the container operation, then releases the lock.
This could be templatized <EM>to a certain extent</EM>, on the
This could be templatized <em>to a certain extent</em>, on the
underlying container and/or a locking mechanism. Trying to provide
a catch-all general template solution would probably be more trouble
than it's worth.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="4">&quot;Hinting&quot; during insertion</A></H2>
<P>Section [23.1.2], Table 69, of the C++ standard lists this function
<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>
a.insert(p,t);</PRE>
@ -263,86 +263,86 @@
specifies nothing more. (LWG Issue #233, currently in review,
addresses this topic, but I will ignore it here because it is not yet
finalized.)
</P>
<P>Here we'll describe how the hinting works in the libstdc++-v3
</p>
<p>Here we'll describe how the hinting works in the libstdc++-v3
implementation, and what you need to do in order to take advantage of
it. (Insertions can change from logarithmic complexity to amortized
constant time, if the hint is properly used.) Also, since the current
implementation is based on the SGI STL one, these points may hold true
for other library implementations also, since the HP/SGI code is used
in a lot of places.
</P>
<P>In the following text, the phrases <EM>greater than</EM> and <EM>less
than</EM> refer to the results of the strict weak ordering imposed on
</p>
<p>In the following text, the phrases <em>greater than</em> and <em>less
than</em> refer to the results of the strict weak ordering imposed on
the container by its comparison object, which defaults to (basically)
&quot;&lt;&quot;. Using those phrases is semantically sloppy, but I
didn't want to get bogged down in syntax. I assume that if you are
intelligent enough to use your own comparison objects, you are also
intelligent enough to assign &quot;greater&quot; and &quot;lesser&quot;
their new meanings in the next paragraph. *grin*
</P>
<P>If the <TT>hint</TT> parameter ('p' above) is equivalent to:
<UL>
<LI><TT>begin()</TT>, then the item being inserted should have a key
</p>
<p>If the <code>hint</code> parameter ('p' above) is equivalent to:
<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 <TT>begin()</TT>.
<LI><TT>end()</TT>, then the item being inserted should have a key
entry at <code>begin()</code>.
<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 <TT>end()</TT>.
<LI>neither <TT>begin()</TT> nor <TT>end()</TT>, then: Let <TT>h</TT>
be the entry in the container pointed to by <TT>hint</TT>, that
is, <TT>h = *hint</TT>. Then the item being inserted should have
a key less than that of <TT>h</TT>, and greater than that of the
item preceeding <TT>h</TT>. The new item will be inserted
between <TT>h</TT> and <TT>h</TT>'s predecessor.
</UL>
</P>
<P>For <TT>multimap</TT> and <TT>multiset</TT>, the restrictions are
at <code>end()</code>.
<li>neither <code>begin()</code> nor <code>end()</code>, then: Let <code>h</code>
be the entry in the container pointed to by <code>hint</code>, that
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 preceeding <code>h</code>. The new item will be inserted
between <code>h</code> and <code>h</code>'s predecessor.
</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
by &quot;not greater than.&quot; (Why not replace greater with
greater-than-or-equal-to? You probably could in your head, but the
mathematicians will tell you that it isn't the same thing.)
</P>
<P>If the conditions are not met, then the hint is not used, and the
insertion proceeds as if you had called <TT> a.insert(t) </TT>
instead. (<STRONG>Note </STRONG> that GCC releases prior to 3.0.2
had a bug in the case with <TT>hint == begin()</TT> for the
<TT>map</TT> and <TT>set</TT> classes. You should not use a hint
</p>
<p>If the conditions are not met, then the hint is not used, and the
insertion proceeds as if you had called <code> a.insert(t) </code>
instead. (<strong>Note </strong> that GCC releases prior to 3.0.2
had a bug in the case with <code>hint == begin()</code> for the
<code>map</code> and <code>set</code> classes. You should not use a hint
argument in those releases.)
</P>
<P>This behavior goes well with other container's <TT>insert()</TT>
</p>
<p>This behavior goes well with other container's <code>insert()</code>
functions which take an iterator: if used, the new item will be
inserted before the iterator passed as an argument, same as the other
containers. The exception
(in a sense) is with a hint of <TT>end()</TT>: the new item will
actually be inserted after <TT>end()</TT>, but it also becomes the
new <TT>end()</TT>.
</P>
<P><STRONG>Note </STRONG> also that the hint in this implementation is a
(in a sense) is with a hint of <code>end()</code>: the new item will
actually be inserted after <code>end()</code>, but it also becomes the
new <code>end()</code>.
</p>
<p><strong>Note </strong> also that the hint in this implementation is a
one-shot. The insertion-with-hint routines check the immediately
surrounding entries to ensure that the new item would in fact belong
there. If the hint does not point to the correct place, then no
further local searching is done; the search begins from scratch in
logarithmic time. (Further local searching would only increase the
time required when the hint is too far off.)
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="5">Bitmasks and string arguments</A></H2>
<P>Bitmasks do not take char* nor const char* arguments in their
<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
about the problem: follow the library's &quot;Links&quot; from the
homepage, and from the C++ information &quot;defect reflector&quot;
link, select the library issues list. Issue number 116 describes the
problem.
</P>
<P>For now you can simply make a temporary string object using the
</p>
<p>For now you can simply make a temporary string object using the
constructor expression:
<PRE>
std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) );
@ -351,21 +351,21 @@
<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>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.7 2001/08/24 20:34:34 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.8 2001/09/15 00:41:11 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,52 +1,52 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.2 2001/04/03 00:26:56 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.3 2001/05/30 21:55:01 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 24: Iterators</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 24: Iterators</a></h1>
<P>Chapter 24 deals with the FORTRAN subroutines for automatically
<p>Chapter 24 deals with the FORTRAN subroutines for automatically
transforming lemmings into gold.
</P>
</p>
<!-- ####################################################### -->
<HR>
<H1>Contents</H1>
<UL>
<LI><A HREF="#1">They ain't pointers!</A>
<LI><A HREF="#2">It ends <EM>where?</EM></A>
</UL>
<hr>
<h1>Contents</h1>
<ul>
<li><a href="#1">They ain't pointers!</a>
<li><a href="#2">It ends <em>where?</em></a>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">They ain't pointers!</A></H2>
<P><A HREF="../faq/index.html#5_1">FAQ 5.1</A> points out that iterators
<h2><a name="1">They ain't pointers!</a></h2>
<p><a href="../faq/index.html#5_1">FAQ 5.1</a> points out that iterators
are not implemented as pointers. They are a generalization of
pointers, but they are implemented in libstdc++-v3 as separate classes.
</P>
<P>Keeping that simple fact in mind as you design your code will
</p>
<p>Keeping that simple fact in mind as you design your code will
prevent a whole lot of difficult-to-understand bugs.
</P>
<P>You can think of it the other way 'round, even. Since iterators
are a generalization, that means that <EM>pointers</EM> are
<EM>iterators</EM>, and that pointers can be used whenever an
</p>
<p>You can think of it the other way 'round, even. Since iterators
are a generalization, that means that <em>pointers</em> are
<em>iterators</em>, and that pointers can be used whenever an
iterator would be. All those functions in the Algorithms chapter
of the Standard will work just as well on plain arrays and their
pointers.
</P>
<P>That doesn't mean that when you pass in a pointer, it gets wrapped
</p>
<p>That doesn't mean that when you pass in a pointer, it gets wrapped
into some special delegating iterator-to-pointer class with a layer
of overhead. (If you think that's the case anywhere, you don't
understand templates to begin with...) Oh, no; if you pass
@ -55,53 +55,53 @@
its operations, so the resulting code will be doing exactly the same
things as it would be doing if you had hand-coded it yourself (for
the 273rd time).
</P>
<P>How much overhead <EM>is</EM> there when using an interator class?
</p>
<p>How much overhead <em>is</em> there when using an interator class?
Very little. Most of the layering classes contain nothing but
typedefs, and typedefs are &quot;meta-information&quot; that simply
tell the compiler some nicknames; they don't create code. That
information gets passed down through inheritance, so while the
compiler has to do work looking up all the names, your runtime code
does not. (This has been a prime concern from the beginning.)
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="2">It ends <EM>where?</EM></A></H2>
<P>This starts off sounding complicated, but is actually very easy,
<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>Beginners usually have a little trouble understand the whole
</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
</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
<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.
<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
<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>
</ol>
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>:
</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>
beginning end
@ -125,60 +125,60 @@
</PRE>
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
</p>
<p>Now think back to your junior-high school algebra course, when you
were learning how to draw graphs. Remember that a graph terminating
with a solid dot meant, &quot;Everything up through this point,&quot;
and a graph terminating with an open dot meant, &quot;Everything up
to, but not including, this point,&quot; respectively called closed
and open ranges? Remember how closed ranges were written with
brackets, <EM>[a,b]</EM>, and open ranges were written with parentheses,
<EM>(a,b)</EM>?
</P>
<P>The boundary markers for arrays describe a <EM>half-open range</EM>,
brackets, <em>[a,b]</em>, and open ranges were written with parentheses,
<em>(a,b)</em>?
</p>
<p>The boundary markers for arrays describe a <em>half-open range</em>,
starting with (and including) the first element, and ending with (but
not including) the last element: <EM>[beginning,end)</EM>. See, I
not including) the last element: <em>[beginning,end)</em>. See, I
told you it would be simple in the end.
</P>
<P>Iterators, and everything working with iterators, follows this same
time-honored tradition. A container's <TT>begin()</TT> method returns
an iterator referring to the first element, and its <TT>end()</TT>
</p>
<p>Iterators, and everything working with iterators, follows this same
time-honored tradition. A container's <code>begin()</code> method returns
an iterator referring to the first element, and its <code>end()</code>
method returns a past-the-end iterator, which is guaranteed to be
unique and comparable against any other iterator pointing into the
middle of the container.
</P>
<P>Container constructors, container methods, and algorithms, all take
</p>
<p>Container constructors, container methods, and algorithms, all take
pairs of iterators describing a range of values on which to operate.
All of these ranges are half-open ranges, so you pass the beginning
iterator as the starting parameter, and the one-past-the-end iterator
as the finishing parameter.
</P>
<P>This generalizes very well. You can operate on sub-ranges quite
easily this way; functions accepting a <EM>[first,last)</EM> range
</p>
<p>This generalizes very well. You can operate on sub-ranges quite
easily this way; functions accepting a <em>[first,last)</em> range
don't know or care whether they are the boundaries of an entire {array,
sequence, container, whatever}, or whether they only enclose a few
elements from the center. This approach also makes zero-length
sequences very simple to recognize: if the two endpoints compare
equal, then the {array, sequence, container, whatever} is empty.
</P>
<P>Just don't dereference <TT>end()</TT>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Just don't dereference <code>end()</code>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.2 2001/04/03 00:26:56 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.3 2001/05/30 21:55:01 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,95 +1,95 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.3 2001/05/30 21:55:02 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 25: Algorithms</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 25: Algorithms</a></h1>
<P>Chapter 25 deals with the generalized subroutines for automatically
<p>Chapter 25 deals with the generalized subroutines for automatically
transforming lemmings into gold.
</P>
</p>
<!-- ####################################################### -->
<HR>
<H1>Contents</H1>
<UL>
<LI><A HREF="#1">Prerequisites</A>
<LI><A HREF="#2">Topic</A>
</UL>
<hr>
<h1>Contents</h1>
<ul>
<li><a href="#1">Prerequisites</a>
<li><a href="#2">Topic</a>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Prerequisites</A></H2>
<P>The neatest accomplishment of the algorithms chapter is that all the
<h2><a name="1">Prerequisites</a></h2>
<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
<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
<li>The algorithms do not (and cannot) affect the container as a
whole; only the things between the two iterator endpoints. If
you pass a range of iterators only enclosing the middle third of
a container, then anything outside that range is inviolate.
</OL>
</P>
<P>Even strings can be fed through the algorithms here, although the
</ol>
</p>
<p>Even strings can be fed through the algorithms here, although the
string class has specialized versions of many of these functions (for
example, <TT>string::find()</TT>). Most of the examples on this
example, <code>string::find()</code>). Most of the examples on this
page will use simple arrays of integers as a playground for
algorithms, just to keep things simple.
<A NAME="Nsize">The use of <B>N</B></A> as a size in the examples is
<a name="Nsize">The use of <B>N</B></a> as a size in the examples is
to keep things easy to read but probably won't be legal code. You can
use wrappers such as those described in the
<A HREF="../23_containers/howto.html">containers chapter</A> to keep
<a href="../23_containers/howto.html">containers chapter</a> to keep
real code readable.
</P>
<P>The single thing that trips people up the most is the definition of
<EM>range</EM> used with iterators; the famous
</p>
<p>The single thing that trips people up the most is the definition of
<em>range</em> used with iterators; the famous
&quot;past-the-end&quot; rule that everybody loves to hate. The
<A HREF="../24_iterators/howto.html#2">iterators chapter</A> of this
<a href="../24_iterators/howto.html#2">iterators chapter</a> of this
document has a complete explanation of this simple rule that seems to
cause so much confusion. Once you get <EM>range</EM> into your head
cause so much confusion. Once you get <em>range</em> into your head
(it's not that hard, honest!), then the algorithms are a cakewalk.
</P>
<P>
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>
</p>
<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="2">Topic</A></H2>
<P>Blah.
</P>
<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="2">Topic</a></h2>
<p>Blah.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.3 2001/05/30 21:55:02 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.4 2001/09/15 00:41:11 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,108 +1,108 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.2 2001/04/03 00:26:56 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.3 2001/05/30 21:55:03 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 26: Numerics</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 26: Numerics</a></h1>
<P>Chapter 26 deals with building block abstractions to aid in
<p>Chapter 26 deals with building block abstractions to aid in
numerical computing:
<UL>
<LI>Template data structures such as <TT>valarray&lt;&gt;</TT>
and <TT>complex&lt;&gt;</TT>.
<LI>Template numerical functions such as <TT>accumulate</TT>;
<TT>inner_product</TT>; <TT>partial_sum</TT> and
<TT>adjacent_difference</TT>.
</UL>
<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++,
and overloaded versions for <TT>long</TT>, <TT>float</TT>, and
<TT>long double</TT> have been added for all of them.
</P>
and overloaded versions for <code>long</code>, <code>float</code>, and
<code>long double</code> have been added for all of them.
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Complex Number Processing</A></H2>
<P>Using <TT>complex&lt;&gt;</TT> becomes even more comple- er, sorry,
<EM>complicated</EM>, with the not-quite-gratuitously-incompatible
<h2><a name="1">Complex Number Processing</a></h2>
<p>Using <code>complex&lt;&gt;</code> becomes even more comple- er, sorry,
<em>complicated</em>, with the not-quite-gratuitously-incompatible
addition of complex types to the C language. David Tribble has
compiled a list of C++98 and C99 conflict points; his description of
C's new type versus those of C++ and how to get them playing together
nicely is
<A HREF="http://home.flash.net/~dtribble/text/cdiffs.htm#C99.complex">here</A>.
</P>
<P><TT>complex&lt;&gt;</TT> is intended to be instantiated with a
<a href="http://home.flash.net/~dtribble/text/cdiffs.htm#C99.complex">here</a>.
</p>
<p><code>complex&lt;&gt;</code> is intended to be instantiated with a
floating-point type. As long as you meet that and some other basic
requirements, then the resulting instantiation has all of the usual
math operators defined, as well as definitions of <TT>op&lt;&lt;</TT>
and <TT>op&gt;&gt;</TT> that work with iostreams: <TT>op&lt;&lt;</TT>
prints <TT>(u,v)</TT> and <TT>op&gt;&gt;</TT> can read <TT>u</TT>,
<TT>(u)</TT>, and <TT>(u,v)</TT>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
math operators defined, as well as definitions of <code>op&lt;&lt;</code>
and <code>op&gt;&gt;</code> that work with iostreams: <code>op&lt;&lt;</code>
prints <code>(u,v)</code> and <code>op&gt;&gt;</code> can read <code>u</code>,
<code>(u)</code>, and <code>(u,v)</code>.
</p>
<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="2">Array Processing</A></H2>
<P>One of the major reasons why FORTRAN can chew through numbers so well
<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
that C89 is not allowed to make, and neither is C++. C99 adds a new
keyword, <TT>restrict</TT>, to apply to individual pointers. The C++
keyword, <code>restrict</code>, to apply to individual pointers. The C++
solution is contained in the library rather than the language
(although many vendors can be expected to add this to their compilers
as an extension).
</P>
<P>That library solution is a set of two classes, five template classes,
</p>
<p>That library solution is a set of two classes, five template classes,
and &quot;a whole bunch&quot; of functions. The classes are required
to be free of pointer aliasing, so compilers can optimize the
daylights out of them the same way that they have been for FORTRAN.
They are collectively called <TT>valarray</TT>, although strictly
They are collectively called <code>valarray</code>, although strictly
speaking this is only one of the five template classes, and they are
designed to be familiar to people who have worked with the BLAS
libraries before.
</P>
<P>Some more stuff should go here once somebody has time to write it.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Some more stuff should go here once somebody has time to write it.
</p>
<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="3">Numerical Functions</A></H2>
<P>There are four generalized functions in the &lt;numeric&gt; header
<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><TT>accumulate</TT>
<LI><TT>inner_product</TT>
<LI><TT>partial_sum</TT>
<LI><TT>adjacent_difference</TT>
</UL>
</P>
<P>Here is a simple example of the two forms of <TT>accumulate</TT>.
<ul>
<li><code>accumulate</code>
<li><code>inner_product</code>
<li><code>partial_sum</code>
<li><code>adjacent_difference</code>
</ul>
</p>
<p>Here is a simple example of the two forms of <code>accumulate</code>.
<PRE>
int ar[50];
int someval = somefunction();
@ -114,50 +114,50 @@
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
initial value for <TT>sum</TT>. The second does the same, but uses
<TT>someval</TT> as the starting value (thus, <TT>sum_stuff == sum +
someval</TT>). The final call uses the second of the two signatures,
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,
and multiplies all the members of the array; here we must obviously
use 1 as a starting value instead of 0.
</P>
<P>The other three functions have similar dual-signature forms.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>The other three functions have similar dual-signature forms.
</p>
<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="4">C99</A></H2>
<P>In addition to the other topics on this page, we'll note here some
<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.
</P>
<P>The C99 features depend on the <TT>--enable-c99</TT> configure flag.
</p>
<p>The C99 features depend on the <code>--enable-c99</code> configure flag.
This flag is already on by default, but it can be disabled by the
user. Also, the configuration machinery will disable it if the
neccessary support for C99 (e.g., header files) cannot be found.
</P>
<P>As of GCC 3.0, C99 support includes classification functions
such as <TT>isnormal</TT>, <TT>isgreater</TT>, <TT>isnan</TT>, etc.
The functions used for 'long long' support such as <TT>strtoll</TT>
are supported, as is the <TT>lldiv_t</TT> typedef. Also supported
</p>
<p>As of GCC 3.0, C99 support includes classification functions
such as <code>isnormal</code>, <code>isgreater</code>, <code>isnan</code>, etc.
The functions used for 'long long' support such as <code>strtoll</code>
are supported, as is the <code>lldiv_t</code> typedef. Also supported
are the wide character functions using 'long long', like
<TT>wcstoll</TT>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
<code>wcstoll</code>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.2 2001/04/03 00:26:56 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.3 2001/05/30 21:55:03 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,43 +1,43 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.7 2001/07/09 21:47:36 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.8 2001/07/18 21:37:06 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Chapter 27: Input/Output</A></H1>
<h1 CLASS="centered"><a name="top">Chapter 27: Input/Output</a></h1>
<P>Chapter 27 deals with iostreams and all their subcomponents
and extensions. All <EM>kinds</EM> of fun stuff.
</P>
<p>Chapter 27 deals with iostreams and all their subcomponents
and extensions. All <em>kinds</em> of fun stuff.
</p>
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Copying a file</A></H2>
<P>So you want to copy a file quickly and easily, and most important,
<h2><a name="1">Copying a file</a></h2>
<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>
@ -45,8 +45,8 @@
std::ifstream IN ("input_file");
std::ofstream OUT ("output_file"); </PRE>
</P>
<P>Here's the easiest way to get it completely wrong:
</p>
<p>Here's the easiest way to get it completely wrong:
<PRE>
OUT &lt;&lt; IN;</PRE>
For those of you who don't already know why this doesn't work
@ -57,29 +57,29 @@
The quick brown fox jumped over the lazy dog.</PRE>
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>
</p>
<p>Seriously, go do it. Get surprised, then come back. It's worth it.
</p>
<HR WIDTH="60%">
<P>The thing to remember is that the <TT>basic_[io]stream</TT> classes
<p>The thing to remember is that the <code>basic_[io]stream</code> classes
handle formatting, nothing else. In particular, they break up on
whitespace. The actual reading, writing, and storing of data is
handled by the <TT>basic_streambuf</TT> family. Fortunately, the
<TT>operator&lt;&lt;</TT> is overloaded to take an ostream and
handled by the <code>basic_streambuf</code> family. Fortunately, the
<code>operator&lt;&lt;</code> is overloaded to take an ostream and
a pointer-to-streambuf, in order to help with just this kind of
&quot;dump the data verbatim&quot; situation.
</P>
<P>Why a <EM>pointer</EM> to streambuf and not just a streambuf? Well,
</p>
<p>Why a <em>pointer</em> to streambuf and not just a streambuf? Well,
the [io]streams hold pointers (or references, depending on the
implementation) to their buffers, not the actual
buffers. This allows polymorphic behavior on the part of the buffers
as well as the streams themselves. The pointer is easily retrieved
using the <TT>rdbuf()</TT> member function. Therefore, the easiest
using the <code>rdbuf()</code> member function. Therefore, the easiest
way to copy the file is:
<PRE>
OUT &lt;&lt; IN.rdbuf();</PRE>
</P>
<P>So what <EM>was</EM> happening with OUT&lt;&lt;IN? Undefined
</p>
<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
extraction process removes all the whitespace, leaving you with no
@ -88,35 +88,35 @@
member pointers) sometimes gets converted to a void*, and the output
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>
<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.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="2">The buffering is screwing up my program!</A></H2>
<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.
-->
<P>First, are you sure that you understand buffering? Particularly
<p>First, are you sure that you understand buffering? Particularly
the fact that C++ may not, in fact, have anything to do with it?
</P>
<P>The rules for buffering can be a little odd, but they aren't any
</p>
<p>The rules for buffering can be a little odd, but they aren't any
different from those of C. (Maybe that's why they can be a bit
odd.) Many people think that writing a newline to an output
stream automatically flushes the output buffer. This is true only
when the output stream is, in fact, a terminal and not a file
or some other device -- and <EM>that</EM> may not even be true
or some other device -- and <em>that</em> may not even be true
since C++ says nothing about files nor terminals. All of that is
system-dependant. (The &quot;newline-buffer-flushing only occuring
on terminals&quot; thing is mostly true on Unix systems, though.)
</P>
<P>Some people also believe that sending <TT>endl</TT> down an
</p>
<p>Some people also believe that sending <code>endl</code> down an
output stream only writes a newline. This is incorrect; after a
newline is written, the buffer is also flushed. Perhaps this
is the effect you want when writing to a screen -- get the text
@ -136,20 +136,20 @@
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
<TT>endl</TT> if you also need a newline, or just flush the buffer
</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>
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
</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:
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>
std::ofstream os (&quot;/foo/bar/baz&quot;);
std::ifstream is (&quot;/qux/quux/quuux&quot;);
@ -160,48 +160,48 @@
...
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 <TT>rdbuf()</TT>.
Then the public version of <TT>setbuf</TT> can be called. The
</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
arguments are the same as those for the Standard C I/O Library
function (a buffer area followed by its size).
</P>
<P>A great deal of this is implementation-dependant. For example,
<TT>streambuf</TT> does not specify any actions for its own
<TT>setbuf()</TT>-ish functions; the classes derived from
<TT>streambuf</TT> each define behavior that &quot;makes
</p>
<p>A great deal of this is implementation-dependant. For example,
<code>streambuf</code> does not specify any actions for its own
<code>setbuf()</code>-ish functions; the classes derived from
<code>streambuf</code> each define behavior that &quot;makes
sense&quot; for that class: an argument of (0,0) turns off
buffering for <TT>filebuf</TT> but has undefined behavior for
its sibling <TT>stringbuf</TT>, and specifying anything other
buffering for <code>filebuf</code> but has undefined behavior for
its sibling <code>stringbuf</code>, and specifying anything other
than (0,0) has varying effects. Other user-defined class derived
from streambuf can do whatever they want.
</P>
<P>A last reminder: there are usually more buffers involved than
</p>
<p>A last reminder: there are usually more buffers involved than
just those at the language/library level. Kernel buffers, disk
buffers, and the like will also have an effect. Inspecting and
changing those are system-dependant.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="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 <TT>ios::binary</TT> is not, repeat
<EM>not</EM>, the only thing you have to do. It is not a silver
bullet, and will not allow you to use the <TT>&lt;&lt;/&gt;&gt;</TT>
<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
<em>not</em>, the only thing you have to do. It is not a silver
bullet, and will not allow you to use the <code>&lt;&lt;/&gt;&gt;</code>
operators of the normal fstreams to do binary I/O.
</P>
<P>Sorry. Them's the breaks.
</P>
<P>This isn't going to try and be a complete tutorial on reading and
</p>
<p>Sorry. Them's the breaks.
</p>
<p>This isn't going to try and be a complete tutorial on reading and
writing binary files (because &quot;binary&quot;
<A HREF="#7">covers a lot of ground)</A>, but we will try and clear
<a href="#7">covers a lot of ground)</a>, but we will try and clear
up a couple of misconceptions and common errors.
</P>
<P>First, <TT>ios::binary</TT> has exactly one defined effect, no more
</p>
<p>First, <code>ios::binary</code> has exactly one defined effect, no more
and no less. Normal text mode has to be concerned with the newline
characters, and the runtime system will translate between (for
example) '\n' and the appropriate end-of-line sequence (LF on Unix,
@ -213,125 +213,125 @@
if it is doing so in your program then you've discovered a bug in
your vendor's compiler (or some other part of the C++ implementation,
possibly the runtime system).
</P>
<P>Second, using <TT>&lt;&lt;</TT> to write and <TT>&gt;&gt;</TT> to
</p>
<p>Second, using <code>&lt;&lt;</code> to write and <code>&gt;&gt;</code> to
read isn't going to work with the standard file stream classes, even
if you use <TT>skipws</TT> during reading. Why not? Because
ifstream and ofstream exist for the purpose of <EM>formatting</EM>,
if you use <code>skipws</code> during reading. Why not? Because
ifstream and ofstream exist for the purpose of <em>formatting</em>,
not reading and writing. Their job is to interpret the data into
text characters, and that's exactly what you don't want to happen
during binary I/O.
</P>
<P>Third, using the <TT>get()</TT> and <TT>put()/write()</TT> member
</p>
<p>Third, using the <code>get()</code> and <code>put()/write()</code> member
functions still aren't guaranteed to help you. These are
&quot;unformatted&quot; I/O functions, but still character-based.
(This may or may not be what you want, see below.)
</P>
<P>Notice how all the problems here are due to the inappropriate use
of <EM>formatting</EM> functions and classes to perform something
which <EM>requires</EM> that formatting not be done? There are a
</p>
<p>Notice how all the problems here are due to the inappropriate use
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
<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 <TT>mmap()</TT>
<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 <TT>::read()</TT> and <TT>::write()</TT> directly, and
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;
<li>&quot;Use streambufs, that's what they're there for.&quot;
While not trivial for the beginner, this is the best of all
solutions. The streambuf/filebuf layer is the layer that is
responsible for actual I/O. If you want to use the C++
library for binary I/O, this is where you start.
</UL>
</P>
<P>How to go about using streambufs is a bit beyond the scope of this
</ul>
</p>
<p>How to go about using streambufs is a bit beyond the scope of this
document (at least for now), but while streambufs go a long way,
they still leave a couple of things up to you, the programmer.
As an example, byte ordering is completely between you and the
operating system, and you have to handle it yourself.
</P>
<P>Deriving a streambuf or filebuf
</p>
<p>Deriving a streambuf or filebuf
class from the standard ones, one that is specific to your data
types (or an abstraction thereof) is probably a good idea, and
lots of examples exist in journals and on Usenet. Using the
standard filebufs directly (either by declaring your own or by
using the pointer returned from an fstream's <TT>rdbuf()</TT>)
using the pointer returned from an fstream's <code>rdbuf()</code>)
is certainly feasible as well.
</P>
<P>One area that causes problems is trying to do bit-by-bit operations
</p>
<p>One area that causes problems is trying to do bit-by-bit operations
with filebufs. C++ is no different from C in this respect: I/O
must be done at the byte level. If you're trying to read or write
a few bits at a time, you're going about it the wrong way. You
must read/write an integral number of bytes and then process the
bytes. (For example, the streambuf functions take and return
variables of type <TT>int_type</TT>.)
</P>
<P>Another area of problems is opening text files in binary mode.
variables of type <code>int_type</code>.)
</p>
<p>Another area of problems is opening text files in binary mode.
Generally, binary mode is intended for binary files, and opening
text files in binary mode means that you now have to deal with all of
those end-of-line and end-of-file problems that we mentioned before.
An instructive thread from comp.lang.c++.moderated delved off into
this topic starting more or less at
<A HREF="http://www.deja.com/getdoc.xp?AN=436187505">this</A>
<a href="http://www.deja.com/getdoc.xp?AN=436187505">this</a>
article and continuing to the end of the thread. (You'll have to
sort through some flames every couple of paragraphs, but the points
made are good ones.)
</P>
</p>
<HR>
<H2><A NAME="5">What is this &lt;sstream&gt;/stringstreams thing?</A></H2>
<P>Stringstreams (defined in the header <TT>&lt;sstream&gt;</TT>)
<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
sliced time. An example of their use is in the Received Wisdom
section for Chapter 21 (Strings),
<A HREF="../21_strings/howto.html#1.1internal"> describing how to
format strings</A>.
</P>
<P>The quick definition is: they are siblings of ifstream and ofstream,
and they do for <TT>std::string</TT> what their siblings do for
files. All that work you put into writing <TT>&lt;&lt;</TT> and
<TT>&gt;&gt;</TT> functions for your classes now pays off
<EM>again!</EM> Need to format a string before passing the string
to a function? Send your stuff via <TT>&lt;&lt;</TT> to an
<a href="../21_strings/howto.html#1.1internal"> describing how to
format strings</a>.
</p>
<p>The quick definition is: they are siblings of ifstream and ofstream,
and they do for <code>std::string</code> what their siblings do for
files. All that work you put into writing <code>&lt;&lt;</code> and
<code>&gt;&gt;</code> functions for your classes now pays off
<em>again!</em> Need to format a string before passing the string
to a function? Send your stuff via <code>&lt;&lt;</code> to an
ostringstream. You've read a string as input and need to parse it?
Initialize an istringstream with that string, and then pull pieces
out of it with <TT>&gt;&gt;</TT>. Have a stringstream and need to
get a copy of the string inside? Just call the <TT>str()</TT>
out of it with <code>&gt;&gt;</code>. Have a stringstream and need to
get a copy of the string inside? Just call the <code>str()</code>
member function.
</P>
<P>This only works if you've written your
<TT>&lt;&lt;</TT>/<TT>&gt;&gt;</TT> functions correctly, though,
</p>
<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
take the latter, then your I/O operators will work fine with
file streams, but with nothing else -- including stringstreams.
</P>
<P>If you are a user of the strstream classes, you need to update
your code. You don't have to explicitly append <TT>ends</TT> to
</p>
<p>If you are a user of the strstream classes, you need to update
your code. You don't have to explicitly append <code>ends</code> to
terminate the C-style character array, you don't have to mess with
&quot;freezing&quot; functions, and you don't have to manage the
memory yourself. The strstreams have been officially deprecated,
which means that 1) future revisions of the C++ Standard won't
support them, and 2) if you use them, people will laugh at you.
</P>
</p>
<HR>
<H2><A NAME="6">Deriving a stream buffer</A></H2>
<P>Creating your own stream buffers for I/O can be remarkably easy.
<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
excellent books: <EM>Standard C++ IOStreams and Locales</EM> by
excellent books: <em>Standard C++ IOStreams and Locales</em> by
Langer and Kreft, ISBN 0-201-18395-1, and
<A HREF="http://www.josuttis.com/libbook/">The C++ Standard Library</A>
<a href="http://www.josuttis.com/libbook/">The C++ Standard Library</a>
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
Addison-Wesley, who isn't paying us a cent for saying that, honest.
</P>
<P>Here is a simple example, io/outbuf1, from the Josuttis text. It
</p>
<p>Here is a simple example, io/outbuf1, from the Josuttis text. It
transforms everything sent through it to uppercase. This version
assumes many things about the nature of the character type being
used (for more information, read the books or the newsgroups):
@ -374,39 +374,39 @@
}
</PRE>
Try it yourself!
</P>
</p>
<HR>
<H2><A NAME="7">More on binary I/O</A></H2>
<P>Towards the beginning of February 2001, the subject of
<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
same time. One notable place was Usenet, where James Kanze and
Dietmar K&uuml;hl separately posted articles on why attempting
generic binary I/O was not a good idea. (Here are copies of
<A HREF="binary_iostreams_kanze.txt">Kanze's article</A> and
<A HREF="binary_iostreams_kuehl.txt">K&uuml;hl's article</A>.)
</P>
<P>Briefly, the problems of byte ordering and type sizes mean that
the unformatted functions like <TT>ostream::put()</TT> and
<TT>istream::get()</TT> cannot safely be used to communicate
<a href="binary_iostreams_kanze.txt">Kanze's article</a> and
<a href="binary_iostreams_kuehl.txt">K&uuml;hl's article</a>.)
</p>
<p>Briefly, the problems of byte ordering and type sizes mean that
the unformatted functions like <code>ostream::put()</code> and
<code>istream::get()</code> cannot safely be used to communicate
between arbitrary programs, or across a network, or from one
invocation of a program to another invocation of the same program
on a different platform, etc.
</P>
<P>The entire Usenet thread is instructive, and took place under the
</p>
<p>The entire Usenet thread is instructive, and took place under the
subject heading &quot;binary iostreams&quot; on both comp.std.c++
and comp.lang.c++.moderated in parallel. Also in that thread,
Dietmar K&uuml;hl mentioned that he had written a pair of stream
classes that would read and write XDR, which is a good step towards
a portable binary format.
</P>
</p>
<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.
<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
</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>
#include &lt;iostream&gt;
@ -417,54 +417,54 @@
std::cout &lt;&lt; &quot;d!\n&quot;;
</PRE>
This must do what you think it does.
</P>
<P>Alert members of the audience will immediately notice that buffering
</p>
<p>Alert members of the audience will immediately notice that buffering
is going to make a hash of the output unless special steps are taken.
</P>
<P>The special steps taken by libstdc++, at least for version 3.0,
</p>
<p>The special steps taken by libstdc++, at least for version 3.0,
involve doing very little buffering for the standard streams, leaving
most of the buffering to the underlying C library. (This kind of
thing is <A HREF="../explanations.html#cstdio">tricky to get right</A>.)
thing is <a href="../explanations.html#cstdio">tricky to get right</a>.)
The upside is that correctness is ensured. The downside is that
writing through <TT>cout</TT> can quite easily lead to awful
writing through <code>cout</code> can quite easily lead to awful
performance when the C++ I/O library is layered on top of the C I/O
library (as it is for 3.0 by default). Some patches are in the
works which should improve the situation for 3.1.
</P>
<P>However, the C and C++ standard streams only need to be kept in sync
</p>
<p>However, the C and C++ standard streams only need to be kept in sync
when both libraries' facilities are in use. If your program only uses
C++ I/O, then there's no need to sync with the C streams. The right
thing to do in this case is to call
<PRE>
#include <EM>any of the I/O headers such as ios, iostream, etc</EM>
#include <em>any of the I/O headers such as ios, iostream, etc</em>
std::ios::sync_with_stdio(false);
</PRE>
</P>
<P>You must do this before performing any I/O via the C++ stream objects.
</p>
<p>You must do this before performing any I/O via the C++ stream objects.
Once you call this, the C++ streams will operate independantly of the
(unused) C streams. For GCC 3.0, this means that <TT>cout</TT> and
(unused) C streams. For GCC 3.0, this means that <code>cout</code> and
company will become fully buffered on their own.
</P>
<P>Note, by the way, that the synchronization requirement only applies to
the standard streams (<TT>cin</TT>, <TT>cout</TT>, <TT>cerr</TT>,
<TT>clog</TT>, and their wide-character counterparts). File stream
</p>
<p>Note, by the way, that the synchronization requirement only applies to
the standard streams (<code>cin</code>, <code>cout</code>, <code>cerr</code>,
<code>clog</code>, and their wide-character counterparts). File stream
objects that you create yourself have no such requirement and are fully
buffered.
</P>
</p>
<!-- ####################################################### -->
<HR><BR><BR><BR><BR><BR><BR><BR><BR>
<P CLASS="fineprint"><EM>
<hr><br><br><br><br><br><br><br><br>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.7 2001/07/09 21:47:36 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.8 2001/07/18 21:37:06 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,117 +1,117 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<HTML>
<HEAD>
<META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (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">
<!-- $Id: configopts.html,v 1.12 2001/07/09 21:47:35 pme Exp $ -->
</HEAD>
<BODY>
<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">
<title>libstdc++-v3 configure options</title>
<link REL=StyleSheet HREF="lib3styles.css">
<!-- $Id: configopts.html,v 1.13 2001/08/08 02:48:58 bkoz Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Interesting <TT>configure</TT>
options</A></H1>
<h1 CLASS="centered"><a name="top">Interesting <code>configure</code>
options</a></h1>
<P>The latest version of this document is always available at
<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html">
http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html</A>.
</P>
<p>The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html">
http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html</a>.
</p>
<P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
<!-- ####################################################### -->
<HR>
<P>Here are some of the non-obvious options to libstdc++'s configure.
<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. -->
<A HREF="http://sources.redhat.com/autoconf/autoconf.html#SEC74">they
all have opposite forms as well</A>
<a href="http://sources.redhat.com/autoconf/autoconf.html#SEC74">they
all have opposite forms as well</a>
(enable/disable and with/without). The defaults are for current
development sources.
</P>
<P>The canonical way to find out the configure options that are
</p>
<p>The canonical way to find out the configure options that are
available for a given set of libstdc++ sources is to go to the
source directory and then type:<TT> ./configure --help</TT>
source directory and then type:<code> ./configure --help</code>
<DL>
<DT><TT>--enable-multilib </TT>[default]
<DD><P>This is part of the generic multilib support for building cross
<dl>
<dt><code>--enable-multilib </code>[default]
<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>
</p>
<DT><TT>--enable-debug </TT>
<DD><P>The configure script will automatically detect the highest
<dt><code>--enable-debug </code>
<dd><p>The configure script will automatically detect the highest
level of optimization that the compiler in use can use
(certain versions of g++ will ICE if given the <TT>-O2</TT>
(certain versions of g++ will ICE if given the <code>-O2</code>
option, but this is fixed in later versions of the compiler).
This --enable flag will disable all optimizations and instruct
the compiler to emit as much extra debugging information as it
can, for use inside GDB. Note this make command, executed in
the build directory, will do much the same thing, without the
configuration difference:<TT>make CXXFLAGS='-g -O0' all</TT>
</P>
configuration difference:<code>make CXXFLAGS='-g -O0' all</code>
</p>
<DT><TT>--enable-cstdio </TT>
<DD><P>This is an abbreviated form of <TT>'--enable-cstdio=stdio'</TT>
<dt><code>--enable-cstdio </code>
<dd><p>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code>
(described next).
</P>
</p>
<DT><TT>--enable-cstdio=LIB </TT>
<DD><P>Select a target-specific I/O package. As of libstdc++-v3
<dt><code>--enable-cstdio=LIB </code>
<dd><p>Select a target-specific I/O package. As of libstdc++-v3
snapshot 2.91, the choices are 'libio' to specify the GNU
I/O package (from
<A HREF="http://sources.redhat.com/glibc/">glibc</A>, the
<a href="http://sources.redhat.com/glibc/">glibc</a>, the
GNU C library), or 'stdio' to use a generic &quot;C&quot;
abstraction. The default is 'stdio'. A longer explanation
is <A HREF="explanations.html#cstdio">here</A>.
</P>
is <a href="explanations.html#cstdio">here</a>.
</p>
<DT><TT>--enable-sjlj-exceptions </TT>
<DD><P>Forces old, set-jump/long-jump exception handling model. If
<dt><code>--enable-sjlj-exceptions </code>
<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>
</p>
<DT><TT>--enable-clocale </TT>
<DD><P>This is an abbreviated form of <TT>'--enable-clocale=generic'</TT>
<dt><code>--enable-clocale </code>
<dd><p>This is an abbreviated form of <code>'--enable-clocale=generic'</code>
(described next).
</P>
</p>
<DT><TT>--enable-clocale=MODEL </TT>
<DD><P>Select a target-specific underlying locale package. The
<dt><code>--enable-clocale=MODEL </code>
<dd><p>Select a target-specific underlying locale package. The
choices are 'ieee_1003.1' to specify an X/Open, Standard Unix
(IEEE Std. 1003.1-200x) model based on langinfo/iconv/catgets,
'gnu' to specify a model based on functionality from the GNU C
library (langinfo/iconv/gettext) (from <A
HREF="http://sources.redhat.com/glibc/">glibc</A>, the GNU C
HREF="http://sources.redhat.com/glibc/">glibc</a>, the GNU C
library), or 'generic' to use a generic &quot;C&quot;
abstraction which consists of &quot;C&quot; locale info. The
default is 'generic'.
</P>
</p>
<DT><TT>--enable-c99 </TT>
<DD><P>The &quot;long long&quot; type was introduced in C99, along
<dt><code>--enable-c99 </code>
<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
specified by the C++ standard will be put into <TT>namespace
__gnu_cxx</TT>, and then all these names will
specified by the C++ standard will be put into <code>namespace
__gnu_cxx</code>, and then all these names will
be injected into namespace std, so that C99 functions can be
used &quot;as if&quot; they were in the C++ standard (as they
will eventually be in some future revision of the standard,
without a doubt). By default, C99 support is on, assuming the
configure probes find all the necessary functions and bits
necessary.
</P>
</p>
<DT><TT>--enable-long-long </TT>
<DD><P>The &quot;long long&quot; type was introduced in C99. It is
<dt><code>--enable-long-long </code>
<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
templates and the like for iostreams). This option is on by default:
@ -121,22 +121,22 @@ options</A></H1>
allow &quot;C&quot; visibility of this feature (on GNU/Linux,
the flag is -D_ISOC99_SOURCE, which is added automatically via
CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
</P>
</p>
<DT><TT>--enable-cheaders=OPTION </TT>
<DD><P>This allows the user to define what kind of C headers are
<dt><code>--enable-cheaders=OPTION </code>
<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>
</p>
<DT><TT>--enable-threads </TT>
<DD><P>This is an abbreviated form of <TT>'--enable-threads=yes'</TT>
<dt><code>--enable-threads </code>
<dd><p>This is an abbreviated form of <code>'--enable-threads=yes'</code>
(described next).
</P>
</p>
<DT><TT>--enable-threads=LIB </TT>
<DD><P>Select a threading library. As of libstdc++-v3 snapshot 2.91,
<dt><code>--enable-threads=LIB </code>
<dd><p>Select a threading library. As of libstdc++-v3 snapshot 2.91,
the choices are:
'yes' for some kind of default (hmmmmm);
'decosf1', 'irix', 'mach', 'os2', 'posix'/'pthreads'
@ -145,35 +145,35 @@ options</A></H1>
corresponding interface;
and 'single', 'no', or 'none' for the null-case,
single-threaded library.
</P>
<P>All of this is currently undergoing a lot of changes. As of
</p>
<p>All of this is currently undergoing a lot of changes. As of
2.91, 'single' and 'posix' are the only implemented
models. Default is single.
</P>
</p>
<DT><TT>--enable-version-specific-runtime-libs </TT>
<DD><P>Specify that run-time libraries should be installed in the
<dt><code>--enable-version-specific-runtime-libs </code>
<dd><p>Specify that run-time libraries should be installed in the
compiler-specific subdirectory (i.e.,
<TT>${libdir}/gcc-lib/${target_alias}/${gcc_version}</TT>)
instead of <TT>${libdir}</TT>. This option is useful if you
<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>)
instead of <code>${libdir}</code>. This option is useful if you
intend to use several versions of gcc in parallel. In addition,
libstdc++'s include files will be installed in
<TT>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</TT>,
<code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>,
unless you also specify
<TT>--with-gxx-include-dir=<EM>dirname</EM></TT> during configuration.
</P>
<code>--with-gxx-include-dir=<em>dirname</em></code> during configuration.
</p>
<DT><TT>--with-gxx-include-dir=&lt;include-files dir&gt;</TT>
<DD><P>Adds support for named libstdc++ include directory. For instance,
<dt><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code>
<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;.
<PRE>
--with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</PRE>
</P>
</p>
<DT><TT>--enable-cxx-flags=FLAGS</TT>
<DD><P>With this option, you can pass a string of -f (functionality)
<dt><code>--enable-cxx-flags=FLAGS</code>
<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
<PRE>
@ -181,13 +181,13 @@ options</A></H1>
Note that the flags don't necessarily have to all be -f flags,
as shown, but usually those are the ones that will make sense
for experimentation and configure-time overriding.
</P>
<P>The advantage of --enable-cxx-flags over setting CXXFLAGS in
</p>
<p>The advantage of --enable-cxx-flags over setting CXXFLAGS in
the 'make' environment is that, if files are automatically
rebuilt, the same flags will be used when compiling those files
as well, so that everything matches.
</P>
<P>Fun flags to try might include combinations of
</p>
<p>Fun flags to try might include combinations of
<PRE>
-fstrict-aliasing
-fno-exceptions
@ -195,30 +195,30 @@ options</A></H1>
-fvtable-gc</PRE>
and opposite forms (-fno-) of the same. Tell us (the mailing
list) if you discover more!
</P>
</p>
<DT><TT>--enable-c-mbchar </TT>[default]
<DD><P>Certain template specializations are required for wide
<dt><code>--enable-c-mbchar </code>[default]
<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.
Disabling wide character specializations is useful for initial
porting steps, but builds only a subset of what is required by
ISO. By default, this option is on.
</P>
</DL>
</P>
<P>Return <A HREF="#top">to the top of the page</A> or
<A HREF="http://gcc.gnu.org/libstdc++/">to the homepage</A>.
</P>
</p>
</dl>
</p>
<p>Return <a href="#top">to the top of the page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
$Id: configopts.html,v 1.12 2001/07/09 21:47:35 pme Exp $
</EM></P>
<hr>
<P CLASS="fineprint"><em>
$Id: configopts.html,v 1.13 2001/08/08 02:48:58 bkoz Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,98 +1,98 @@
<HTML>
<HEAD>
<META NAME="KEYWORDS" CONTENT="libstdc++, homepage, home, g++, libg++, STL">
<TITLE>Standard C++ Library v3</TITLE>
<LINK REL=StyleSheet HREF="lib3styles.css">
<!-- $Id: documentation.html,v 1.4 2001/05/30 21:54:56 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta NAME="KEYWORDS" CONTENT="libstdc++, homepage, home, g++, libg++, STL">
<title>Standard C++ Library v3</title>
<link REL=StyleSheet HREF="lib3styles.css">
<!-- $Id: documentation.html,v 1.5 2001/06/15 22:57:30 pme Exp $ -->
</head>
<body>
<P><B>All of these documents</B> (in fact, this entire homepage set) are
bundled with the library source, under the <TT>docs</TT> subdirectory,
<p><B>All of these documents</B> (in fact, this entire homepage set) are
bundled with the library source, under the <code>docs</code> subdirectory,
for releases and snapshots. The sole exception is the
automatically-generated source documentation, available separately.
</P>
</p>
<HR>
<H2><A NAME="4">Source Documentation</A></H2>
<P>In addition to the distribution documentation (these pages), we also
<hr>
<h2><a name="4">Source Documentation</a></h2>
<p>In addition to the distribution documentation (these pages), we also
have a set of HTML documents generated from the sources themselves,
using the Doxygen tool. These are useful for examining the signatures
of public member functions for the library classes, etc.
</P>
<P>
</p>
<p>
The latest collection is for the GCC 3.0 release,
<TT>libstdc++-doxygen-3.0.tar.gz</TT> (3.8MB),
<A HREF="libstdc++-doxygen-3.0/index.html">viewable online</A>.
<code>libstdc++-doxygen-3.0.tar.gz</code> (3.8MB),
<a href="libstdc++-doxygen-3.0/index.html">viewable online</a>.
The collection is also available in the libstdc++ snapshots directory at
<TT>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/&gt;</TT>. You will
<code>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/&gt;</code>. You will
almost certainly need to use one of the
<A HREF="http://gcc.gnu.org/mirrors.html">mirror sites</A> to download
<a href="http://gcc.gnu.org/mirrors.html">mirror sites</a> to download
the tarball. After unpacking, simply load
libstdc++-doxygen-3.0/index.html <!-- also update this date -->
in a browser. Feedback (and additional documentation!) is welcome.
</P>
</p>
<!-- another paragraph here for post-release collections -->
<HR>
<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><BR>
</UL>
<hr>
<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><br>
</ul>
<HR>
<H2><A NAME="1">Introductory notes for libstdc++</A></H2>
<P>This is a short list of text files pertaining to this
<hr>
<h2><a name="1">Introductory notes for libstdc++</a></h2>
<p>This is a short list of text files pertaining to this
implementation of ISO 14882. A brief description follows the name
of the file.
</P>
<P>
<UL>
<LI><A HREF="17_intro/BADNAMES">BADNAMES</A>
</p>
<p>
<ul>
<li><a href="17_intro/BADNAMES">BADNAMES</a>
- names to avoid because of potential collisions
<LI><A HREF="17_intro/BUGS">BUGS</A>
<LI><A HREF="17_intro/C++STYLE">C++STYLE</A>
<li><a href="17_intro/BUGS">BUGS</a>
<li><a href="17_intro/C++STYLE">C++STYLE</a>
- coding style by example
<LI><A HREF="17_intro/CHECKLIST">CHECKLIST</A>
<li><a href="17_intro/CHECKLIST">CHECKLIST</a>
- a list of required features and their status.
<LI><A HREF="17_intro/COPYING">COPYING</A>
<li><a href="17_intro/COPYING">COPYING</a>
- GPL v2 license terms
<LI><A HREF="17_intro/DESIGN">DESIGN</A>
<li><a href="17_intro/DESIGN">DESIGN</a>
- overview of the implementation plan
<LI><A HREF="17_intro/HEADER_POLICY">HEADER_POLICY</A>
<li><a href="17_intro/headER_POLICY">headER_POLICY</a>
- header naming and sub-include structure
<LI><A HREF="17_intro/PROBLEMS">PROBLEMS</A>
<li><a href="17_intro/PROBLEMS">PROBLEMS</a>
<!-- Linking to "../README" doesn't work; we are at the top level
of the web pages. Punt. -->
<LI>README - directory structure
<LI><A HREF="17_intro/RELEASE-NOTES">RELEASE-NOTES</A>
<li>README - directory structure
<li><a href="17_intro/RELEASE-NOTES">RELEASE-NOTES</a>
- instructions for building, using
<LI><A HREF="17_intro/TODO">TODO</A>
<li><a href="17_intro/TODO">TODO</a>
- tasks and known bugs
<LI><A HREF="17_intro/organization">organization</A>
<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>
</UL>
</P>
<li><a href="17_intro/organization">organization</a>
<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>
</ul>
</p>
<HR>
<H2><A NAME="3">Chapter-Specific Information, Extensions, Notes and Advice</A></H2>
<OL>
<LI><A HREF="17_intro/howto.html">Chapter 17 (Intro)</A>
<LI><A HREF="18_support/howto.html">Chapter 18 (Library Support)</A>
<LI><A HREF="19_diagnostics/howto.html">Chapter 19 (Diagnostics)</A>
<LI><A HREF="20_util/howto.html">Chapter 20 (Utilities)</A>
<LI><A HREF="21_strings/howto.html">Chapter 21 (Strings)</A>
<LI><A HREF="22_locale/howto.html">Chapter 22 (Localization)</A>
<LI><A HREF="23_containers/howto.html">Chapter 23 (Containers)</A>
<LI><A HREF="24_iterators/howto.html">Chapter 24 (Iterators)</A>
<LI><A HREF="25_algorithms/howto.html">Chapter 25 (Algorithms)</A>
<LI><A HREF="26_numerics/howto.html">Chapter 26 (Numerics)</A>
<LI><A HREF="27_io/howto.html">Chapter 27 (I/O)</A>
<LI><A HREF="ext/howto.html">Extensions to the Standard Library</A>
</OL>
<hr>
<h2><a name="3">Chapter-Specific Information, Extensions, Notes and Advice</a></h2>
<ol>
<li><a href="17_intro/howto.html">Chapter 17 (Intro)</a>
<li><a href="18_support/howto.html">Chapter 18 (Library Support)</a>
<li><a href="19_diagnostics/howto.html">Chapter 19 (Diagnostics)</a>
<li><a href="20_util/howto.html">Chapter 20 (Utilities)</a>
<li><a href="21_strings/howto.html">Chapter 21 (Strings)</a>
<li><a href="22_locale/howto.html">Chapter 22 (Localization)</a>
<li><a href="23_containers/howto.html">Chapter 23 (Containers)</a>
<li><a href="24_iterators/howto.html">Chapter 24 (Iterators)</a>
<li><a href="25_algorithms/howto.html">Chapter 25 (Algorithms)</a>
<li><a href="26_numerics/howto.html">Chapter 26 (Numerics)</a>
<li><a href="27_io/howto.html">Chapter 27 (I/O)</a>
<li><a href="ext/howto.html">Extensions to the Standard Library</a>
</ol>
</BODY>
</HTML>
</body>
</html>

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

@ -1,74 +1,74 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<HTML>
<HEAD>
<META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (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">
<!-- $Id: configopts.html,v 1.10 2001/04/20 08:59:25 bkoz Exp $ -->
</HEAD>
<BODY>
<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">
<title>Explanatory notes about libstdc++-v3 design</title>
<link REL=StyleSheet HREF="lib3styles.css">
<!-- $Id: explanations.html,v 1.1 2001/07/09 19:37:01 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Explanatory notes about libstdc++-v3
design</A></H1>
<h1 CLASS="centered"><a name="top">Explanatory notes about libstdc++-v3
design</a></h1>
<P>The latest version of this document is always available at
<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html">
http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html</A>.
</P>
<p>The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html">
http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html</a>.
</p>
<P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
<!-- ####################################################### -->
<HR>
<A NAME="cstdio"><H3>&quot;I/O packages&quot;, <TT>--enable-cstdio</TT></H3></A>
<P>In addition to all the nifty things which C++ can do for I/O, its library
<hr>
<a name="cstdio"><h3>&quot;I/O packages&quot;, <code>--enable-cstdio</code></h3></a>
<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
<A HREF="27_io/howto.html#8">for the programmer</A> but for the
<a href="27_io/howto.html#8">for the programmer</a> but for the
implementors as well.
</P>
<P>There are two ways to do a C++ library: the cool way, and the easy way.
</p>
<p>There are two ways to do a C++ library: the cool way, and the easy way.
More specifically, the cool-but-easy-to-get-wrong way, and the
easy-to-guarantee-correct-behavior way. For 3.0, the easy way is used.
</P>
<P>Choosing 'stdio' is the easy way. It builds a C++ library which forwards
</p>
<p>Choosing 'stdio' is the easy way. It builds a C++ library which forwards
all operations to the C library. Many of the C++ I/O functions are
specified in the standard 'as if' they called a certain C function; the
easiest way to get it correct is to actually call that function. The
disadvantage is that the C++ code will run slower (fortunately, the layer
is thin).
</P>
<P>Choosing 'libio' is the cool way; it allows C++ and C to share some
</p>
<p>Choosing 'libio' is the cool way; it allows C++ and C to share some
buffers. It's disabled because of tricky synchronization issues. Other
cool ways (various methods of sharing resources between C and C++
facilities, instead of layering) are possible. This approach can speed
up I/O significantly.
</P>
<P>Other packages are possible. For a new package, a header must be
</p>
<p>Other packages are possible. For a new package, a header must be
written to provide types like streamsize (usually just a typedef), as
well as some internal types like<TT> __c_file_type </TT> and
<TT> __c_lock </TT> (for the stdio case, these are FILE (as in
well as some internal types like<code> __c_file_type </code> and
<code> __c_lock </code> (for the stdio case, these are FILE (as in
&quot;FILE*&quot;) and a simple POSIX mutex, respectively). An
interface class called <TT> __basic_file </TT> must also be filled in;
interface class called <code> __basic_file </code> must also be filled in;
as an example, for the stdio case, these member functions are all
inline calles to fread, fwrite, etc.
</P>
<P>Return <A HREF="#top">to the top of the page</A> or
<A HREF="http://gcc.gnu.org/libstdc++/">to the homepage</A>.
</P>
</p>
<p>Return <a href="#top">to the top of the page</a> or
<a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
$Id$
</EM></P>
<hr>
<P CLASS="fineprint"><em>
$Id: explanations.html,v 1.1 2001/07/09 19:37:01 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

@ -1,53 +1,53 @@
<!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@sources.redhat.com (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">
<!-- $Id: howto.html,v 1.4 2001/05/02 01:39:03 pme Exp $ -->
</HEAD>
<BODY>
<html>
<head>
<meta HcodeP-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">
<!-- $Id: howto.html,v 1.5 2001/05/30 21:55:04 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">Extensions</A></H1>
<h1 CLASS="centered"><a name="top">Extensions</a></h1>
<P>Here we will make an attempt at describing the non-Standard extensions to
<p>Here we will make an attempt at describing the non-Standard extensions to
the library. Some of these are from SGI's STL, some of these are GNU's,
and some just seemed to appear on the doorstep.
</P>
<P><B>Before you leap in and use these</B>, be aware of two things:
<OL>
<LI>Non-Standard means exactly that. The behavior, and the very
</p>
<p><B>Before you leap in and use these</B>, 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>
<li>You should know how to <a href="../faq/index.html#5_4">access
these headers properly</a>.
</ol>
</p>
<!-- ####################################################### -->
<HR>
<H1>Contents</H1>
<UL>
<LI><A HREF="#1">Ropes and trees and hashes, oh my!</A>
<LI><A HREF="#2">Added members</A>
<LI><A HREF="#3">Allocators</A>
<LI><A HREF="#4">Compile-time checks</A>
</UL>
<hr>
<h1>Contents</h1>
<ul>
<li><a href="#1">Ropes and trees and hashes, oh my!</a>
<li><a href="#2">Added members</a>
<li><a href="#3">Allocators</a>
<li><a href="#4">Compile-time checks</a>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="1">Ropes and trees and hashes, oh my!</A></H2>
<P>The SGI headers
<h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
<p>The SGI headers
<PRE>
&lt;bvector&gt;
&lt;hash_map&gt;
@ -55,120 +55,120 @@
&lt;rope&gt;
&lt;slist&gt;
&lt;tree&gt;
</PRE> are all here; <TT>&lt;bvector&gt;</TT> exposes the old bit_vector
</PRE> 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).
<TT>&lt;hash_map&gt;</TT> and <TT>&lt;hash_set&gt;</TT>
are discussed further below. <TT>&lt;rope&gt;</TT> is the SGI
<code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
are discussed further below. <code>&lt;rope&gt;</code> is the SGI
specialization for large strings (&quot;rope,&quot; &quot;large
strings,&quot; get it? love those SGI folks).
<TT>&lt;slist&gt;</TT> is a singly-linked list, for when the
doubly-linked <TT>list&lt;&gt;</TT> is too much space overhead, and
<TT>&lt;tree&gt;</TT> exposes the red-black tree classes used in the
<code>&lt;slist&gt;</code> is a singly-linked list, for when the
doubly-linked <code>list&lt;&gt;</code> is too much space overhead, and
<code>&lt;tree&gt;</code> exposes the red-black tree classes used in the
implementation of the standard maps and sets.
</P>
<P>Okay, about those hashing classes... I'm going to foist most of the
</p>
<p>Okay, about those hashing classes... I'm going to foist most of the
work off onto SGI's own site.
</P>
<P>Each of the associative containers map, multimap, set, and multiset
</p>
<p>Each of the associative containers map, multimap, set, and multiset
have a counterpart which uses a
<A HREF="http://www.sgi.com/Technology/STL/HashFunction.html">hashing
function</A> to do the arranging, instead of a strict weak ordering
<a href="http://www.sgi.com/Technology/STL/HashFunction.html">hashing
function</a> to do the arranging, instead of a strict weak ordering
function. The classes take as one of their template parameters a
function object that will return the hash value; by default, an
instantiation of
<A HREF="http://www.sgi.com/Technology/STL/hash.html">hash</A>.
<a href="http://www.sgi.com/Technology/STL/hash.html">hash</a>.
You should specialize this functor for your class, or define your own,
before trying to use one of the hashing classes.
</P>
<P>The hashing classes support all the usual associative container
</p>
<p>The hashing classes support all the usual associative container
functions, as well as some extra constructors specifying the number
of buckets, etc.
</P>
<P>Why would you want to use a hashing class instead of the
</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
<BLOCKQUOTE><em>[W]ith a well chosen hash function, hash tables
generally provide much better average-case performance than binary
search trees, and much worse worst-case performance. So if your
implementation has hash_map, if you don't mind using nonstandard
components, and if you aren't scared about the possibility of
pathological cases, you'll probably get better performance from
hash_map.</EM></BLOCKQUOTE>
</P>
<P>(Side note: for those of you wondering, <B>&quot;Why wasn't a hash
hash_map.</em></BLOCKQUOTE>
</p>
<p>(Side note: for those of you wondering, <B>&quot;Why wasn't a hash
table included in the Standard in the first #!$@ place?&quot;</B> 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.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="2">Added members</A></H2>
<P>Some of the classes in the Standard Library have additional
<hr>
<h2><a name="2">Added members</a></h2>
<p>Some of the classes in the Standard Library have additional
publicly-available members. Of those, some are intended purely for
the implementors, for example, additional typedefs. Those won't be
described here (or anywhere else). This list will grow slowly, since
we expect it to be rare -- most extensions will be self-contained.
</P>
<P>
<UL>
<LI><TT>filebuf</TT>s have another ctor with this signature:<BR>
<TT>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</TT>
<BR>This comes in very handy in a number of places, such as
</p>
<p>
<ul>
<li><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><TT>__c_file_type* F </TT>
<ul>
<li><code>__c_file_type* F </code>
// the __c_file_type typedef usually boils down to stdio's FILE
<LI><TT>ios_base::openmode M </TT>
<li><code>ios_base::openmode M </code>
// same as all the other uses of openmode
<LI><TT>int_type B </TT>
<li><code>int_type B </code>
// buffer size, defaults to BUFSIZ
</UL>
</ul>
For those wanting to use file descriptors instead of FILE*'s, I
invite you to contemplate the mysteries of C's <TT>fdopen()</TT>.
</UL>
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
invite you to contemplate the mysteries of C's <code>fdopen()</code>.
</ul>
</p>
<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="3">Allocators</A></H2>
<P>This will be blank for a while. It will describe all of the different
<hr>
<h2><a name="3">Allocators</a></h2>
<p>This will be blank for a while. It will describe all of the different
memory allocators, most inherited from SGI's code. Input is solicited.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<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="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
compile-time checking</A> of template instantiations of the standard
<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
compile-time checking</a> of template instantiations of the standard
containers. They are described in the linked-to page.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: howto.html,v 1.4 2001/05/02 01:39:03 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: howto.html,v 1.5 2001/05/30 21:55:04 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>

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

File diff suppressed because it is too large Load diff

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

@ -1,7 +1,7 @@
libstdc++ Frequently Asked Questions
The latest version of this document is always available at
The latest version of this document is always available at
[1]http://gcc.gnu.org/onlinedocs/libstdc++/faq/.
To the [2]libstdc++-v3 homepage.
@ -33,7 +33,7 @@
3. [24]Bugs in the C++ language/lib specification
4. [25]Things in libstdc++ that look like bugs
o [26]-Weffc++ complains too much
o [27]"ambiguous overloads" after including an old-style
o [27]"ambiguous overloads" after including an old-style
header
o [28]The g++-3 headers are not ours
o [29]compilation errors from streambuf.h
@ -54,13 +54,13 @@
1.1 What is libstdc++-v3?
The GNU Standard C++ Library v3, or libstdc++-2.9x, is an ongoing
project to implement the ISO 14882 Standard C++ library as described
in chapters 17 through 27 and annex D. As the library reaches stable
plateaus, it is captured in a snapshot and released. The current
release is [40]the eleventh snapshot. For those who want to see
exactly how far the project has come, or just want the latest
bleeding-edge code, the up-to-date source is available over anonymous
The GNU Standard C++ Library v3, or libstdc++-2.9x, is an ongoing
project to implement the ISO 14882 Standard C++ library as described
in chapters 17 through 27 and annex D. As the library reaches stable
plateaus, it is captured in a snapshot and released. The current
release is [40]the eleventh snapshot. For those who want to see
exactly how far the project has come, or just want the latest
bleeding-edge code, the up-to-date source is available over anonymous
CVS, and can even be browsed over the Web (see below).
A more formal description of the V3 goals can be found in the official
@ -70,94 +70,94 @@
1.2 Why should I use libstdc++?
The completion of the ISO C++ standardization gave the C++ community a
powerful set of reuseable tools in the form of the C++ Standard
Library. However, all existing C++ implementations are (as the Draft
Standard used to say) "incomplet and incorrekt," and many suffer from
powerful set of reuseable tools in the form of the C++ Standard
Library. However, all existing C++ implementations are (as the Draft
Standard used to say) "incomplet and incorrekt," and many suffer from
limitations of the compilers that use them.
The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
widely considered to be one of the leading compilers in the world. Its
development has recently been taken over by the [42]GCC team. All of
the rapid development and near-legendary [43]portability that are the
development has recently been taken over by the [42]GCC team. All of
the rapid development and near-legendary [43]portability that are the
hallmarks of an open-source project are being applied to libstdc++.
That means that all of the Standard classes and functions (such as
string, vector<>, iostreams, and algorithms) will be freely available
and fully compliant. Programmers will no longer need to "roll their
That means that all of the Standard classes and functions (such as
string, vector<>, iostreams, and algorithms) will be freely available
and fully compliant. Programmers will no longer need to "roll their
own" nor be worried about platform-specific incompatabilities.
_________________________________________________________________
1.3 Who's in charge of it?
The libstdc++ project is contributed to by several developers all over
the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
Dos Reis, Phil Edwards, and Ulrich Drepper 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
everyone. You can read instructions for doing so on the [44]homepage.
Development and discussion is held on the libstdc++ mailing list.
Subscribing to the list, or searching the list archives, is open to
everyone. You can read instructions for doing so on the [44]homepage.
If you have questions, ideas, code, or are just curious, sign up!
_________________________________________________________________
1.4 How do I get libstdc++?
The eleventh (and latest) snapshot of libstdc++-v3 is [45]available
The eleventh (and latest) snapshot of libstdc++-v3 is [45]available
via ftp.
The [46]homepage has instructions for retrieving the latest CVS
The [46]homepage has instructions for retrieving the latest CVS
sources, and for browsing the CVS sources over the web.
The subset commonly known as the Standard Template Library (chapters
23 through 25, mostly) is adapted from the SGI STL, which is also an
The subset commonly known as the Standard Template Library (chapters
23 through 25, mostly) is adapted from the SGI STL, which is also an
ongoing work.
_________________________________________________________________
1.5 When is libstdc++ going to be finished?
Nathan Myers gave the best of all possible answers, responding to a
Nathan Myers gave the best of all possible answers, responding to a
Usenet article asking this question: Sooner, if you help.
_________________________________________________________________
1.6 How do I contribute to the effort?
Here is [47]a page devoted to this topic. Subscribing to the mailing
list (see above, or the homepage) is a very good idea if you have
something to contribute, or if you have spare time and want to help.
Here is [47]a page devoted to this topic. Subscribing to the mailing
list (see above, or the homepage) is a very good idea if you have
something to contribute, or if you have spare time and want to help.
Contributions don't have to be in the form of source code; anybody who
is willing to help write documentation, for example, or has found a
is willing to help write documentation, for example, or has found a
bug in code that we all thought was working, is more than welcome!
_________________________________________________________________
1.7 What happened to libg++? I need that!
The most recent libg++ README states that libg++ is no longer being
actively maintained. It should not be used for new projects, and is
The most recent libg++ README states that libg++ is no longer being
actively maintained. It should not be used for new projects, and is
only being kicked along to support older code.
The libg++ was designed and created when there was no Standard to
provide guidance. Classes like linked lists are now provided for by
list<T> and do not need to be created by genclass. (For that matter,
templates exist now and are well-supported, whereas genclass (mostly)
The libg++ was designed and created when there was no Standard to
provide guidance. Classes like linked lists are now provided for by
list<T> and do not need to be created by genclass. (For that matter,
templates exist now and are well-supported, whereas genclass (mostly)
predates them.)
There are other classes in libg++ that are not specified in the ISO
There are other classes in libg++ that are not specified in the ISO
Standard (e.g., statistical analysis). While there are a lot of really
useful things that are used by a lot of people (e.g., statistics :-),
the Standards Committee couldn't include everything, and so a lot of
useful things that are used by a lot of people (e.g., statistics :-),
the Standards Committee couldn't include everything, and so a lot of
those "obvious" classes didn't get included.
Since libstdc++ is an implementation of the Standard Library, we have
no plans at this time to include non-Standard utilities in the
implementation, however handy they are. (The extensions provided in
the SGI STL aren't maintained by us and don't get a lot of our
attention, because they don't require a lot of our time.) It is
entirely plausable that the "useful stuff" from libg++ might be
extracted into an updated utilities library, but nobody has stated
Since libstdc++ is an implementation of the Standard Library, we have
no plans at this time to include non-Standard utilities in the
implementation, however handy they are. (The extensions provided in
the SGI STL aren't maintained by us and don't get a lot of our
attention, because they don't require a lot of our time.) It is
entirely plausable that the "useful stuff" from libg++ might be
extracted into an updated utilities library, but nobody has stated
such a project yet.
(The [48]Boost site houses free C++ libraries that do varying things,
and happened to be started by members of the Standards Committee.
(The [48]Boost site houses free C++ libraries that do varying things,
and happened to be started by members of the Standards Committee.
Certain "useful stuff" classes will probably migrate there.)
For the bold and/or desperate, the [49]GCC FAQ describes where to find
@ -168,12 +168,12 @@
If you have read the README and RELEASE-NOTES files, and your question
remains unanswered, then just ask the mailing list. At present, you do
not need to be subscribed to the list to send a message to it. More
information is available on the homepage (including how to browse the
not need to be subscribed to the list to send a message to it. More
information is available on the homepage (including how to browse the
list archives); to send to the list, use [50]libstdc++@gcc.gnu.org.
If you have a question that you think should be included here, or if
you have a question about a question/answer here, contact [51]Phil
If you have a question that you think should be included here, or if
you have a question about a question/answer here, contact [51]Phil
Edwards or [52]Gabriel Dos Reis.
_________________________________________________________________
@ -181,47 +181,47 @@
2.1 How do I install libstdc++-v3?
Complete instructions are not given here (this is a FAQ, not an
Complete instructions are not given here (this is a FAQ, not an
installation document), but the tools required are few:
* A 3.x release of GCC. Note that building GCC is much easier and
* A 3.x release of GCC. Note that building GCC is much 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
using GCC 2.95, you can still build earlier snapshots of
libstdc++.
* GNU Make is recommended, but should not be required.
* The GNU Autotools are needed if you are messing with the configury
or makefiles.
The file [53]documentation.html provides a good overview of the steps
necessary to build, install, and use the library. Instructions for
configuring the library with new flags such as --enable-threads are
there also, as well as patches and instructions for working with GCC
The file [53]documentation.html provides a good overview of the steps
necessary to build, install, and use the library. Instructions for
configuring the library with new flags such as --enable-threads are
there also, as well as patches and instructions for working with GCC
2.95.
The top-level install.html and [54]RELEASE-NOTES files contain the
exact build and installation instructions. You may wish to browse
those files over CVSweb ahead of time to get a feel for what's
required. RELEASE-NOTES is located in the ".../docs/17_intro/"
The top-level install.html and [54]RELEASE-NOTES files contain the
exact build and installation instructions. You may wish to browse
those files over CVSweb ahead of time to get a feel for what's
required. RELEASE-NOTES is located in the ".../docs/17_intro/"
directory of the distribution.
_________________________________________________________________
2.2 [removed]
This question has become moot and has been removed. The stub is here
This question has become moot and has been removed. The stub is here
to preserve numbering (and hence links/bookmarks).
_________________________________________________________________
2.3 What is this CVS thing that you keep mentioning?
The Concurrent Versions System is one of several revision control
The Concurrent Versions System 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 [55]CVS entry in the GNU
software catalogue has a better description as well as a [56]link to
free (beer), and very high quality. The [55]CVS entry in the GNU
software catalogue has a better description as well as a [56]link to
the makers of CVS.
The "anonymous client checkout" feature of CVS is similar to anonymous
FTP in that it allows anyone to retrieve the latest libstdc++ sources.
After the first of April, American users will have a "/pharmacy"
After the first of April, American users will have a "/pharmacy"
command-line option...
_________________________________________________________________
@ -230,13 +230,13 @@
libstdc++-v3 comes with its own testsuite. You do not need to actually
install the library ("make install") to run the testsuite.
To run the testsuite on the library after building it, use "make
check" while in your build directory. To run the testsuite on the
library after building and installing it, use "make check-install"
To run the testsuite on the library after building it, use "make
check" while in your build directory. To run the testsuite on the
library after building and installing it, use "make check-install"
instead.
If you find bugs in the testsuite programs themselves, or if you think
of a new test program that should be added to the suite, please write
of a new test program that should be added to the suite, please write
up your idea and send it to the list!
_________________________________________________________________
@ -246,44 +246,44 @@
Probably not. Yet.
Because GCC advances so rapidly, development and testing of libstdc++
is being done almost entirely under that compiler. If you are curious
about whether other, lesser compilers (*grin*) support libstdc++, you
are more than welcome to try. Configuring and building the library
(see above) will still require certain tools, however. Also keep in
Because GCC advances so rapidly, development and testing of libstdc++
is being done almost entirely under that compiler. If you are curious
about whether other, lesser compilers (*grin*) support libstdc++, you
are more than welcome to try. Configuring and building the library
(see above) will still require certain tools, however. Also keep in
mind that building libstdc++ does not imply that your compiler will be
able to use all of the features found in the C++ Standard Library.
Since the goal of ISO Standardization is for all C++ implementations
to be able to share code, the final libstdc++ should, in theory, be
useable under any ISO-compliant compiler. It will still be targeted
Since the goal of ISO Standardization is for all C++ implementations
to be able to share code, the final libstdc++ should, in theory, be
useable under any ISO-compliant compiler. It will still be targeted
and optimized for GCC/g++, however.
_________________________________________________________________
3.2 [removed]
This question has become moot and has been removed. The stub is here
This question has become moot and has been removed. The stub is here
to preserve numbering (and hence links/bookmarks).
_________________________________________________________________
3.3 Building DEC OSF kills the assembler
The atomicity.h header for the Alpha processor currently uses
pseudo-operators which the DEC assembler doesn't understand (in
particular, .subsection and .previous). The simple solution is to
install GNU as and arrange for the GCC build to use it (or merge the
The atomicity.h header for the Alpha processor currently uses
pseudo-operators which the DEC assembler doesn't understand (in
particular, .subsection and .previous). The simple solution is to
install GNU as and arrange for the GCC build to use it (or merge the
sources and build it during the bootstrap).
Anyone who [57]knows the DEC assembler well enough to provide the
equivalent of these two pseudos would win praise and accolades from
Anyone who [57]knows the DEC assembler well enough to provide the
equivalent of these two pseudos would win praise and accolades from
many.
_________________________________________________________________
4.0 Known Bugs and Non-Bugs
Note that this section can get rapdily outdated -- such is the nature
of an open-source project. For the latest information, join the
mailing list or look through recent archives. The RELEASE- NOTES and
Note that this section can get rapdily outdated -- such is the nature
of an open-source project. For the latest information, join the
mailing list or look through recent archives. The RELEASE- NOTES and
BUGS files are generally kept up-to-date.
4.1 What works already?
@ -317,8 +317,8 @@ New:
4.2 Bugs in gcc/g++ (not libstdc++-v3)
This is by no means meant to be complete nor exhaustive, but mentions
some problems that users may encounter when building or using
This is by no means meant to be complete nor exhaustive, but mentions
some problems that users may encounter when building or using
libstdc++. If you are experiencing one of these problems, you can find
more information on the libstdc++ and the GCC mailing lists.
* As of 2.91, these bugs have all been fixed. We look forward to new
@ -327,55 +327,55 @@ New:
4.3 Bugs in the C++ language/lib specification
Yes, unfortunately, there are some. In a [58]message to the list,
Nathan Myers announced that he has started a list of problems in the
ISO C++ Standard itself, especially with regard to the chapters that
concern the library. The list itself is [59]posted on his website.
Developers who are having problems interpreting the Standard may wish
Yes, unfortunately, there are some. In a [58]message to the list,
Nathan Myers announced that he has started a list of problems in the
ISO C++ Standard itself, especially with regard to the chapters that
concern the library. The list itself is [59]posted on his website.
Developers who are having problems interpreting the Standard may wish
to consult his notes.
For those people who are not part of the ISO Library Group (i.e.,
nearly all of us needing to read this page in the first place :-), a
For those people who are not part of the ISO Library Group (i.e.,
nearly all of us needing to read this page in the first place :-), a
public list of the library defects is occasionally published [60]here.
_________________________________________________________________
4.4 Things in libstdc++ that look like bugs
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++,
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.
-Weffc++ The biggest of these is the quadzillions of warnings about
the library headers emitted when -Weffc++ is used. Making libstdc++
"-Weffc++-clean" 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. There
-Weffc++ The biggest of these is the quadzillions of warnings about
the library headers emitted when -Weffc++ is used. Making libstdc++
"-Weffc++-clean" 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. There
are multiple solutions under discussion.
rel_ops Another is the rel_ops namespace and the template comparison
operator functions contained therein. If they become visible in the
same namespace as other comparison functions (e.g., 'using' them and
the <iterator> header), then you will suddenly be faced with huge
numbers of ambiguity errors. This was discussed on the -v3 list;
rel_ops Another is the rel_ops namespace and the template comparison
operator functions contained therein. If they become visible in the
same namespace as other comparison functions (e.g., 'using' them and
the <iterator> header), then you will suddenly be faced with huge
numbers of ambiguity errors. This was discussed on the -v3 list;
Nathan Myers [61]sums things up here.
The g++-3 headers are not ours
If you have found an extremely broken header file which is causing
problems for you, look carefully before submitting a "high" priority
bug report (which you probably shouldn't do anyhow; see the last
If you have found an extremely broken header file which is causing
problems for you, look carefully before submitting a "high" priority
bug report (which you probably shouldn't do anyhow; see the last
paragraph of the page describing [62]the GCC bug database).
If the headers are in ${prefix}/include/g++-3, then you are using the
old libstdc++-v2 library, which is nonstandard and unmaintained. Do
If the headers are in ${prefix}/include/g++-3, 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.
Currently our header files are installed in ${prefix}/include/g++-v3
(see the 'v'?). This may change with the next release of GCC, as it
Currently our header files are installed in ${prefix}/include/g++-v3
(see the 'v'?). This may change with the next release of GCC, as it
may be too confusing, but [63]the question has not yet been decided.
glibc 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 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:
2.34. When compiling C++ programs, I get a compilation error in streambuf.h.
@ -385,36 +385,36 @@ type has changed in glibc 2.2. The patch is at
http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
Note that 2.95.x shipped with the [64]old v2 library which is no
longer maintained. Also note that gcc 2.95.3 fixes this problem, but
Note that 2.95.x shipped with the [64]old v2 library which is no
longer maintained. Also note that gcc 2.95.3 fixes this problem, but
requires a separate patch for libstdc++-v3.
concept checks If you see compilation errors containing messages about
fooConcept and a constraints 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
fooConcept and a constraints 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).
More information, including how to optionally enable/disable the
More information, including how to optionally enable/disable the
checks, is available [65]here.
_________________________________________________________________
4.5 Aw, that's easy to fix!
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 on
[66]submitting patches that covers the procedure, but for libstdc++
you should also send the patch to our mailing list in addition to the
GCC patches mailing list. The libstdc++ [67]contributors' page also
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 on
[66]submitting patches that covers the procedure, but for libstdc++
you should also send the patch to our mailing list in addition to the
GCC patches mailing list. The libstdc++ [67]contributors' page also
talks about how to submit patches.
In addition to the description, the patch, and the ChangeLog entry, it
is a Good Thing if you can additionally create a small test program to
test for the presence of the bug that your patch fixes. Bugs have a
way of being reintroduced; if an old bug creeps back in, it will be
caught immediately by the [68]testsuite -- but only if such a test
test for the presence of the bug that your patch fixes. Bugs have a
way of being reintroduced; if an old bug creeps back in, it will be
caught immediately by the [68]testsuite -- but only if such a test
exists.
_________________________________________________________________
@ -422,60 +422,60 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
5.1 string::iterator is not char*; vector<T>::iterator is not T*
If you have code that depends on container<T> iterators being
If you have code that depends on container<T> iterators being
implemented as pointer-to-T, your code is broken.
While there are arguments for iterators to be implemented in that
manner, A) they aren't very good ones in the long term, and B) they
While there are arguments for iterators to be implemented in that
manner, A) they aren't very good ones in the long term, and B) they
were never guaranteed by the Standard anyway. The type-safety achieved
by making iterators a real class rather than a typedef for T*
by making iterators a real class rather than a typedef for T*
outweighs nearly all opposing arguments.
Code which does assume that a vector iterator i is a pointer can often
be fixed by changing i in certain expressions to &*i . Future
revisions of the Standard are expected to bless this usage for
be fixed by changing i in certain expressions to &*i . Future
revisions of the Standard are expected to bless this usage for
vector<> (but not for basic_string<>).
_________________________________________________________________
5.2 What's next after libstdc++-v3?
Hopefully, not much. The goal of libstdc++-v3 is to produce a
fully-compliant, fully-portable Standard Library. After that, we're
Hopefully, not much. The goal of libstdc++-v3 is to produce a
fully-compliant, fully-portable Standard Library. After that, we're
mostly done: there won't be any more compliance work to do. However:
1. The ISO Committee will meet periodically to review Defect Reports
in the C++ Standard. Undoubtedly some of these will result in
changes to the Standard, which will be reflected in patches to
libstdc++. Some of that is already happening, see 4.2. Some of
those changes are being predicted by the library maintainers, and
we add code to the library based on what the current proposed
1. The ISO Committee will meet periodically to review Defect Reports
in the C++ Standard. Undoubtedly some of these will result in
changes to the Standard, which will be reflected in patches to
libstdc++. Some of that is already happening, see 4.2. Some of
those changes are being predicted by the library maintainers, and
we add code to the library based on what the current proposed
resolution specifies.
2. 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
2. 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.
3. An ABI for libstdc++ will eventually be developed, so that
3. An ABI for libstdc++ will eventually be developed, so that
multiple binary-incompatible copies of the library can be replaced
with a single backwards-compatible library, like libgcc_s.so is.
4. The current libstdc++ contains extensions to the Library which
4. 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 libstdc++-v3 if
they seem to be "standard" enough. (For example, the "long long"
type from C99.) Bugfixes and rewrites (to improve or fix thread
they seem to be "standard" enough. (For example, the "long long"
type from C99.) Bugfixes and rewrites (to improve or fix thread
safety, for instance) will of course be a continuing task.
[69]This question about the next libstdc++ prompted some brief but
[69]This question about the next libstdc++ prompted some brief but
interesting [70]speculation.
_________________________________________________________________
5.3 What about the STL from SGI?
The [71]STL from SGI, version 3.3, was the most recent merge of the
STL codebase. The code in libstdc++ contains many fixes and changes,
and it is very likely that the SGI code is no longer under active
The [71]STL from SGI, version 3.3, was the most recent merge of the
STL codebase. The code in libstdc++ contains many fixes and changes,
and it is very likely that the SGI code is no longer under active
development. We expect that no future merges will take place.
In particular, string is not from SGI and makes no use of their "rope"
class (which is included as an optional extension), nor is valarray
class (which is included as an optional extension), nor is valarray
and some others. Classes like vector<> are, however.
The FAQ for SGI's STL (one jump off of their main page) is recommended
@ -484,8 +484,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
5.4 Extensions and Backward Compatibility
Although you can specify -I options to make the preprocessor search
the g++-v3/ext and /backward directories, it is better to refer to
Although you can specify -I options to make the preprocessor search
the g++-v3/ext and /backward directories, it is better to refer to
files there by their path, as in:
#include <ext/hash_map>
@ -495,31 +495,31 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
5.5 [removed]
This question has become moot and has been removed. The stub is here
This question has become moot and has been removed. The stub is here
to preserve numbering (and hence links/bookmarks).
_________________________________________________________________
5.6 Is libstdc++-v3 thread-safe?
Quick answer: no, as of 2.92 (eleventh snapshot), the library is not
Quick answer: no, as of 2.92 (eleventh snapshot), the library is not
appropriate for multithreaded access. The string class is MT-safe.
This is assuming that your idea of "multithreaded" is the same as
ours... The general question of multithreading and libstdc++-v3 is
This is assuming that your idea of "multithreaded" is the same as
ours... The general question of multithreading and libstdc++-v3 is
addressed in the chapter-specific advice for [73]Library Introduction.
Threadsafe containers are covered in more detail in [74]the Received
Threadsafe containers are covered in more detail in [74]the Received
Wisdom section on containers.
_________________________________________________________________
5.7 How do I get a copy of the ISO C++ Standard?
Copies of the full ISO 14882 standard are available on line via the
ISO mirror site for committee members. Non-members, or those who have
not paid for the privilege of sitting on the committee and sustained
their two-meeting commitment for voting rights, may get a copy of the
Copies of the full ISO 14882 standard are available on line via the
ISO mirror site for committee members. Non-members, or those who have
not paid for the privilege of sitting on the committee and sustained
their two-meeting commitment for voting rights, may get a copy of the
standard from their respective national standards organization. In the
USA, this national standards organization is ANSI and their website is
right [75]here. (And if you've already registered with them, clicking
right [75]here. (And if you've already registered with them, clicking
this link will take you to directly to the place where you can [76]buy
the standard on-line.
@ -527,9 +527,9 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
out!
_________________________________________________________________
Comments and suggestions are welcome, and may be sent to [78]the
Comments and suggestions are welcome, and may be sent to [78]the
mailing list.
$Id: index.html,v 1.9 2001/05/30 21:55:04 pme Exp $
$Id: index.html,v 1.10 2001/07/18 21:37:06 pme Exp $
References

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

@ -1,53 +1,53 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<HTML>
<HEAD>
<META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (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">
<!-- $Id: install.html,v 1.5 2001/04/03 00:26:54 pme Exp $ -->
</HEAD>
<BODY>
<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">
<title>libstdc++-v3 Installation Instructions</title>
<link REL=StyleSheet HREF="lib3styles.css">
<!-- $Id: install.html,v 1.6 2001/05/30 21:54:56 pme Exp $ -->
</head>
<body>
<H1 CLASS="centered"><A NAME="top">libstdc++-v3 INSTALL</A></H1>
<h1 CLASS="centered"><a name="top">libstdc++-v3 INSTALL</a></h1>
<P>The latest version of this document is always available at
<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
http://gcc.gnu.org/onlinedocs/libstdc++/install.html</A>.
</P>
<p>The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
</p>
<P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
<!-- ####################################################### -->
<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>
</UL>
<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>
</ul>
<HR>
<hr>
<!-- ####################################################### -->
<H2><A NAME="prereqs">Tools you will need beforehand</A></H2>
<P>You will need a recent version of g++ to compile the snapshot of
<h2><a name="prereqs">Tools you will need beforehand</a></h2>
<p>You will need a recent version of g++ to compile the snapshot of
libstdc++, such as one of the GCC 3.x snapshots (insert standard
caveat about using snapshots rather than formal releases). You
will need the full source
distribution to whatever compiler release you are using. The
GCC snapshots can be had from one of the sites on their
<A HREF="http://gcc.gnu.org/mirrors.html">mirror list</A>.
</P>
<a href="http://gcc.gnu.org/mirrors.html">mirror list</a>.
</p>
<P>In addition, if you plan to modify the makefiles or regenerate the
<p>In addition, if you plan to modify the makefiles or regenerate the
configure scripts you'll need recent versions of the GNU Autotools:
autoconf (version 2.50 or later),
automake (version 1.4 or later), <!-- special version? -->
@ -56,238 +56,238 @@
These tools are all required to be installed in the same location
(most linux distributions install these tools by default, so no
worries as long as the versions are correct).
</P>
</p>
<P>GNU Make is the only 'make' that will parse the makefiles correctly.
</P>
<p>GNU Make is the only 'make' that will parse the makefiles correctly.
</p>
<P>To test your build, you will need either DejaGNU 1.4 (to run
<TT>'make check'</TT> like
<A HREF="http://gcc.gnu.org/install/test.html">the rest of GCC</A>),
or Bash 2.x (to run <TT>'make check-script'</TT>).
</P>
<p>To test your build, you will need either DejaGNU 1.4 (to run
<code>'make check'</code> like
<a href="http://gcc.gnu.org/install/test.html">the rest of GCC</a>),
or Bash 2.x (to run <code>'make check-script'</code>).
</p>
<P>As of June 19, 2000, libstdc++ attempts to use tricky and
<p>As of June 19, 2000, libstdc++ attempts to use tricky and
space-saving features of the GNU toolchain, enabled with
<TT>-ffunction-sections -fdata-sections -Wl,--gc-sections</TT>.
<code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>.
To obtain maximum benefit from this, binutils after this date
should also be used (bugs were fixed with C++ exception handling
related to this change in libstdc++-v3). The version of these
tools should be <TT>2.10.90</TT>, and you can get snapshots (as
tools should be <code>2.10.90</code>, and you can get snapshots (as
well as releases) of binutils
<A HREF="ftp://sources.redhat.com/pub/binutils">here</A>.
</P>
<a href="ftp://sources.redhat.com/pub/binutils">here</a>.
</p>
<!-- Commented until some system-specific requirements appear.
<P>Finally, a few system-specific requirements:
<DL>
<DT>Cygwin
<DD>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
<p>Finally, a few system-specific requirements:
<dl>
<dt>Cygwin
<dd>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll
[snip]
</DL>
</P>
</dl>
</p>
-->
<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
<h2><a name="srcsetup">Setting up the source directories</a></h2>
<p>The following definitions will be used throughout the rest of this
document:
<UL>
<LI><EM>gccsrcdir</EM>: The directory holding the source of the
<ul>
<li><em>gccsrcdir</em>: The directory holding the source of the
compiler. It should have several subdirectories like
<EM>gccsrcdir</EM>/libio and <EM>gccsrcdir</EM>/gcc.
<LI><EM>libsrcdir</EM>: The directory holding the source of the
<em>gccsrcdir</em>/libio and <em>gccsrcdir</em>/gcc.
<li><em>libsrcdir</em>: The directory holding the source of the
C++ library.
<LI><EM>gccbuilddir</EM>: The build directory for the compiler
in <EM>gccsrcdir</EM>. GCC requires that it be built in
<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><EM>libbuilddir</EM>: The build directory for libstdc++.
<LI><EM>destdir</EM>: The eventual installation directory for
<li><em>libbuilddir</em>: The build directory for libstdc++.
<li><em>destdir</em>: The eventual installation directory for
the compiler/libraries, set with the --prefix option to
the configure script.
</UL>
</ul>
Note:
<OL>
<LI>The 3.0 version and following are intended to replace the
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>The source, build, and installation directories should
<ol>
<li>The 3.0 version and following are intended to replace the
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>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.
</OL>
</P>
</ol>
</p>
<P>Check out or download the gcc sources: the resulting source directory
(<TT>gcc</TT> or <TT>gcc-3.0</TT>, for example) is <EM>gccsrcdir</EM>.
Once in <EM>gccsrcdir</EM>, you'll need to rename or delete the
<p>Check out or download the gcc sources: the resulting source directory
(<code>gcc</code> or <code>gcc-3.0</code>, for example) is <em>gccsrcdir</em>.
Once in <em>gccsrcdir</em>, you'll need to rename or delete the
libstdc++-v3 directory which comes with that snapshot:
<PRE>
mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong>
rm -r libstdc++-v3</PRE>
</P>
<P>Next, unpack the libstdc++-v3 library tarball into this
<EM>gccsrcdir</EM> directory; it will create a
<EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
</p>
<p>Next, unpack the libstdc++-v3 library tarball into this
<em>gccsrcdir</em> directory; it will create a
<em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>:
<PRE>
gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
</P>
<P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
</p>
<p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that
gcc's configure flags will be able to deal with the new library.
<PRE>
mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
</P>
mv <em>libsrcdir</em> libstdc++-v3</PRE>
</p>
<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
Instructions</A> first.
</P>
<P>When building libstdc++-v3 you'll have to configure
the entire <EM>gccsrcdir</EM> directory. The full list of libstdc++-v3
<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
Instructions</a> first.
</p>
<p>When building libstdc++-v3 you'll have to configure
the entire <em>gccsrcdir</em> directory. The full list of libstdc++-v3
specific configuration options, not dependent on the specific compiler
release being used, can be found <A HREF="configopts.html">here</A>.
</P>
<P>Consider possibly using --enable-languages=c++ to save time by only
release being used, can be found <a href="configopts.html">here</a>.
</p>
<p>Consider possibly using --enable-languages=c++ to save time by only
building the C++ language parts.
</P>
</p>
<P><PRE>
cd <EM>gccbuilddir</EM>
<EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --other-opts...</PRE>
</P>
<p><PRE>
cd <em>gccbuilddir</em>
<em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</PRE>
</p>
<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>
<P>If you're building GCC from scratch, you can do the usual
<TT> 'make bootstrap' </TT> here, and libstdc++-v3 will be built
<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>
<p>If you're building GCC from scratch, you can do the usual
<code> 'make bootstrap' </code> here, and libstdc++-v3 will be built
as its default C++ library. The generated g++ will magically
use the correct headers, link against the correct library
binary, and in general using libstdc++-v3 will be a piece of
cake. You're done; run <TT>'make install'</TT> (see the GCC
cake. You're done; run <code>'make install'</code> (see the GCC
installation instructions) to put the new compiler and libraries
into place.
</P>
</p>
<H3>[re]building only libstdc++</H3>
<P>To rebuild just libstdc++, use:
<h3>[re]building only libstdc++</h3>
<p>To rebuild just libstdc++, use:
<PRE>
make all-target-<EM>libstdc++-v3</EM></PRE>
make all-target-<em>libstdc++-v3</em></PRE>
This will configure and build the C++ library in the
<EM>gccbuilddir/cpu-vendor-os/</EM>libstdc++ directory.
</P>
<P>If you are rebuilding from a previous build [attempt], some
<em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory.
</p>
<p>If you are rebuilding from a previous build [attempt], some
information is kept in a cache file. This is stored in
<EM>gccbuilddir/cpu-vendor-os/</EM> if you are building with
<em>gccbuilddir/cpu-vendor-os/</em> if you are building with
multilibs (the default), or in
<EM>gccbuilddir/cpu-vendor-os/</EM>libstdc++-v3 if you have
<em>gccbuilddir/cpu-vendor-os/</em>libstdc++-v3 if you have
multilibs disabled. The filename is config.cache; if previous
information is causing problems, you can delete it entirely, or
simply edit it and remove lines.
</P>
<P>You're done. Now install the rebuilt pieces with
</p>
<p>You're done. Now install the rebuilt pieces with
<PRE>
make install</PRE>
or
<PRE>
make install-gcc
make install-target-libstdc++-v3</PRE>
</P>
</p>
<HR>
<H2><A NAME="postinstall">Post-installation</A></H2>
<P>Installation will create the <EM>destdir</EM> directory and
<hr>
<h2><a name="postinstall">Post-installation</a></h2>
<p>Installation will create the <em>destdir</em> directory and
populate it with subdirectories:
<PRE>
lib/
include/g++-v3/
backward/
bits/
<EM>cpu-vendor-os</EM>/bits/
<em>cpu-vendor-os</em>/bits/
ext/</PRE>
</P>
<P>You can check the status of the build without installing it using
</p>
<p>You can check the status of the build without installing it using
<PRE>
make check</PRE>
or you can check the status of the installed library using
<PRE>
make check-install</PRE>
in the <EM>libbuilddir</EM> directory.
in the <em>libbuilddir</em> directory.
These commands will create a 'testsuite' directory underneath
<EM>libbuilddir</EM> containing the results of the tests. We are
<em>libbuilddir</em> containing the results of the tests. We are
interested in any strange failures of the testsuite; please see
<A HREF="faq/index.html#2_4">FAQ 2.4</A> for which files to examine.
</P>
<a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine.
</p>
<HR>
<H2><A NAME="usage">Using the library</A></H2>
<LI><B>Find the new library at runtime (shared linking only)</B>
<P>If you only built a static library (libstdc++.a), or if you
<hr>
<h2><a name="usage">Using the library</a></h2>
<li><B>Find the new library at runtime (shared linking only)</B>
<p>If you only built a static library (libstdc++.a), or if you
specified static linking, you don't have to worry about this.
But if you built a shared library (libstdc++.so) and linked
against it, then you will need to find that library when you
run the executable.
</P>
<P>Methods vary for different platforms and different styles, but
</p>
<p>Methods vary for different platforms and different styles, but
the usual ones are printed to the screen during installation.
They include:
<UL>
<LI>At runtime set LD_LIBRARY_PATH in your environment correctly,
<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>Compile the path to find the library at runtime into the
<li>Compile the path to find the library at runtime into the
program. This can be done by passing certain options to g++,
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):<TT> -Wl,--rpath,<EM>destdir</EM>/lib</TT>
<LI>IRIX ld:<TT> -Wl,-rpath,<EM>destdir</EM>/lib</TT>
<LI>Solaris ld:<TT> -Wl,-R<EM>destdir</EM>/lib</TT>
<LI>More...?
</UL>
</UL>
</P>
<P>Use the <TT>ldd(1)</TT> utility to show which library the system
<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...?
</ul>
</ul>
</p>
<p>Use the <code>ldd(1)</code> utility to show which library the system
thinks it will get at runtime.
</P>
<P>A libstdc++.la file is also installed, for use with Libtool. If
</p>
<p>A libstdc++.la file is also installed, for use with Libtool. If
you use Libtool to create your executables, these details are
taken care of for you.
</P>
</OL>
</P>
</p>
</ol>
</p>
<!--
<HR>
<H2><A NAME=""></A></H2>
<P>
</P>
<hr>
<h2><a name=""></a></h2>
<p>
</p>
-->
<!-- ####################################################### -->
<HR>
<P CLASS="fineprint"><EM>
<hr>
<P CLASS="fineprint"><em>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
<BR> $Id: install.html,v 1.5 2001/04/03 00:26:54 pme Exp $
</EM></P>
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
<br> $Id: install.html,v 1.6 2001/05/30 21:54:56 pme Exp $
</em></p>
</BODY>
</HTML>
</body>
</html>