diff options
| author | pme <pme@138bc75d-0d04-0410-961f-82ee72b054a4> | 2001-09-17 23:24:40 +0000 |
|---|---|---|
| committer | pme <pme@138bc75d-0d04-0410-961f-82ee72b054a4> | 2001-09-17 23:24:40 +0000 |
| commit | c558c60c115adb132ab9b4fb9662d23184c3272b (patch) | |
| tree | 74ce2b24b23a1ae2d24a36c9cd0622a7a5845ca2 /libstdc++-v3 | |
| parent | 77918ba42f29c839be0a9a261842035984d18c3b (diff) | |
| download | gcc-c558c60c115adb132ab9b4fb9662d23184c3272b.tar.gz | |
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.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@45668 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3')
23 files changed, 2674 insertions, 2649 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 76869661c26..7a45a8deb36 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -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. diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index c55f1fba0f8..5d638a1c42f 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -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> - -<H1 CLASS="centered"><A NAME="top">Chapter 17: Library Introduction</A></H1> - -<P>Chapter 17 is actually a list of definitions and descriptions used +<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> + +<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 "Introduction" 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><foo></TT> vs <TT><foo.h></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><foo></code> vs <code><foo.h></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 "files" 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 "thread-safe" 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 <void*, std::malloc_alloc> my_malloc_based_list; </PRE> - </P> - <P>A recent journal article has described "atomic integer + </p> + <p>A recent journal article has described "atomic integer operations," 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 "may not be available on all systems, and if they are, may have different interfaces." [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 "Thread Next" 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> - -<HR> -<H2><A NAME="4"><TT><foo></TT> vs <TT><foo.h></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 + </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"><code><foo></code> vs <code><foo.h></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> diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html index 04f61aec1e6..fd9c08ad31d 100644 --- a/libstdc++-v3/docs/html/18_support/howto.html +++ b/libstdc++-v3/docs/html/18_support/howto.html @@ -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 "0L" 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><limits></CODE></H3> +<hr> +<h2><a name="2">Implementation properties</a></h2> + <p> + <h3><CODE><limits></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><cstdlib></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><cstdlib></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 "interleaved," that is, + <li>The previous two actions are "interleaved," 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 "nothrow" 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 "nothrow" 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 "throwing <TT>new</TT>s" can't + </p> + <p>By default, if one of the "throwing <code>new</code>s" 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> diff --git a/libstdc++-v3/docs/html/19_diagnostics/howto.html b/libstdc++-v3/docs/html/19_diagnostics/howto.html index f7576061335..0cd031a8331 100644 --- a/libstdc++-v3/docs/html/19_diagnostics/howto.html +++ b/libstdc++-v3/docs/html/19_diagnostics/howto.html @@ -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 "Assignable" (which means what you think + <code>vector</code> be "Assignable" (which means what you think it means). The checking was done during compilation, and none of the code was executed at runtime. - </P> - <P>Unfortunately, the size of the compiler files grew significantly + </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> diff --git a/libstdc++-v3/docs/html/20_util/howto.html b/libstdc++-v3/docs/html/20_util/howto.html index 1d425fb3360..ab73cdb776a 100644 --- a/libstdc++-v3/docs/html/20_util/howto.html +++ b/libstdc++-v3/docs/html/20_util/howto.html @@ -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> - -<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<></TT>. -</P> +<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> + +<p>Chapter 20 deals with utility classes and functions, such as + the oft-debated <code>auto_ptr<></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<MyClass> 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> - -<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> + </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"><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> - -<HR> -<H2><A NAME="3">Functors</A></H2> - <P>If you don't know what functors are, you're not alone. Many people + </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 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> - -<HR> -<H2><A NAME="4">Pairs</A></H2> - <P>The <TT>pair<T1,T2></TT> is a simple and handy way to + <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 <code>pair<T1,T2></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& x, const T2& 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 <class U, class V> pain (const pair<U,V>& 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<T1,T2></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<T1,T2></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 < y.first || ( !(y.first < x.first) && x.second < 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<int,MyClass> 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> diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html index 80254269ff9..bf47e406c41 100644 --- a/libstdc++-v3/docs/html/21_strings/howto.html +++ b/libstdc++-v3/docs/html/21_strings/howto.html @@ -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<char></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<char></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, "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 "easy" only if you ignore some things, + </p> + <p>Basically, this is "easy" only if you ignore some things, things which may be too important to your program to ignore. (I chose to ignore them when originally writing this entry, and am surprised that nobody ever called me on it...) The GotW question and answer remain useful instructional tools, however. - </P> - <P><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 "whitespace," 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 "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 "convert to all upper case." The word transformations is especially apt, because the standard template function - <TT>transform<></TT> is used. - </P> - <P>This code will go through some iterations (no pun). Here's the + <code>transform<></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 <string> @@ -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<unsigned char>(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> diff --git a/libstdc++-v3/docs/html/22_locale/codecvt.html b/libstdc++-v3/docs/html/22_locale/codecvt.html index 2ce6c95a1e5..46147d90556 100644 --- a/libstdc++-v3/docs/html/22_locale/codecvt.html +++ b/libstdc++-v3/docs/html/22_locale/codecvt.html @@ -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: "So dudes, what's the deal with Unicode strings?" 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. "UCS-2" and "UTF-8") are necessary, although for other, non-iconv implementations a table of enumerated values or some other mechanism may be required. -<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 "Footnotes for C/C++ developers" in Haible for more information on UCS-2/Unicode endian issues. (Summary: big endian seems most likely, however implementations, most notably Microsoft, vary.) -<LI> +<li> Types representing the conversion state, for conversions involving the machinery in the "C" library, or the conversion descriptor, for conversions using iconv (such as the type iconv_t.) Note that the conversion descriptor encodes more information than a simple encoding state type. -<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 "C" 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<wchar_t, char, mbstate_t> when implemented using standard "C" functions. -<P> +<p> Three problems arise, one big, one of medium importance, and one small. -<P> +<p> First, the small: mcsrtombs and wcsrtombs may not be multithread-safe on all systems required by the GNU tools. For GNU/Linux and glibc, this is not an issue. -<P> +<p> Of medium concern, in the grand scope of things, is that the functions used to implement this specialization work on null-terminated strings. Buffers, especially file buffers, may not be null-terminated, thus giving conversions that end prematurely or are otherwise incorrect. Yikes! -<P> +<p> The last, and fundamental problem, is the assumption of a global locale for all the "C" functions referenced above. For something like C++ iostreams (where codecvt is explicitly used) the notion of @@ -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<wchar_t, char, mbstate_t> , 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<char, char, mbstate_t> -</TT> -<P> +</code> +<p> This is a degenerate (ie, does nothing) specialization. Implementing this was a piece of cake. -<P> -<TT> +<p> +<code> codecvt<char, wchar_t, mbstate_t> -</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&) -</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<internal character type, external character type, __enc_traits> 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> - -<P> -<H2> +<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> 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 "C" and "C++" 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 "6. Character Set Handling" and "7 Locales and Internationalization" -<P> +<p> Drepper, Ulrich, Numerous, late-night email correspondence -<P> +<p> Feather, Clive, "A brief description of Normative Addendum 1," in particular the parts on Extended Character Sets http://www.lysator.liu.se/c/na1.html -<P> +<p> Haible, Bruno, "The Unicode HOWTO" 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, "UTF-8 and Unicode FAQ for Unix/Linux" 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 diff --git a/libstdc++-v3/docs/html/22_locale/ctype.html b/libstdc++-v3/docs/html/22_locale/ctype.html index 08be102fe26..3568145c92e 100644 --- a/libstdc++-v3/docs/html/22_locale/ctype.html +++ b/libstdc++-v3/docs/html/22_locale/ctype.html @@ -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 "C" ctype : global locales, termination. -</H2> +</h2> -<P> +<p> For the required specialization codecvt<wchar_t, char, mbstate_t> , 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<char> -</TT> -<P> +</code> +<p> This is simple specialization. Implementing this was a piece of cake. -<P> -<TT> +<p> +<code> ctype<wchar_t> -</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 "6. Character Set Handling" and "7 Locales and Internationalization" -<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 diff --git a/libstdc++-v3/docs/html/22_locale/howto.html b/libstdc++-v3/docs/html/22_locale/howto.html index 2edcad94fc2..ec9bf0a5da7 100644 --- a/libstdc++-v3/docs/html/22_locale/howto.html +++ b/libstdc++-v3/docs/html/22_locale/howto.html @@ -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> - -<H1 CLASS="centered"><A NAME="top">Chapter 22: Localization</A></H1> - -<P>Chapter 22 deals with the C++ localization facilities. -</P> +<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> + +<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="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="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="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 "The Standard C++ Locale" was +<hr> +<h2><a name="6">Nathan Myers on Locales</a></h2> + <p> An article entitled "The Standard C++ Locale" 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, "How + <p>A very common question on newsgroups and mailing lists is, "How do I do <foo> to a character string?" where <foo> 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, "And how do I make the code portable?" - </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 "Danish" int tolower (int); </TT>. - </P> - <P>The C++ code to do all this proceeds in the same way. First, a locale + <code> extern "Danish" 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& loc) const; }</PRE> This function extracts the appropriate "facet" 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 <iterator> // for back_inserter #include <locale> @@ -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> diff --git a/libstdc++-v3/docs/html/22_locale/locale.html b/libstdc++-v3/docs/html/22_locale/locale.html index 2c7b28828ed..9a13bb33b7d 100644 --- a/libstdc++-v3/docs/html/22_locale/locale.html +++ b/libstdc++-v3/docs/html/22_locale/locale.html @@ -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 "C" 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 "6. Character Set Handling" and "7 Locales and Internationalization" -<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 diff --git a/libstdc++-v3/docs/html/22_locale/messages.html b/libstdc++-v3/docs/html/22_locale/messages.html index 165035842de..906bff86784 100644 --- a/libstdc++-v3/docs/html/22_locale/messages.html +++ b/libstdc++-v3/docs/html/22_locale/messages.html @@ -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 "C" 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> + <code>msgfmt fr_FR.po -o fr_FR.mo</code> <p> - <TT>msgfmt de_DE.po -o de_DE.mo</TT> + <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> + <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code> <p> - <TT>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</TT> + <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> - -<P> -<H2> +<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> 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 "7 Locales and Internationalization" -<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 diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 7ae920bc86d..5a7f39cfd9b 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -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">"Hinting" 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">"Hinting" 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 "container" 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 "*of" + </p> + <p>This author has a collection of such functions, called "*of" because they all extend the builtin "sizeof". 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<T></TT> instead of a - more general <TT>Container<T></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<T></code> instead of a + more general <code>Container<T></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 (&)[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 <bitset> @@ -105,30 +105,30 @@ std::bitset<n> 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<N></TT>. - <LI>A container<bool>. - <LI>Extremely weird solutions. - </UL> - </P> - <P><B>A very large N in <TT>bitset<N></TT>. </B> It has + <ul> + <li>A very large N in <code>bitset<N></code>. + <li>A container<bool>. + <li>Extremely weird solutions. + </ul> + </p> + <p><B>A very large N in <code>bitset<N></code>. </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., - "changed"/"unchanged" flags), that's a <EM>lot</EM> + "changed"/"unchanged" flags), that's a <em>lot</em> of state. - </P> - <P>You can then keep track of the "maximum bit used" during some + </p> + <p>You can then keep track of the "maximum bit used" 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<bool>. </B> The Committee made provision + </p> + <p><B>A container<bool>. </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<char></TT> or <TT>Container<short int></TT>. - Specifically, <TT>vector<bool></TT> is required to be + <code>Container<char></code> or <code>Container<short int></code>. + Specifically, <code>vector<bool></code> is required to be specialized for that space savings. - </P> - <P>The problem is that <TT>vector<bool></TT> doesn't behave like a + </p> + <p>The problem is that <code>vector<bool></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<bool></TT> - specialization. In the meantime, <TT>deque<bool></TT> is + <em>C++ Report</em> cover it well). Future revisions of the ISO C++ + Standard will change the requirement for <code>vector<bool></code> + specialization. In the meantime, <code>deque<bool></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. </B> If you have access to + </p> + <p><B>Extremely weird solutions. </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<N></TT> for the exact <TT>N</TT> + an instantiation of <code>bitset<N></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 ("For most clients,"...), 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">"Hinting" during insertion</A></H2> - <P>Section [23.1.2], Table 69, of the C++ standard lists this function +<hr> +<h2><a name="4">"Hinting" 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) "<". 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 "greater" and "lesser" 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: "greater than" should be replaced by "not less than" and "less than" should be replaced by "not greater than." (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 "Links" from the homepage, and from the C++ information "defect reflector" 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<5> b ( std::string("10110") ); @@ -351,21 +351,21 @@ <PRE> std::bitset<5> b ( "10110" ); // 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> diff --git a/libstdc++-v3/docs/html/24_iterators/howto.html b/libstdc++-v3/docs/html/24_iterators/howto.html index 9c658f9f4cd..9cdabd7be3a 100644 --- a/libstdc++-v3/docs/html/24_iterators/howto.html +++ b/libstdc++-v3/docs/html/24_iterators/howto.html @@ -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> - -<H1 CLASS="centered"><A NAME="top">Chapter 24: Iterators</A></H1> - -<P>Chapter 24 deals with the FORTRAN subroutines for automatically +<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> + +<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 "meta-information" that simply tell the compiler some nicknames; they don't create code. That information gets passed down through inheritance, so while the compiler has to do work looking up all the names, your runtime code does not. (This has been a prime concern from the beginning.) - </P> - <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, + </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, 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, "Everything up through this point," and a graph terminating with an open dot meant, "Everything up to, but not including, this point," respectively called closed and open ranges? Remember how closed ranges were written with - brackets, <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> diff --git a/libstdc++-v3/docs/html/25_algorithms/howto.html b/libstdc++-v3/docs/html/25_algorithms/howto.html index 1e1ea29d62d..277031b99d4 100644 --- a/libstdc++-v3/docs/html/25_algorithms/howto.html +++ b/libstdc++-v3/docs/html/25_algorithms/howto.html @@ -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 "past-the-end" 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> diff --git a/libstdc++-v3/docs/html/26_numerics/howto.html b/libstdc++-v3/docs/html/26_numerics/howto.html index f55b5dd96ae..04562b9cedf 100644 --- a/libstdc++-v3/docs/html/26_numerics/howto.html +++ b/libstdc++-v3/docs/html/26_numerics/howto.html @@ -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> - -<H1 CLASS="centered"><A NAME="top">Chapter 26: Numerics</A></H1> - -<P>Chapter 26 deals with building block abstractions to aid in +<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> + +<p>Chapter 26 deals with building block abstractions to aid in numerical computing: - <UL> - <LI>Template data structures such as <TT>valarray<></TT> - and <TT>complex<></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<></code> + and <code>complex<></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<></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<></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<></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<></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<<</TT> - and <TT>op>></TT> that work with iostreams: <TT>op<<</TT> - prints <TT>(u,v)</TT> and <TT>op>></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> - -<HR> -<H2><A NAME="2">Array Processing</A></H2> - <P>One of the major reasons why FORTRAN can chew through numbers so well + math operators defined, as well as definitions of <code>op<<</code> + and <code>op>></code> that work with iostreams: <code>op<<</code> + prints <code>(u,v)</code> and <code>op>></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 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 "a whole bunch" of functions. The classes are required to be free of pointer aliasing, so compilers can optimize the daylights out of them the same way that they have been for FORTRAN. - They are collectively called <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> - -<HR> -<H2><A NAME="3">Numerical Functions</A></H2> - <P>There are four generalized functions in the <numeric> header + </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 <numeric> header that follow the same conventions as those in <algorithm>. 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<int>()); </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> - -<HR> -<H2><A NAME="4">C99</A></H2> - <P>In addition to the other topics on this page, we'll note here some + </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 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> diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index 3241e6e0fb0..9edab19b849 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -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 <sstream>/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 <sstream>/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 << 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 "output_file" 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<<</TT> is overloaded to take an ostream and + handled by the <code>basic_streambuf</code> family. Fortunately, the + <code>operator<<</code> is overloaded to take an ostream and a pointer-to-streambuf, in order to help with just this kind of "dump the data verbatim" situation. - </P> - <P>Why a <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 << IN.rdbuf();</PRE> - </P> - <P>So what <EM>was</EM> happening with OUT<<IN? Undefined + </p> + <p>So what <em>was</em> happening with OUT<<IN? Undefined behavior, since that particular << 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 "newline-buffer-flushing only occuring on terminals" 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 << ...... << 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 ("/foo/bar/baz"); std::ifstream is ("/qux/quux/quuux"); @@ -160,48 +160,48 @@ ... os << "this data is written immediately\n"; is >> 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 "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 "makes sense" 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><</>></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><</>></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 "binary" - <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><<</TT> to write and <TT>>></TT> to + </p> + <p>Second, using <code><<</code> to write and <code>>></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 "unformatted" I/O functions, but still character-based. (This may or may not be what you want, see below.) - </P> - <P>Notice how all the problems here are due to the inappropriate use - of <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>"Derive your own fstream-type classes and write your own + <ul> + <li>"Derive your own fstream-type classes and write your own <</>> operators to do binary I/O on whatever data types you're using." 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>"Build the file structure in memory, then <TT>mmap()</TT> + <li>"Build the file structure in memory, then <code>mmap()</code> the file and copy the structure." 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>"Use streambufs, that's what they're there for." + <li>"Use streambufs, that's what they're there for." 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 <sstream>/stringstreams thing?</A></H2> - <P>Stringstreams (defined in the header <TT><sstream></TT>) +<hr> +<h2><a name="5">What is this <sstream>/stringstreams thing?</a></h2> + <p>Stringstreams (defined in the header <code><sstream></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><<</TT> and - <TT>>></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><<</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><<</code> and + <code>>></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><<</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>>></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>>></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><<</TT>/<TT>>></TT> functions correctly, though, + </p> + <p>This only works if you've written your + <code><<</code>/<code>>></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 "freezing" functions, and you don't have to manage the memory yourself. The strstreams have been officially deprecated, which means that 1) future revisions of the C++ Standard won't support them, and 2) if you use them, people will laugh at you. - </P> + </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 "binary" I/O was brought up in a couple of places at the same time. One notable place was Usenet, where James Kanze and Dietmar Kühl separately posted articles on why attempting generic binary I/O was not a good idea. (Here are copies of - <A HREF="binary_iostreams_kanze.txt">Kanze's article</A> and - <A HREF="binary_iostreams_kuehl.txt">Kü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ü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 "binary iostreams" on both comp.std.c++ and comp.lang.c++.moderated in parallel. Also in that thread, Dietmar Kühl mentioned that he had written a pair of stream classes that would read and write XDR, which is a good step towards a portable binary format. - </P> + </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 <iostream> @@ -417,54 +417,54 @@ std::cout << "d!\n"; </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> diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index dd0bcd3a430..9a5b71fe8e4 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -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 "powerpc-elf" will have libstdc++ built many different ways: "-msoft-float" and not, etc. A different libstdc++ will be built for each of the different multilib versions. This option is on by default. - </P> + </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 "C" 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 "C" abstraction which consists of "C" locale info. The default is 'generic'. - </P> + </p> - <DT><TT>--enable-c99 </TT> - <DD><P>The "long long" type was introduced in C99, along + <dt><code>--enable-c99 </code> + <dd><p>The "long long" type was introduced in C99, along with many other functions for wide characters, and math classification macros, etc. If enabled, all C99 functions not - specified by the C++ standard will be put into <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 "as if" they were in the C++ standard (as they will eventually be in some future revision of the standard, without a doubt). By default, C99 support is on, assuming the configure probes find all the necessary functions and bits necessary. - </P> + </p> - <DT><TT>--enable-long-long </TT> - <DD><P>The "long long" type was introduced in C99. It is + <dt><code>--enable-long-long </code> + <dd><p>The "long long" type was introduced in C99. It is provided as a GNU extension to C++98 in g++. This flag builds support for "long long" into the library (specialized templates and the like for iostreams). This option is on by default: @@ -121,22 +121,22 @@ options</A></H1> allow "C" visibility of this feature (on GNU/Linux, the flag is -D_ISOC99_SOURCE, which is added automatically via CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). - </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=<include-files dir></TT> - <DD><P>Adds support for named libstdc++ include directory. For instance, + <dt><code>--with-gxx-include-dir=<include-files dir></code> + <dd><p>Adds support for named libstdc++ include directory. For instance, the following puts all the libstdc++ headers into a directory called "2.97-20001008" instead of the usual "g++-v3". <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> diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index bd8c2988b94..6d5da262bc8 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -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><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/></TT>. You will + <code><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/></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> diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html index eb88000ffc9..076454f9b13 100644 --- a/libstdc++-v3/docs/html/explanations.html +++ b/libstdc++-v3/docs/html/explanations.html @@ -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>"I/O packages", <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>"I/O packages", <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 "FILE*") 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> diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index 593e30f1350..b34e61e4633 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -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> - -<H1 CLASS="centered"><A NAME="top">Extensions</A></H1> - -<P>Here we will make an attempt at describing the non-Standard extensions to +<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> + +<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> <bvector> <hash_map> @@ -55,120 +55,120 @@ <rope> <slist> <tree> - </PRE> are all here; <TT><bvector></TT> exposes the old bit_vector + </PRE> are all here; <code><bvector></code> exposes the old bit_vector class that was used before specialization of vector<bool> was available (it's actually a typedef for the specialization now). - <TT><hash_map></TT> and <TT><hash_set></TT> - are discussed further below. <TT><rope></TT> is the SGI + <code><hash_map></code> and <code><hash_set></code> + are discussed further below. <code><rope></code> is the SGI specialization for large strings ("rope," "large strings," get it? love those SGI folks). - <TT><slist></TT> is a singly-linked list, for when the - doubly-linked <TT>list<></TT> is too much space overhead, and - <TT><tree></TT> exposes the red-black tree classes used in the + <code><slist></code> is a singly-linked list, for when the + doubly-linked <code>list<></code> is too much space overhead, and + <code><tree></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 "normal" 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>"Why wasn't a hash + hash_map.</em></BLOCKQUOTE> + </p> + <p>(Side note: for those of you wondering, <B>"Why wasn't a hash table included in the Standard in the first #!$@ place?"</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> - -<HR> -<H2><A NAME="2">Added members</A></H2> - <P>Some of the classes in the Standard Library have additional + </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 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> - -<HR> -<H2><A NAME="3">Allocators</A></H2> - <P>This will be blank for a while. It will describe all of the different + 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 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> - -<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 + </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 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> diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index 128ecb4dde7..e08f65ac99d 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -1,215 +1,215 @@ -<HTML> -<HEAD> - <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> - <META NAME="KEYWORDS" CONTENT="libstdc++, libstdc++-v3, GCC, g++, libg++, STL"> - <META NAME="DESCRIPTION" CONTENT="FAQ for the GNU libstdc++ effort."> - <TITLE>libstdc++-v3 FAQ</TITLE> -<LINK REL=StyleSheet HREF="../lib3styles.css"> +<html> +<head> + <meta HcodeP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <meta NAME="KEYWORDS" CONTENT="libstdc++, libstdc++-v3, GCC, g++, libg++, STL"> + <meta NAME="DESCRIPTION" CONTENT="FAQ for the GNU libstdc++ effort."> + <title>libstdc++-v3 FAQ</title> +<link REL=StyleSheet HREF="../lib3styles.css"> <!-- ** Locations of "the most recent snapshot is the Nth" text are ** answers 1_1, 1_4, 4_1, 5_6. --> -<!-- $Id: index.html,v 1.9 2001/05/30 21:55:04 pme Exp $ --> -</HEAD> -<BODY> +<!-- $Id: index.html,v 1.10 2001/07/18 21:37:06 pme Exp $ --> +</head> +<body> -<H1 CLASS="centered">libstdc++ Frequently Asked Questions</H1> +<h1 CLASS="centered">libstdc++ Frequently Asked Questions</h1> -<P>The latest version of this document is always available at -<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/faq/"> -http://gcc.gnu.org/onlinedocs/libstdc++/faq/</A>.</P> +<p>The latest version of this document is always available at +<a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/"> +http://gcc.gnu.org/onlinedocs/libstdc++/faq/</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> -<H1>Questions</H1> -<OL> - <LI><A HREF="#1_0">General Information</A> +<hr> +<h1>Questions</h1> +<ol> + <li><a href="#1_0">General Information</a> <!-- I suspect these will mostly be links to/into existing documents. --> - <OL> - <LI><A HREF="#1_1">What is libstdc++-v3?</A> - <LI><A HREF="#1_2">Why should I use libstdc++?</A> - <LI><A HREF="#1_3">Who's in charge of it?</A> - <LI><A HREF="#1_4">How do I get libstdc++?</A> - <LI><A HREF="#1_5">When is libstdc++ going to be finished?</A> - <LI><A HREF="#1_6">How do I contribute to the effort?</A> - <LI><A HREF="#1_7">What happened to libg++? I need that!</A> - <LI><A HREF="#1_8">What if I have more questions?</A> - </OL> - - <LI><A HREF="#2_0">Installation</A> - <OL> - <LI><A HREF="#2_1">How do I install libstdc++-v3?</A> - <LI><A HREF="#2_2">[removed]</A> - <LI><A HREF="#2_3">What is this CVS thing that you keep - mentioning?</A> - <LI><A HREF="#2_4">How do I know if it works?</A> - </OL> - - <LI><A HREF="#3_0">Platform-Specific Issues</A> - <OL> - <LI><A HREF="#3_1">Can libstdc++-v3 be used with <my - favorite compiler>?</A> - <LI><A HREF="#3_2">[removed]</A> - <LI><A HREF="#3_3">Building under DEC OSF kills the assembler</A> - </OL> - - <LI><A HREF="#4_0">Known Bugs and Non-Bugs</A> - <OL> - <LI><A HREF="#4_1">What works already?</A> - <LI><A HREF="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</A> - <LI><A HREF="#4_3">Bugs in the C++ language/lib specification</A> - <LI><A HREF="#4_4">Things in libstdc++ that look like bugs</A> - <UL> - <LI><A HREF="#4_4_Weff">-Weffc++ complains too much</A> - <LI><A HREF="#4_4_rel_ops">"ambiguous overloads" - after including an old-style header</A> - <LI><A HREF="#4_4_interface">The g++-3 headers are - <STRONG>not ours</STRONG></A> - <LI><A HREF="#4_4_glibc">compilation errors from streambuf.h</A> - <LI><A HREF="#4_4_checks">errors about <EM>*Cconcept</EM> and - <EM>constraints</EM> in the STL...</A> - </UL> - <LI><A HREF="#4_5">Aw, that's easy to fix!</A> - </OL> - - <LI><A HREF="#5_0">Miscellaneous</A> - <OL> - <LI><A HREF="#5_1">string::iterator is not char*; - vector<T>::iterator is not T*</A> - <LI><A HREF="#5_2">What's next after libstdc++-v3?</A> - <LI><A HREF="#5_3">What about the STL from SGI?</A> - <LI><A HREF="#5_4">Extensions and Backward Compatibility</A> - <LI><A HREF="#5_5">[removed]</A> - <LI><A HREF="#5_6">Is libstdc++-v3 thread-safe?</A> - <LI><A HREF="#5_7">How do I get a copy of the ISO C++ Standard?</A> - </OL> - -</OL> - -<HR> + <ol> + <li><a href="#1_1">What is libstdc++-v3?</a> + <li><a href="#1_2">Why should I use libstdc++?</a> + <li><a href="#1_3">Who's in charge of it?</a> + <li><a href="#1_4">How do I get libstdc++?</a> + <li><a href="#1_5">When is libstdc++ going to be finished?</a> + <li><a href="#1_6">How do I contribute to the effort?</a> + <li><a href="#1_7">What happened to libg++? I need that!</a> + <li><a href="#1_8">What if I have more questions?</a> + </ol> + + <li><a href="#2_0">Installation</a> + <ol> + <li><a href="#2_1">How do I install libstdc++-v3?</a> + <li><a href="#2_2">[removed]</a> + <li><a href="#2_3">What is this CVS thing that you keep + mentioning?</a> + <li><a href="#2_4">How do I know if it works?</a> + </ol> + + <li><a href="#3_0">Platform-Specific Issues</a> + <ol> + <li><a href="#3_1">Can libstdc++-v3 be used with <my + favorite compiler>?</a> + <li><a href="#3_2">[removed]</a> + <li><a href="#3_3">Building under DEC OSF kills the assembler</a> + </ol> + + <li><a href="#4_0">Known Bugs and Non-Bugs</a> + <ol> + <li><a href="#4_1">What works already?</a> + <li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> + <li><a href="#4_3">Bugs in the C++ language/lib specification</a> + <li><a href="#4_4">Things in libstdc++ that look like bugs</a> + <ul> + <li><a href="#4_4_Weff">-Weffc++ complains too much</a> + <li><a href="#4_4_rel_ops">"ambiguous overloads" + after including an old-style header</a> + <li><a href="#4_4_interface">The g++-3 headers are + <strong>not ours</strong></a> + <li><a href="#4_4_glibc">compilation errors from streambuf.h</a> + <li><a href="#4_4_checks">errors about <em>*Cconcept</em> and + <em>constraints</em> in the STL...</a> + </ul> + <li><a href="#4_5">Aw, that's easy to fix!</a> + </ol> + + <li><a href="#5_0">Miscellaneous</a> + <ol> + <li><a href="#5_1">string::iterator is not char*; + vector<T>::iterator is not T*</a> + <li><a href="#5_2">What's next after libstdc++-v3?</a> + <li><a href="#5_3">What about the STL from SGI?</a> + <li><a href="#5_4">Extensions and Backward Compatibility</a> + <li><a href="#5_5">[removed]</a> + <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> + <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> + </ol> + +</ol> + +<hr> <!-- ####################################################### --> -<H1><A NAME="1_0">1.0 General Information</A></H1> +<h1><a name="1_0">1.0 General Information</a></h1> <!-- I suspect these will mostly be links to/into existing documents. --> - <H2><A NAME="1_1">1.1 What is libstdc++-v3?</A></H2> - <P>The GNU Standard C++ Library v3, or libstdc++-2.9x, is an + <h2><a name="1_1">1.1 What is libstdc++-v3?</a></h2> + <p>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 <A HREF="ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.92.tar.gz">the - eleventh snapshot</A>. For those who want to see exactly how + eleventh snapshot</a>. 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). - </P> - <P>A more formal description of the V3 goals can be found in the - official <A HREF="../17_intro/DESIGN">design document</A>. - </P> - -<HR> - <H2><A NAME="1_2">1.2 Why should I use libstdc++?</A></H2> - <P>The completion of the ISO C++ standardization gave the + </p> + <p>A more formal description of the V3 goals can be found in the + official <a href="../17_intro/DESIGN">design document</a>. + </p> + +<hr> + <h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2> + <p>The completion of the ISO C++ standardization gave the C++ community a powerful set of reuseable tools in the form 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. - </P> - <P>The GNU C/C++/FORTRAN/<pick-a-language> compiler - (<TT>gcc</TT>, <TT>g++</TT>, etc) is widely considered to be + </p> + <p>The GNU C/C++/FORTRAN/<pick-a-language> compiler + (<code>gcc</code>, <code>g++</code>, etc) is widely considered to be one of the leading compilers in the world. Its development has recently been taken over by the - <A HREF="http://gcc.gnu.org/">GCC team</A>. All of + <a href="http://gcc.gnu.org/">GCC team</a>. All of the rapid development and near-legendary <A -HREF="http://gcc.gnu.org/gcc-2.95/buildstat.html">portability</A> +HREF="http://gcc.gnu.org/gcc-2.95/buildstat.html">portability</a> that are the hallmarks of an open-source project are being applied to libstdc++. - </P> - <P>That means that all of the Standard classes and functions - (such as <TT>string</TT>, <TT>vector<></TT>, iostreams, + </p> + <p>That means that all of the Standard classes and functions + (such as <code>string</code>, <code>vector<></code>, 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. - </P> + </p> -<HR> - <H2><A NAME="1_3">1.3 Who's in charge of it?</A></H2> - <P>The libstdc++ project is contributed to by several developers +<hr> + <h2><a name="1_3">1.3 Who's in charge of it?</a></h2> + <p>The libstdc++ project is contributed to by several developers all over the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel Dos Reis, Phil Edwards, and Ulrich Drepper are the lead maintainers of the CVS archive. - </P> - <P>Development and discussion is held on the libstdc++ mailing + </p> + <p>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 <A HREF="http://gcc.gnu.org/libstdc++/">homepage</A>. + doing so on the <a href="http://gcc.gnu.org/libstdc++/">homepage</a>. If you have questions, ideas, code, or are just curious, sign up! - </P> + </p> -<HR> - <H2><A NAME="1_4">1.4 How do I get libstdc++?</A></H2> - <P>The eleventh (and latest) snapshot of libstdc++-v3 is <A +<hr> + <h2><a name="1_4">1.4 How do I get libstdc++?</a></h2> + <p>The eleventh (and latest) snapshot of libstdc++-v3 is <A HREF="ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.92.tar.gz"> - available via ftp</A>. - </P> - <P>The <A HREF="http://gcc.gnu.org/libstdc++/">homepage</A> + available via ftp</a>. + </p> + <p>The <a href="http://gcc.gnu.org/libstdc++/">homepage</a> has instructions for retrieving the latest CVS sources, and for browsing the CVS sources over the web. - </P> - <P>The subset commonly known as the Standard Template Library + </p> + <p>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.<!-- Possibly a link to SGI's STL here. --> - </P> + </p> -<HR> - <H2><A NAME="1_5">1.5 When is libstdc++ going to be finished?</A></H2> -<!-- <P>Nathan Myers gave the best of all possible answers in <A +<hr> + <h2><a name="1_5">1.5 When is libstdc++ going to be finished?</a></h2> +<!-- <p>Nathan Myers gave the best of all possible answers in <A HREF="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text">a - Usenet article</A>.</P> + Usenet article</a>.</p> which is no longer available, thanks deja...--> - <P>Nathan Myers gave the best of all possible answers, responding to a - Usenet article asking this question: <EM>Sooner, if you help.</EM> - </P> + <p>Nathan Myers gave the best of all possible answers, responding to a + Usenet article asking this question: <em>Sooner, if you help.</em> + </p> -<HR> - <H2><A NAME="1_6">1.6 How do I contribute to the effort?</A></H2> - <P>Here is <A HREF="../17_intro/contribute.html">a - page devoted to this topic</A>. Subscribing to the mailing +<hr> + <h2><a name="1_6">1.6 How do I contribute to the effort?</a></h2> + <p>Here is <a href="../17_intro/contribute.html">a + page devoted to this topic</a>. Subscribing to the mailing 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 bug in code that we all thought was working, is more than welcome! - </P> + </p> -<HR> - <H2><A NAME="1_7">1.7 What happened to libg++? I need that!</A></H2> - <P>The most recent libg++ README states that libg++ is no longer +<hr> + <h2><a name="1_7">1.7 What happened to libg++? I need that!</a></h2> + <p>The most recent libg++ README states that libg++ is no longer being actively maintained. It should not be used for new projects, and is only being kicked along to support older code. - </P> - <P>The libg++ was designed and created when there was no Standard + </p> + <p>The libg++ was designed and created when there was no Standard to provide guidance. Classes like linked lists are now provided - for by <TT>list<T></TT> and do not need to be created by - <TT>genclass</TT>. (For that matter, templates exist now and + for by <code>list<T></code> and do not need to be created by + <code>genclass</code>. (For that matter, templates exist now and are well-supported, whereas genclass (mostly) predates them.) - </P> - <P>There are other classes in libg++ that are not specified in the + </p> + <p>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 those "obvious" classes didn't get included. - </P> - <P>Since libstdc++ is an implementation of the Standard Library, we + </p> + <p>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 @@ -217,161 +217,161 @@ which is no longer available, thanks deja...--> 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. - </P> + </p> <!-- The advertisement, so to speak, might have to go. Hmmmmm. --> - <P>(The <A HREF="http://www.boost.org/">Boost</A> site houses free + <p>(The <a href="http://www.boost.org/">Boost</a> 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.) - </P> - <P>For the bold and/or desperate, the - <A HREF="http://gcc.gnu.org/fom_serv/cache/33.html">GCC FAQ</A> + </p> + <p>For the bold and/or desperate, the + <a href="http://gcc.gnu.org/fom_serv/cache/33.html">GCC FAQ</a> describes where to find the last libg++ source. - </P> + </p> -<HR> - <H2><A NAME="1_8">1.8 What if I have more questions?</A></H2> - <P>If you have read the README and RELEASE-NOTES files, and your +<hr> + <h2><a name="1_8">1.8 What if I have more questions?</a></h2> + <p>If you have read the README and RELEASE-NOTES files, and your question remains unanswered, then just ask the mailing list. 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 list archives); to send - to the list, use <A HREF="mailto:libstdc++@gcc.gnu.org"> - <CODE>libstdc++@gcc.gnu.org</CODE></A>. - </P> - <P>If you have a question that you think should be included here, - or if you have a question <EM>about</EM> a question/answer here, - contact <A HREF="mailto:pme@gcc.gnu.org">Phil Edwards</A> - or <A HREF="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</A>. - </P> - -<HR> - -<H1><A NAME="2_0">2.0 Installation</A></H1> - <H2><A NAME="2_1">2.1 How do I install libstdc++-v3?</A></H2> - <P>Complete instructions are not given here (this is a FAQ, not + to the list, use <a href="mailto:libstdc++@gcc.gnu.org"> + <CODE>libstdc++@gcc.gnu.org</CODE></a>. + </p> + <p>If you have a question that you think should be included here, + or if you have a question <em>about</em> a question/answer here, + contact <a href="mailto:pme@gcc.gnu.org">Phil Edwards</a> + or <a href="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</a>. + </p> + +<hr> + +<h1><a name="2_0">2.0 Installation</a></h1> + <h2><a name="2_1">2.1 How do I install libstdc++-v3?</a></h2> + <p>Complete instructions are not given here (this is a FAQ, not an installation document), but the tools required are few: - </P> - <UL> - <LI> A 3.x release of GCC. Note that building GCC is much + </p> + <ul> + <li> 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 libstdc++. - <LI> GNU Make is recommended, but should not be required. - <LI> The GNU Autotools are needed if you are messing with + <li> GNU Make is recommended, but should not be required. + <li> The GNU Autotools are needed if you are messing with the configury or makefiles. - </UL> - <P>The file <A HREF="../documentation.html">documentation.html</A> + </ul> + <p>The file <a href="../documentation.html">documentation.html</a> 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. - </P> - <P>The top-level install.html and - <A HREF="../17_intro/RELEASE-NOTES">RELEASE-NOTES</A> files contain + </p> + <p>The top-level install.html and + <a href="../17_intro/RELEASE-NOTES">RELEASE-NOTES</a> 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. - </P> + </p> -<HR> - <H2><A NAME="2_2">2.2 [removed]</A></H2> - <P>This question has become moot and has been removed. The stub +<hr> + <h2><a name="2_2">2.2 [removed]</a></h2> + <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - </P> + </p> -<HR> - <H2><A NAME="2_3">2.3 What is this CVS thing that you - keep mentioning?</A></H2> - <P>The <EM>Concurrent Versions System</EM> is one of several revision +<hr> + <h2><a name="2_3">2.3 What is this CVS thing that you + keep mentioning?</a></h2> + <p>The <em>Concurrent Versions System</em> is one of several revision control packages. It was selected for GNU projects because it's free (speech), free (beer), and very high quality. The <A HREF="http://www.gnu.org/software/cvs/cvs.html">CVS entry in - the GNU software catalogue</A> has a better description as + the GNU software catalogue</a> has a better description as well as a - <A HREF="http://www.cvshome.org/">link to the makers of CVS</A>. - </P> - <P>The "anonymous client checkout" feature of CVS is + <a href="http://www.cvshome.org/">link to the makers of CVS</a>. + </p> + <p>The "anonymous client checkout" feature of CVS is similar to anonymous FTP in that it allows anyone to retrieve the latest libstdc++ sources. - </P> - <P>After the first of April, American users will have a + </p> + <p>After the first of April, American users will have a "/pharmacy" command-line option... <!-- wonder how long that'll live --> - </P> - -<HR> - <H2><A NAME="2_4">2.4 How do I know if it works?</A></H2> - <P>libstdc++-v3 comes with its own testsuite. You do not need - to actually install the library ("<TT>make - install</TT>") to run the testsuite. - </P> - <P>To run the testsuite on the library after building it, use + </p> + +<hr> + <h2><a name="2_4">2.4 How do I know if it works?</a></h2> + <p>libstdc++-v3 comes with its own testsuite. You do not need + to actually install the library ("<code>make + install</code>") to run the testsuite. + </p> + <p>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. - </P> - <P>If you find bugs in the testsuite programs themselves, or if + </p> + <p>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, <B>please</B> write up your idea and send it to the list! - </P> - -<HR> -<H1><A NAME="3_0">3.0 Platform-Specific Issues</A></H1> - <H2><A NAME="3_1">3.1 Can libstdc++-v3 be used with <my - favorite compiler>?</A></H2> - <P>Probably not. Yet.</P> - <P>Because GCC advances so rapidly, development and testing of + </p> + +<hr> +<h1><a name="3_0">3.0 Platform-Specific Issues</a></h1> + <h2><a name="3_1">3.1 Can libstdc++-v3 be used with <my + favorite compiler>?</a></h2> + <p>Probably not. Yet.</p> + <p>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 - <EM>building</EM> libstdc++ does not imply that your compiler - will be able to <EM>use</EM> all of the features found in the + <em>building</em> libstdc++ does not imply that your compiler + will be able to <em>use</em> all of the features found in the C++ Standard Library. - </P> - <P>Since the goal of ISO Standardization is for all C++ + </p> + <p>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. - </P> + </p> -<HR> - <H2><A NAME="3_2">3.2 [removed]</A></H2> - <P>This question has become moot and has been removed. The stub +<hr> + <h2><a name="3_2">3.2 [removed]</a></h2> + <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - </P> + </p> -<HR> - <H2><A NAME="3_3">3.3 Building DEC OSF kills the assembler</A></H2> - <P>The <TT>atomicity.h</TT> header for the Alpha processor +<hr> + <h2><a name="3_3">3.3 Building DEC OSF kills the assembler</a></h2> + <p>The <code>atomicity.h</code> 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 <TT>as</TT> and arrange + The simple solution is to install GNU <code>as</code> and arrange for the GCC build to use it (or merge the sources and build it during the bootstrap). - </P> - <P>Anyone who - <A HREF="http://gcc.gnu.org/ml/libstdc++/2000-12/msg00279.html">knows - the DEC assembler well enough</A> to provide the equivalent of + </p> + <p>Anyone who + <a href="http://gcc.gnu.org/ml/libstdc++/2000-12/msg00279.html">knows + the DEC assembler well enough</a> to provide the equivalent of these two pseudos would win praise and accolades from many. - </P> + </p> -<HR> -<H1><A NAME="4_0">4.0 Known Bugs and Non-Bugs</A></H1> - <EM>Note that this section can get rapdily outdated -- such is the +<hr> +<h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1> + <em>Note that this section can get rapdily outdated -- such is the nature of an open-source project. For the latest information, join the mailing list or look through recent archives. The RELEASE- - NOTES and BUGS files are generally kept up-to-date.</EM> + NOTES and BUGS files are generally kept up-to-date.</em> - <H2><A NAME="4_1">4.1 What works already?</A></H2> - <P>This is a verbatim clip from the "Status" section + <h2><a name="4_1">4.1 What works already?</a></h2> + <p>This is a verbatim clip from the "Status" section of the RELEASE-NOTES for the latest snapshot. - </P> + </p> <!-- Yeah, I meant that "verbatim clip" thing literally... :-) --> @@ -402,88 +402,88 @@ New: </pre> -<HR> - <H2><A NAME="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</A></H2> - <P>This is by no means meant to be complete nor exhaustive, but +<hr> + <h2><a name="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</a></h2> + <p>This is by no means meant to be complete nor exhaustive, but mentions some problems that users may encounter when building or using libstdc++. If you are experiencing one of these problems, you can find more information on the libstdc++ and the GCC mailing lists. - </P> - <UL> - <LI>As of 2.91, these bugs have all been fixed. We look forward + </p> + <ul> + <li>As of 2.91, these bugs have all been fixed. We look forward to new ones, well, not exactly... - </UL> + </ul> -<HR> - <H2><A NAME="4_3">4.3 Bugs in the C++ language/lib specification</A></H2> - <P>Yes, unfortunately, there are some. In a <A +<hr> + <h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2> + <p>Yes, unfortunately, there are some. In a <A HREF="http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html">message -to the list</A>, Nathan Myers announced that he has started a list of +to the list</a>, 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 <A HREF="http://www.cantrip.org/draft-bugs.txt">posted on his - website</A>. Developers who are having problems interpreting + website</a>. Developers who are having problems interpreting the Standard may wish to consult his notes. - </P> - <P>For those people who are not part of the ISO Library Group + </p> + <p>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 <A HREF="http://anubis.dkuug.dk/jtc1/sc22/wg21/">here</A>. - </P> + published <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/">here</a>. + </p> -<HR> - <H2><A NAME="4_4">4.4 Things in libstdc++ that look like bugs</A></H2> - <P>There are things which are not bugs in the compiler (4.2) nor +<hr> + <h2><a name="4_4">4.4 Things in libstdc++ that look like bugs</a></h2> + <p>There are things which are not bugs in the compiler (4.2) nor the language specification (4.3), but aren't really bugs in libstdc++, either. Really! Please do not report these as bugs. - </P> - <A NAME="4_4_Weff"> - <P><STRONG>-Weffc++</STRONG> + </p> + <a name="4_4_Weff"> + <p><strong>-Weffc++</strong> The biggest of these is the quadzillions of warnings about the - library headers emitted when <TT>-Weffc++</TT> is used. Making + library headers emitted when <code>-Weffc++</code> 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. - </P> - </A> - <A NAME="4_4_rel_ops"> - <P><STRONG>rel_ops</STRONG> - Another is the <TT>rel_ops</TT> namespace and the template + </p> + </a> + <a name="4_4_rel_ops"> + <p><strong>rel_ops</strong> + Another is the <code>rel_ops</code> namespace and the template comparison operator functions contained therein. If they become visible in the same namespace as other comparison functions - (e.g., '<TT>using</TT>' them and the <iterator> header), + (e.g., '<code>using</code>' 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 - <A HREF="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums - things up here</A>. - </P> - </A> - <A NAME="4_4_interface"><H3>The g++-3 headers are - <EM>not ours</EM></H3> - <P>If you have found an extremely broken header file which is + <a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums + things up here</a>. + </p> + </a> + <a name="4_4_interface"><h3>The g++-3 headers are + <em>not ours</em></h3> + <p>If you have found an extremely broken header file which is causing problems for you, look carefully before submitting a "high" priority bug report (which you probably shouldn't do anyhow; see the last paragraph of the page describing - <A HREF="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</A>). - </P> - <P>If the headers are in <CODE>${prefix}/include/g++-3</CODE>, then + <a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>). + </p> + <p>If the headers are in <CODE>${prefix}/include/g++-3</CODE>, then you are using the old libstdc++-v2 library, which is nonstandard and unmaintained. Do not report problems with -v2 to the -v3 mailing list. - </P> - <P>Currently our header files are installed in + </p> + <p>Currently our header files are installed in <CODE>${prefix}/include/g++-v3</CODE> (see the 'v'?). This may change with the next release of GCC, as it may be too confusing, - but <A HREF="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the - question has not yet been decided</A>. - </P> - </A> - <A NAME="4_4_glibc"> - <P><STRONG>glibc</STRONG> + but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the + question has not yet been decided</a>. + </p> + </a> + <a name="4_4_glibc"> + <p><strong>glibc</strong> If you're on a GNU/Linux system and have just upgraded to glibc 2.2, but are still using gcc 2.95.2, then you should have read the glibc FAQ, specifically 2.34: @@ -496,192 +496,192 @@ type has changed in glibc 2.2. The patch is at http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff </PRE> Note that 2.95.x shipped with the - <A HREF="#4_4_interface">old v2 library</A> which is no longer + <a href="#4_4_interface">old v2 library</a> which is no longer maintained. Also note that gcc 2.95.3 fixes this problem, but requires a separate patch for libstdc++-v3. - </P> - </A> - <A NAME="4_4_checks"> - <P><STRONG>concept checks</STRONG> + </p> + </a> + <a name="4_4_checks"> + <p><strong>concept checks</strong> If you see compilation errors containing messages about - <TT> <EM>foo</EM>Concept </TT>and a<TT> constraints </TT> + <code> <em>foo</em>Concept </code>and a<code> constraints </code> member function, then most likely you have violated one of the requirements for types used during instantiation of template containers and functions. For example, EqualityComparableConcept appears if your types must be comparable with == and you have not provided this capability (a typo, or wrong visibility, or you just plain forgot, etc). - </P> - <P>More information, including how to optionally enable/disable the + </p> + <p>More information, including how to optionally enable/disable the checks, is available - <A HREF="../19_diagnostics/howto.html#3">here</A>. - </P> - </A> + <a href="../19_diagnostics/howto.html#3">here</a>. + </p> + </a> -<HR> - <H2><A NAME="4_5">4.5 Aw, that's easy to fix!</A></H2> - <P>If you have found a bug in the library and you think you have +<hr> + <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2> + <p>If you have found a bug in the library and you think you have a working fix, then send it in! The main GCC site has a page - on <A HREF="http://gcc.gnu.org/contribute.html">submitting - patches</A> that covers the procedure, but for libstdc++ you + on <a href="http://gcc.gnu.org/contribute.html">submitting + patches</a> 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++ - <A HREF="../17_intro/contribute.html">contributors' page</A> + <a href="../17_intro/contribute.html">contributors' page</a> also talks about how to submit patches. - </P> - <P>In addition to the description, the patch, and the ChangeLog + </p> + <p>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 - <A HREF="#2_4">testsuite</A> -- but only if such a test exists. - </P> - -<HR> -<H1><A NAME="5_0">5.0 Miscellaneous</A></H1> - <H2><A NAME="5_1">5.1 string::iterator is not char*; - vector<T>::iterator is not T*</A></H2> - <P>If you have code that depends on container<T> iterators + <a href="#2_4">testsuite</a> -- but only if such a test exists. + </p> + +<hr> +<h1><a name="5_0">5.0 Miscellaneous</a></h1> + <h2><a name="5_1">5.1 string::iterator is not char*; + vector<T>::iterator is not T*</a></h2> + <p>If you have code that depends on container<T> iterators being implemented as pointer-to-T, your code is broken. - </P> - <P>While there are arguments for iterators to be implemented in + </p> + <p>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 <TT>T*</TT> outweighs nearly all opposing + than a typedef for <code>T*</code> outweighs nearly all opposing arguments. - </P> - <P>Code which does assume that a vector iterator <code> i </code> + </p> + <p>Code which does assume that a vector iterator <code> i </code> is a pointer can often be fixed by changing <code> i </code> in certain expressions to <code> &*i </code>. Future revisions of the Standard are expected to bless this usage for vector<> (but not for basic_string<>). - </P> + </p> -<HR> - <H2><A NAME="5_2">5.2 What's next after libstdc++-v3?</A></H2> - <P>Hopefully, not much. The goal of libstdc++-v3 is to produce +<hr> + <h2><a name="5_2">5.2 What's next after libstdc++-v3?</a></h2> + <p>Hopefully, not much. The goal of libstdc++-v3 is to produce a fully-compliant, fully-portable Standard Library. After that, - we're mostly done: there won't <EM>be</EM> any more compliance + we're mostly done: there won't <em>be</em> any more compliance work to do. However: - </P> - <OL> - <LI><P>The ISO Committee will meet periodically to review Defect Reports + </p> + <ol> + <li><p>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. - </P> - <LI><P>Performance tuning. Lots of performance tuning. This too is + </p> + <li><p>Performance tuning. Lots of performance tuning. This too is already underway for post-3.0 releases, starting with memory expansion in container classes and buffer usage in synchronized stream objects. - </P> - <LI><P>An ABI for libstdc++ will eventually be developed, so that + </p> + <li><p>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. - </P> - <LI><P>The current libstdc++ contains extensions to the Library which + </p> + <li><p>The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the hash tables from SGI). Other extensions may be added to 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 safety, for instance) will of course be a continuing task. - </P> - </OL> - <P><A + </p> + </ol> + <p><A HREF="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This - question</A> about the next libstdc++ prompted some brief but + question</a> about the next libstdc++ prompted some brief but interesting <A -HREF="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</A>. - </P> +HREF="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>. + </p> -<HR> - <H2><A NAME="5_3">5.3 What about the STL from SGI?</A></H2> - <P>The <A HREF="http://www.sgi.com/Technology/STL/">STL from SGI</A>, +<hr> + <h2><a name="5_3">5.3 What about the STL from SGI?</a></h2> + <p>The <a href="http://www.sgi.com/Technology/STL/">STL from SGI</a>, version 3.3, was the most recent merge of the STL codebase. The 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. - </P> - <P>In particular, <TT>string</TT> is not from SGI and makes no + </p> + <p>In particular, <code>string</code> is not from SGI and makes no use of their "rope" class (which is included as an - optional extension), nor is <TT>valarray</TT> and some others. - Classes like <TT>vector<></TT> are, however. - </P> - <P>The FAQ for SGI's STL (one jump off of their main page) is + optional extension), nor is <code>valarray</code> and some others. + Classes like <code>vector<></code> are, however. + </p> + <p>The FAQ for SGI's STL (one jump off of their main page) is recommended reading. - </P> + </p> -<HR> - <H2><A NAME="5_4">5.4 Extensions and Backward Compatibility</A></H2> - <P>Although you can specify <TT>-I</TT> options to make the +<hr> + <h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2> + <p>Although you can specify <code>-I</code> 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: <!-- Careful, the leading spaces in PRE show up directly. --> - </P> + </p> <PRE> #include <ext/hash_map> </PRE> - <P>Extensions to the library have - <A HREF="../ext/howto.html">their own page</A>. - </P> + <p>Extensions to the library have + <a href="../ext/howto.html">their own page</a>. + </p> -<HR> - <H2><A NAME="5_5">5.5 [removed]</A></H2> - <P>This question has become moot and has been removed. The stub +<hr> + <h2><a name="5_5">5.5 [removed]</a></h2> + <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - </P> + </p> -<HR> - <H2><A NAME="5_6">5.6 Is libstdc++-v3 thread-safe?</A></H2> - <P>Quick answer: no, as of 2.92 (eleventh snapshot), the +<hr> + <h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2> + <p>Quick answer: no, as of 2.92 (eleventh snapshot), the library is not appropriate for multithreaded access. The string class is MT-safe. - </P> - <P>This is assuming that your idea of "multithreaded" + </p> + <p>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 -<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#3">Library - Introduction</A>. Threadsafe containers are covered in +<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#3">Library + Introduction</a>. Threadsafe containers are covered in more detail in -<A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/23_containers/howto.html">the - Received Wisdom section on containers</A>. +<a href="http://gcc.gnu.org/onlinedocs/libstdc++/23_containers/howto.html">the + Received Wisdom section on containers</a>. <!-- I have successfully evaded the topic; my work here is done- no, wait, I have to write those other sections... --> - </P> + </p> -<HR> - <H2><A NAME="5_7">5.7 How do I get a copy of the ISO C++ Standard?</A></H2> - <P>Copies of the full ISO 14882 standard are available on line via the +<hr> + <h2><a name="5_7">5.7 How do I get a copy of the ISO C++ Standard?</a></h2> + <p>Copies of the full ISO 14882 standard are available on line via the ISO mirror site for committee members. Non-members, or those who 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 <A HREF="http://www.ansi.org">here</A>. + ANSI and their website is right <a href="http://www.ansi.org">here</a>. (And if you've already registered with them, clicking this link will take you to directly to the place where you can -<A HREF="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy - the standard on-line</A>. - </P> - <P>Who is your country's member body? Visit the - <A HREF="http://www.iso.ch/">ISO homepage</A> and find out! - </P> +<a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy + the standard on-line</a>. + </p> + <p>Who is your country's member body? Visit the + <a href="http://www.iso.ch/">ISO homepage</a> and find out! + </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: index.html,v 1.9 2001/05/30 21:55:04 pme Exp $ -</EM></P> +<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>. +<br> $Id: index.html,v 1.10 2001/07/18 21:37:06 pme Exp $ +</em></p> -</BODY> -</HTML> +</body> +</html> diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt index 88c1b4be339..accb087bec9 100644 --- a/libstdc++-v3/docs/html/faq/index.txt +++ b/libstdc++-v3/docs/html/faq/index.txt @@ -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 diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html index 392186e472b..c3627b462fd 100644 --- a/libstdc++-v3/docs/html/install.html +++ b/libstdc++-v3/docs/html/install.html @@ -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> +<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><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> - - -<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 + 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 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> |