+2000-07-07 Phil Edwards <pme@sourceware.cygnus.com>
+
+ * docs/download.html: Mention gcc_update.
+ * docs/configopts.html: Minor updates.
+ * docs/gccrebuild.html: Ditto.
+ * docs/18_support/howto.html: More tips, explanations, and reminders.
+ * docs/19_diagnostics/howto.html: Ditto.
+ * docs/21_strings/howto.html: Ditto.
+ * docs/24_iterators/howto.html: Ditto.
+ * docs/25_algorithms/howto.html: Ditto.
+ * docs/26_numerics/howto.html: Ditto.
+
2000-07-05 brent verner <brent@rcfile.org>
* testsuite/27_io/ifstream_members.cc (test01): Add tests.
<TITLE>libstdc++-v3 HOWTO: Chapter 18</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/18_support/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.5 1999/12/15 16:57:06 pme Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $ -->
</HEAD>
<BODY>
macro is <EM>not</EM> allowed to be <TT>(void*)0</TT>, which is
often used in C.
</P>
- <P>
+ <P>In g++, NULL is #define'd to be <TT>__null</TT>, a magic keyword
+ extension of g++.
+ </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>,
+ Scott Meyers points out that the best way to solve this problem is to
+ not overload on pointer-vs-integer types to begin with. He also
+ offers a way to make your own magic NULL that will match pointers
+ before it matches integers:
+ <PRE>
+ const // this is a const object...
+ class {
+ public:
+ template<class T> // convertible to any type
+ operator T*() const // of null non-member
+ { return 0; } // pointer...
+
+ template<class C, class T> // or any type of null
+ operator T C::*() const // member pointer...
+ { return 0; }
+
+ private:
+ void operator&() const; // whose address can't be
+ // taken (see Item 27)...
+
+ } 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
+ 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
+ where you started.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.5 1999/12/15 16:57:06 pme Exp $
+<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $
</EM></P>
<TITLE>libstdc++-v3 HOWTO: Chapter 19</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/19_diagnostics/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $ -->
</HEAD>
<BODY>
<H1 CLASS="centered"><A NAME="top">Chapter 19: Diagnostics</A></H1>
<P>Chapter 19 deals with program diagnostics, such as exceptions
- and assertions.
+ and assertions. You know, all the things we wish weren't even
+ necessary at all.
</P>
<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</A>
</UL>
<HR>
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
+<HR>
+<H2><A NAME="3">Concept checkers</A></H2>
+ <P>As part of their 3.3 release, SGI added some nifty macros which
+ perform assertions on type properties. For example, the Standard
+ requires that types passed as template parameters to <TT>vector</TT>
+ be "Assignable" (which means what you think it means).
+ </P>
+ <P>The concept checkers allow the source code for <TT>vector</TT> to
+ declare
+ <PRE>
+ __STL_CLASS_REQUIRES(_Tp, _Assignable);
+ </PRE>inside the template. <TT>_Tp</TT> is the element type of the
+ vector, and <TT>_Assignable</TT> is the concept to be checked (it is
+ defined in some back-end header files). When you instantiate
+ <TT>vector<MyType></TT>, compile-time checking can be done on
+ whether MyType meets the requirements for vectors.
+ </P>
+<P>This is an extension to the library. This documentation needs updating.</P>
+ <P>Return <A HREF="#top">to top of page</A> or
+ <A HREF="../faq/index.html">to the FAQ</A>.
+ </P>
+
+
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $
+<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $
</EM></P>
<TITLE>libstdc++-v3 HOWTO: Chapter 21</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/21_strings/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.8 2000/03/20 22:16:21 pme Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $ -->
</HEAD>
<BODY>
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
+ production code. (The GotW answer mentions one of the principle
+ difficulties; this article mentions more.)
+ </P>
+ <P>Basically, this is "easy" only if you ignore some things,
+ things which may be too important to your program to ignore. (I chose
+ to ignore them when originally writing this entry, and am surprised
+ that nobody ever called me on it...) The GotW question and answer
+ remain useful instructional tools, however.
+ </P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.8 2000/03/20 22:16:21 pme Exp $
+<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $
</EM></P>
<TITLE>libstdc++-v3 HOWTO: Chapter 24</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/24_iterators/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $ -->
</HEAD>
<BODY>
<H1>Contents</H1>
<UL>
<LI><A HREF="#1">They ain't pointers!</A>
- <LI><A HREF="#2">Topic</A>
+ <LI><A HREF="#2">It ends <EM>where?</EM></A>
</UL>
<HR>
</P>
<HR>
-<H2><A NAME="2">Topic</A></H2>
+<H2><A NAME="2">It ends <EM>where?</EM></A></H2>
<P>Blah.
</P>
<P>Return <A HREF="#top">to top of page</A> or
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $
+<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $
</EM></P>
<TITLE>libstdc++-v3 HOWTO: Chapter 25</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/25_algorithms/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $ -->
+<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $ -->
</HEAD>
<BODY>
<H1 CLASS="centered"><A NAME="top">Chapter 25: Algorithms</A></H1>
-<P>Chapter 25 deals with the FORTRAN subroutines for automatically
+<P>Chapter 25 deals with the generalized subroutines for automatically
transforming lemmings into gold.
</P>
<HR>
<H1>Contents</H1>
<UL>
- <LI><A HREF="#1">Topic</A>
+ <LI><A HREF="#1">Prerequisites</A>
<LI><A HREF="#2">Topic</A>
</UL>
<!-- ####################################################### -->
-<H2><A NAME="1">Topic</A></H2>
- <P>Blah.
+<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
+ these algorithms. Raw pointers make great candidates, thus
+ built-in arrays are fine containers. So do your own iterators.
+ <LI>The algorithms do not (and cannot) affect the container as a
+ whole; only the things between the two iterator endpoints. If
+ you pass a range of iterators only enclosing the middle third of
+ a container, then anything outside that range is inviolate.
+ </OL>
+ </P>
+ <P>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
+ 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
+ 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
+ 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
+ "past-the-end" rule that everybody loves to hate. The
+ <A HREF="../24_iterators/howto.html">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
+ (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>.
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.4 1999/12/15 16:57:06 pme Exp $
+<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:31 bkoz Exp $
</EM></P>
<TITLE>libstdc++-v3 HOWTO: Chapter 26</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/docs/26_numerics/">
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.1 2000/04/21 20:33:32 bkoz Exp $ -->
+<!-- $Id: howto.html,v 1.2 2000/06/28 15:14:39 gdr 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>,
- <TT>complex<></TT> and
- <LI>numerical functions such as <TT>accumulate</TT>;
- <TT>inner_product</TT>; <TT>partial_sum</TT> and
- <TT>adjacent_difference</TT>.
-</UL>
+<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>
+ 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>
<!-- ####################################################### -->
<!-- ####################################################### -->
<H2><A NAME="1">Complex Number Processing</A></H2>
- <P>Blah.
+ <P>Using <TT>complex<></TT> 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++89 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
+ 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>.
<HR>
<H2><A NAME="2">Array Processing</A></H2>
- <P>Blah.
+ <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++
+ 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,
+ 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
+ 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>.
<HR>
<H2><A NAME="3">Numerical Functions</A></H2>
- <P>Blah.
+ <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>.
+ <PRE>
+ int ar[50];
+ int someval = somefunction();
+
+ // ...initialize members of ar to something...
+
+ int sum = std::accumulate(ar,ar+50,0);
+ int sum_stuff = std::accumulate(ar,ar+50,someval);
+ int product = std::accumulate(ar,ar+50,1,std::multiplies<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,
+ 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>.
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:pme@sourceware.cygnus.com">Phil Edwards</A> or
<A HREF="mailto:gdr@egcs.cygnus.com">Gabriel Dos Reis</A>.
-<BR> $Id: howto.html,v 1.1 2000/04/21 20:33:32 bkoz Exp $
+<BR> $Id: howto.html,v 1.2 2000/06/28 15:14:39 gdr Exp $
</EM></P>
<TITLE>libstdc++-v3 configure options</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/">
<LINK REL=StyleSheet HREF="lib3styles.css">
-<!-- $Id: configopts.html,v 1.3 2000/05/16 17:06:39 pme Exp $ -->
+<!-- $Id: configopts.html,v 1.4 2000/05/19 19:55:50 pme Exp $ -->
</HEAD>
<BODY>
<DD><P>This is a grueling temporary hack no matter which way you look
at it. It's described in <A HREF="gccrebuild.html">its own
little page</A>. Note that other --enable flags will
- interact with this one. As of libstdc++-v3 snapshot 2.90.8,
+ interact with this one. In libstdc++-v3 snapshot 2.90.8,
this is enabled by default, with DIR
set to <TT> '../..' </TT>, so that building
the complete GCC sources with libstdc++-v3 in place works
- transparently.
+ transparently. Since then, library sources have been merged
+ into the compiler sources, and this option has been removed.
</P>
<DT><TT>--enable-cxx-flags=FLAGS</TT>
<HR>
<P CLASS="fineprint"><EM>
-$Id: configopts.html,v 1.3 2000/05/16 17:06:39 pme Exp $
+$Id: configopts.html,v 1.4 2000/05/19 19:55:50 pme Exp $
</EM></P>
<H3>Getting the sources by FTP or CVS</H3>
+<!-- The <URL:foo> syntax is the standard way of writing such things. No
+ link to the FTP site is given directly, encouraging mirror usage.
+-->
<P>Get the snapshot archive via FTP from
-<BLOCKQUOTE>
- <A HREF="ftp://sourceware.cygnus.com/pub/libstdc++/">
- ftp://sourceware.cygnus.com/pub/libstdc++/
- </A>
-</BLOCKQUOTE>
- You will probably need to use one of the
+ <TT><URL:ftp://sourceware.cygnus.com/pub/libstdc++/></TT>.
+ You will almost certainly need to use one of the
<A HREF="http://sourceware.cygnus.com/mirrors.html">mirror sites</A>
- due to the heavy load on the main server.
+ due to the extremely heavy load on the main server.
</P>
-<P> The master CVS repository for libstdc++-v3 is now a part of the
- gcc repository. As such, checking out the <TT>gcc</TT> module includes the
- current libstdc++-v3 development sources. To check out libstdc++-v3
- only, use <TT>libstdc++-v3</TT> instead of <TT>gcc</TT> as the module.
-
+<P>The master CVS repository for libstdc++-v3 is now a part of the gcc
+ repository. As such, checking out the <TT>gcc</TT> module includes
+ the current libstdc++-v3 development sources. To check out
+ libstdc++-v3 only, use <TT>libstdc++-v3</TT> instead of <TT>gcc</TT>
+ as the module.
<UL>
- <LI>Read only CVS repository available by anonymous CVS. Directions
- <A HREF="http://gcc.gnu.org/cvs.html"> here.
- </A>
-
- <P>
-
- <LI>Read-Write CVS repository available by authorized CVS via SSH.
- Directions <A HREF="http://gcc.gnu.org/cvswrite.html"> here.
- </A>
- </UL>
+ <LI>Read-only CVS repository is available by anonymous CVS. Directions
+ are <A HREF="http://gcc.gnu.org/cvs.html">here</A>. You can also
+ use anonymous CVS from one of the mirrors of the CVS repository.
+ <LI>Read-write CVS repository is available by authorized CVS via SSH.
+ Directions are <A HREF="http://gcc.gnu.org/cvswrite.html">here</A>.
+ </UL>
+</P>
+<P>One you have the GCC sources checked out over CVS, you can use the
+ <TT>contrib/gcc_update</TT> script to retrieve the latest changes, and
+ automatically update the timestamps of certain files. With the
+ timestamps updated, you won't need autoconf or the other tools (unless
+ you make changes, obviously).
</P>
-<p>You can also
+<P>You can also
<A HREF="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/libstdc++-v3?cvsroot=gcc">browse
- the CVS repository over the web</A>.
-
+ the CVS repository over the web</A>.
</P>
<TITLE>How to automatically rebuild libgcc.a.</TITLE>
<LINK REL="home" HREF="http://sourceware.cygnus.com/libstdc++/">
<LINK REL=StyleSheet HREF="lib3styles.css">
-<!-- $Id: gccrebuild.html,v 1.2 2000/05/03 16:11:02 pme Exp $ -->
+<!-- $Id: gccrebuild.html,v 1.3 2000/06/19 22:20:15 bkoz Exp $ -->
</HEAD>
<BODY>
as <EM>objdir</EM>; here it will be called <EM>GCCobjdir</EM>.
</P>
-<P>This is a kludge, and will go away eventually, as more and more of
- these copiler-level ABI switches get turned on by default. (In a
- sense, it has already gone away, as the library sources have been
- merged into the compiler sources.)
+<P>This was a kludge, and after the library sources were merged into
+ the compiler sources, this was commented out. If you must re-enable
+ it, you amy do so by uncommenting the GLIBCPP_ENABLE_RELIBGCC line in
+ configure.in and regenerating.
</P>
<HR>
<HR>
<P CLASS="fineprint"><EM>
-$Id: gccrebuild.html,v 1.2 2000/05/03 16:11:02 pme Exp $
+$Id: gccrebuild.html,v 1.3 2000/06/19 22:20:15 bkoz Exp $
</EM></P>