This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[v3] documentation update
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Subject: [v3] documentation update
- From: Phil Edwards <pedwards at disaster dot jaj dot com>
- Date: Wed, 30 May 2001 16:38:15 -0400
Getting ready for 3.0...
2001-05-30 Phil Edwards <pme@sources.redhat.com>
* docs/doxygen/user.cfg.in: Minor addition.
* docs/html/documentation.html: Reorganize. Put most-looked-at
stuff first.
* docs/html/install.html: Update for 3.0. HTML fixups.
* 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/23_containers/howto.html: Likewise.
* docs/html/24_iterators/howto.html: Likewise. More notes.
* docs/html/25_algorithms/howto.html: Likewise.
* docs/html/26_numerics/howto.html: Likewise. More notes.
* docs/html/27_io/howto.html: Likewise.
* docs/html/ext/howto.html: Likewise.
* docs/html/faq/index.html: Likewise.
* docs/html/faq/index.txt: Regenerate.
* docs/html/27_io/iostreams_hierarchy.pdf: Remove in favor of
Doxygen-created documentation.
Index: docs/doxygen/user.cfg.in
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.5
diff -u -3 -p -r1.5 user.cfg.in
--- user.cfg.in 2001/04/29 01:40:34 1.5
+++ user.cfg.in 2001/05/30 21:51:03
@@ -20,7 +20,7 @@
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
-PROJECT_NAME = libstdc++-v3
+PROJECT_NAME = "libstdc++-v3 Source"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 documentation.html
--- documentation.html 2001/05/23 02:00:05 1.3
+++ documentation.html 2001/05/30 21:51:03
@@ -11,15 +11,42 @@
<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,
for releases and snapshots. The sole exception is the
- <A HREF="#4">automatically-generated source documentation</A>,
- available separately.
+ automatically-generated source documentation, available separately.
</P>
+<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>
+ The latest collection is <TT>libstdc++-doxygen-20010501.tar.gz</TT> (3.7MB),
+ <A HREF="libstdc++-doxygen-20010501/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
+ almost certainly need to use one of the
+ <A HREF="http://gcc.gnu.org/mirrors.html";>mirror sites</A> to download
+ the tarball. After unpacking, simply load
+ libstdc++-doxygen-20010501/index.html <!-- also update this date -->
+ in a browser. Feedback (and additional documentation!) is welcome.
+</P>
+
+<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
implementation of ISO 14882. A brief description follows the name
of the file.
</P>
+ <P>
<UL>
<LI><A HREF="17_intro/BADNAMES">BADNAMES</A>
- names to avoid because of potential collisions
@@ -35,8 +62,8 @@
<LI><A HREF="17_intro/HEADER_POLICY">HEADER_POLICY</A>
- header naming and sub-include structure
<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. -->
+ <!-- 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>
- instructions for building, using
@@ -46,13 +73,7 @@
<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>
-
-<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>
+ </P>
<HR>
<H2><A NAME="3">Chapter-Specific Information, Extensions, Notes and Advice</A></H2>
@@ -70,28 +91,6 @@
<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="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>
- The latest
- collection is libstdc++-doxygen-20010501.tar.gz (3.7MB), available in
- the libstdc++ snapshots directory at
- <TT><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/></TT>. You will
- almost certainly need to use one of the
- <A HREF="http://gcc.gnu.org/mirrors.html";>mirror sites</A> to download
- the tarball. After unpacking, simply load
- libstdc++-doxygen-20010501/index.html in a browser. You can also
- browse the same collection
- <A HREF="libstdc++-doxygen-20010501/index.html">online</A>.
- Feedback (and additional documentation!) is welcome.
-</P>
-
</BODY>
</HTML>
Index: docs/html/install.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/install.html,v
retrieving revision 1.5
diff -u -3 -p -r1.5 install.html
--- install.html 2001/04/03 00:26:54 1.5
+++ install.html 2001/05/30 21:51:03
@@ -39,29 +39,34 @@
<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++, one of the post-2.95.2 GCC
- snapshots (insert standard caveat about using snapshots rather
- than formal releases). You will need the full source
+ 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>
- <P>In addition, if you plan to modify the makefiles or regenerate
- the configure scripts you'll need the nuevo automake, libtool
- and autoconf to regenerate the Makefiles and configure
- scripts. These tools are all required to be installed in the
- same location (most linux distributions install these tools by
- default, so no worries.)
+ <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? -->
+ and libtool (multilanguage, version 1.4 or later), <!-- really? -->
+ in order to rebuild the files.
+ 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>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>If you don't have bash, and want to run <TT>'make check'</TT> to
- test your build, you'll need to get bash 2.x. Also recommended
- is GNU Make, since it is the only 'make' that will parse these
- makefiles correctly. We are moving to DejaGNU, so you'll
- probably want to get that.
- </P>
-
<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>.
@@ -73,44 +78,20 @@
<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
- have to get a version of the cygwin1.dll that is dated on or
- after February 1, 2000. This is necessary to successfully run
- the script "mknumeric_limits" which probes the
- floating-point
- environment of the host in question -- before this date, Cygwin
- would freeze when running this script. In addition, you may
- want to get a current version of libtool (say libtool-1.3.4
- and above) as earlier versions supposedly had problems creating
- shared libraries.
+ [snip]
</DL>
</P>
+-->
<HR>
<H2><A NAME="srcsetup">Setting up the source directories</A></H2>
- <P><EM>As the libstdc++-v3 sources and the core GCC sources have
- converged, more and more effort goes to building the
- library as the default version to be shipped with g++. With the
- 2.90.8 snapshot, and especially for CVS versions after this
- release, this is treated as the usual scenario. If you want to
- build the library all by itself, you will need to explicitly
- disable certain features (like namespaces) since the core GCC
- library, libgcc.a, will not be rebuilt with those same features.
- </EM>
- </P>
-
- <P>By default, all configurations of libstdc++-v3 now have namespaces
- enabled. Being able to select/de-select this option was a complex task
- that had hopelessly confused many otherwise intelligent people, and
- provided an endless stream of silent cursing and cries for help.
- Because of this, gcc sources are required, and are no longer optional.
- </P>
-
<P>The following definitions will be used throughout the rest of this
document:
<UL>
@@ -129,7 +110,7 @@
</UL>
Note:
<OL>
- <LI>The .91 snapshot and following are intended to replace the
+ <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.
@@ -140,58 +121,24 @@
</OL>
</P>
- <P>Since the release of libstdc++-2.90.8, configuration patches have gone
- into CVS gcc that make the management of the various libstdc++ source
- trees a bit easier. Because of this, both libstdc++-v2 and
- libstdc++-v3 and live together in peace, without the need
- for soft linking. The setup instructions are slightly different,
- depending on whether you want to use CVS gcc or a snapshot. Please
- choose the appropriate scenario:
- </P>
-
- <P><B>...with a gcc-2.9[67] snapshot</B>
- <P>Unpack the <EM>gccsrcdir</EM> and go into that directory. For
- instance, <TT>gcc-2.95.2</TT> is a valid <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>
+ <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
+ libstdc++-v3 directory which comes with that snapshot:
+ <PRE>
mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
rm -r libstdc++-v3</PRE>
- </P>
- <P>Next, unpack the libstdc++-v3 library tarball into the
- <EM>gccsrcdir</EM> directory; it will create a
- <EM>libsrcdir</EM> called <TT>libstdc++-<EM>version</EM></TT>:
- <PRE>
- gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
- </P>
- <P>Finally, make a soft link between <EM>libsrcdir</EM> and
- <TT>libstdc++-v3</TT> so that libstdc++-v3 will be the default C++
- library used.
- <PRE>
- ln -s <EM>libsrcdir</EM> libstdc++-v3</PRE>
- </P>
</P>
-
- <P><B>...with CVS gcc</B>
- <P>Check out or download the gcc sources: the resulting source
- directory 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>
- 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>:
- <PRE>
+ <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>:
+ <PRE>
gzip -dc libstdc++-version.tar.gz | tar xf -</PRE>
- </P>
- <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
- gcc's configure flags will be able to deal with the new library.
- <PRE>
+ </P>
+ <P>Finally, rename <EM>libsrcdir</EM> to <TT>libstdc++-v3</TT> so that
+ gcc's configure flags will be able to deal with the new library.
+ <PRE>
mv <EM>libsrcdir</EM> libstdc++-v3</PRE>
- </P>
</P>
@@ -201,7 +148,7 @@
<A HREF="http://gcc.gnu.org/install/";>GCC Installation
Instructions</A> first.
</P>
- <P>Due to namespaces, when building libstdc++-v3 you'll have to configure
+ <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>.
@@ -235,13 +182,13 @@
<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.
+ <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.
@@ -263,10 +210,9 @@
<PRE>
lib/
include/g++-v3/
+ backward/
bits/
- ext/
- CPU-vendor-OS/include/g++-v3/
- bits/
+ <EM>cpu-vendor-os</EM>/bits/
ext/</PRE>
</P>
<P>You can check the status of the build without installing it using
@@ -315,6 +261,10 @@
</P>
<P>Use the <TT>ldd(1)</TT> 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
+ you use Libtool to create your executables, these details are
+ taken care of for you.
</P>
</OL>
</P>
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/05/30 08:30:02 1.3
+++ howto.html 2001/05/30 21:51:03
@@ -125,8 +125,7 @@
<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. However, at the moment, the compiler
- treats std:: as the global namespace by default.
+ 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
really have new names. Marshall Cline's C++ FAQ Lite has a good
Index: docs/html/18_support/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/18_support/howto.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 howto.html
--- howto.html 2001/04/03 00:26:55 1.2
+++ howto.html 2001/05/30 21:51:03
@@ -186,6 +186,11 @@
out of them, Bad Things happen.
</OL>
</P>
+ <P>Note also that <TT>atexit()</TT> 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>
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/04/03 00:26:55 1.3
+++ howto.html 2001/05/30 21:51:03
@@ -93,16 +93,8 @@
object file. The checks are also cleaner and easier to read and
understand.
</P>
- <P>Concept checking can be disabled when you build your code, for example,
- to save space during a production build. Just define (via -D or
- #define) any of the macros
- <TT>_GLIBCPP_NO_CONCEPT_CHECKS (yes, with the leading underscore),
- <TT>_STL_NO_CONCEPT_CHECKS</TT> (also with the leading underscore),
- or <TT>NDEBUG</TT>. The first macro is specifically for this
- feature, the second is the disabling macro for the replaced SGI
- version (some code may assume SGI's version is in use), and the third
- is the usual macro to disable <TT>assert()</TT>, which is often turned
- off for production builds.
+ <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>Return <A HREF="#top">to top of page</A> or
Index: docs/html/20_util/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/20_util/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/04/03 00:26:55 1.3
+++ howto.html 2001/05/30 21:51:03
@@ -96,7 +96,7 @@
<PRE>
struct My_Type
{
- My_Type (My_Type const&);
+ My_Type (My_Type const&);
};
</PRE>
Note the const keyword; the object being copied shouldn't change.
@@ -120,23 +120,10 @@
void f()
{
- std::vector< std::auto_ptr<int> > vec_ap_int;
+ std::vector< std::auto_ptr<int> > vec_ap_int;
}
</PRE>
- Should you try this, you will see an error along the lines of the
- following (look through the ugly line-wrapping):
- <PRE>
-/installdir/include/g++-v3/bits/concept_checks.h: In
- static member function `static _Type
- <B>_STL_ERROR::__const_parameter_required_for_copy_constructor</B>(_Type, const
- _Type&) [with _Type = std::auto_ptr<int>]':
-/installdir/include/g++-v3/bits/concept_checks.h:383: passing
- `const std::auto_ptr<int>' as `this' argument of
- `std::auto_ptr<_Tp>::operator std::auto_ptr_ref<_Tp1>()
- [with _Tp1 = int, _Tp = int]' discards qualifiers
- </PRE>
- See the highlighted error? It starts with a message in all caps
- to get your attention.
+ 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>.
Index: docs/html/23_containers/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/23_containers/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/05/30 08:30:01 1.3
+++ howto.html 2001/05/30 21:51:03
@@ -45,10 +45,8 @@
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
- the address of the first element and the past-the-end element.
- <!-- a good explanation of the past-the-end rules is in order,
- probably a link somewhere
- -->
+ 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
rest of the code. For example, a pair of functions called
@@ -86,7 +84,7 @@
</P>
<P>Second, the line
<PRE>
- inline unsigned int lengthof (T (&)[sz]) { return sz; } </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
@@ -134,7 +132,7 @@
some extra space, of course. (If you plan to write code like the
incorrect example above, where the bitset is a local variable, then you
may have to talk your compiler into allowing that much stack space;
- there may be zero spae overhead, but it's all allocated inside the
+ 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
Index: docs/html/24_iterators/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/24_iterators/howto.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 howto.html
--- howto.html 2001/04/03 00:26:56 1.2
+++ howto.html 2001/05/30 21:51:03
@@ -70,7 +70,98 @@
<HR>
<H2><A NAME="2">It ends <EM>where?</EM></A></H2>
- <P>Blah.
+ <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
+ 'past-the-end' thing, until they remember their early algebra classes
+ (see, they </EM>told</EM> you that stuff would come in handy!) and
+ the concept of half-open ranges.
+ </P>
+ <P>First, some history, and a reminder of some of the funkier rules in
+ C and C++ for builtin arrays. The following rules have always been
+ true for both languages:
+ <OL>
+ <LI>You can point anywhere in the array, <EM>or to the first element
+ past the end of the array</EM>. A pointer that points to one
+ past the end of the array is guaranteed to be as unique as a
+ pointer to somewhere inside the array, so that you can compare
+ such pointers safely.
+ <LI>You can only dereference a pointer that points into an array.
+ If your array pointer points outside the array -- even to just
+ one past the end -- and you dereference it, Bad Things happen.
+ <LI>Strictly speaking, simply pointing anywhere else invokes
+ undefined behavior. Most programs won't puke until such a
+ pointer is actually dereferenced, but the standards leave that
+ up to the platform.
+ </OL>
+ The reason this past-the-end addressing was allowed is to make it
+ easy to write a loop to go over an entire array, e.g.,
+ while (*d++ = *s++);.
+ </P>
+ <P>So, when you think of two pointers delimiting an array, don't think
+ of them as indexing 0 through n-1. Think of them as <EM>boundary
+ markers</EM>:
+ <PRE>
+
+ beginning end
+ | |
+ | | This is bad. Always having to
+ | | remember to add or subtract one.
+ | | Off-by-one bugs very common here.
+ V V
+ array of N elements
+ |---|---|--...--|---|---|
+ | 0 | 1 | ... |N-2|N-1|
+ |---|---|--...--|---|---|
+
+ ^ ^
+ | |
+ | | This is good. This is safe. This
+ | | is guaranteed to work. Just don't
+ | | dereference 'end'.
+ beginning end
+
+ </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
+ 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>,
+ starting with (and including) the first element, and ending with (but
+ 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>
+ 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
+ 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
+ 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>.
Index: docs/html/25_algorithms/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/25_algorithms/howto.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 howto.html
--- howto.html 2001/04/03 00:26:56 1.2
+++ howto.html 2001/05/30 21:51:03
@@ -37,12 +37,12 @@
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.
+ 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.
+ 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
@@ -59,7 +59,7 @@
<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
+ <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
(it's not that hard, honest!), then the algorithms are a cakewalk.
Index: docs/html/26_numerics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/26_numerics/howto.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 howto.html
--- howto.html 2001/04/03 00:26:56 1.2
+++ howto.html 2001/05/30 21:51:03
@@ -35,6 +35,7 @@
<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>
@@ -120,6 +121,27 @@
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
+ of the C99 features that appear in libstdc++-v3.
+ </P>
+ <P>The C99 features depend on the <TT>--enable-c99</TT> 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
+ 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>.
Index: docs/html/27_io/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/27_io/howto.html,v
retrieving revision 1.4
diff -u -3 -p -r1.4 howto.html
--- howto.html 2001/04/03 00:26:56 1.4
+++ howto.html 2001/05/30 21:51:06
@@ -26,7 +26,6 @@
<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="#4">Iostreams class hierarchy diagram</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>
@@ -282,14 +281,6 @@
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>
-
-<HR>
-<H2><A NAME="4">Iostreams class hierarchy diagram</A></H2>
- <P>The <A HREF="iostreams_hierarchy.pdf">diagram</A> is in PDF. Rumor
- has it that once Benjamin Kosnik has been dead for a few decades,
- this work of his will be hung next to the Mona Lisa in the
- <A HREF="http://www.louvre.fr/";>Musee du Louvre</A>.
</P>
<HR>
cvs server: docs/html/27_io/iostreams_hierarchy.pdf was removed, no comparison available
Index: docs/html/ext/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/ext/howto.html,v
retrieving revision 1.4
diff -u -3 -p -r1.4 howto.html
--- howto.html 2001/05/02 01:39:03 1.4
+++ howto.html 2001/05/30 21:51:06
@@ -116,14 +116,21 @@
<P>
<UL>
<LI><TT>filebuf</TT>s have another ctor with this signature:<BR>
-<TT>basic_filebuf(int __fd, const char* __name, ios_base::openmode __mode);</TT>
+<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
attaching Unix sockets, pipes, and anything else which uses file
descriptors, into the IOStream buffering classes. The three
- arguments are as follows:<BR>
- <TT>int __fd, </TT>// open file descriptor<BR>
- <TT>const char* __name, </TT><BR>
- <TT>ios_base::openmode __mode </TT>// same as the other openmode uses
+ arguments are as follows:
+ <UL>
+ <LI><TT>__c_file_type* F </TT>
+ // the __c_file_type typedef usually boils down to stdio's FILE
+ <LI><TT>ios_base::openmode M </TT>
+ // same as all the other uses of openmode
+ <LI><TT>int_type B </TT>
+ // buffer size, defaults to BUFSIZ
+ </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
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.8
diff -u -3 -p -r1.8 index.html
--- index.html 2001/05/10 18:42:11 1.8
+++ index.html 2001/05/30 21:51:06
@@ -41,8 +41,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
<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">Is this a drop-in replacement for the
- libstdc++ that's shipped with g++?</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>
@@ -52,7 +51,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
<OL>
<LI><A HREF="#3_1">Can libstdc++-v3 be used with <my
favorite compiler>?</A>
- <LI><A HREF="#3_2">Building under Cygwin hangs/explodes!?</A>
+ <LI><A HREF="#3_2">[removed]</A>
<LI><A HREF="#3_3">Building under DEC OSF kills the assembler</A>
</OL>
@@ -82,7 +81,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
<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">Compiling with "-fnew-abi"</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>
@@ -146,10 +145,10 @@ HREF="http://gcc.gnu.org/gcc-2.95/builds
Drepper are the lead maintainers of the CVS archive.
</P>
<P>Development and discussion is held on the libstdc++ mailing
- list. Subscribing to the list, or searching the list
+ 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>. If you
- have questions, ideas, code, or are just curious, sign up!
+ 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>
<HR>
@@ -174,8 +173,8 @@ HREF="ftp://gcc.gnu.org/pub/libstdc++/li
HREF="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text";>a
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: Sooner, if you help.
+ <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>
@@ -254,20 +253,19 @@ which is no longer available, thanks dej
an installation document), but the tools required are few:
</P>
<UL>
- <LI> A release of libstdc++.
- <LI> A recent release of GCC (version 2.95 works). Note
- that building GCC is much easier and more automated
- than building the GCC 2.[78] series was.
- <LI> If you plan on hacking around with the makefiles, you
- will need the tools <A
-HREF="http://sources.redhat.com/autoconf/";>autoconf</A>and <A
-HREF="http://sources.redhat.com/automake/";>automake</A>.
+ <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 the only make that supports these makefiles.
+ <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>
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.
+ 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
@@ -278,11 +276,9 @@ HREF="http://sources.redhat.com/automake
</P>
<HR>
- <H2><A NAME="2_2">2.2 Is this a drop-in replacement for the
- libstdc++ that's shipped with g++?</A></H2>
- <P>Yes, as of 2.90.8, it is intended as such. And as of 2.91,
- libstdc++-v3 <EM>is</EM> the library that's shipped with
- g++, so much of this answer has become moot.
+ <H2><A NAME="2_2">2.2 [removed]</A></H2>
+ <P>This question has become moot and has been removed. The stub
+ is here to preserve numbering (and hence links/bookmarks).
</P>
<HR>
@@ -294,7 +290,7 @@ HREF="http://sources.redhat.com/automake
HREF="http://www.gnu.org/software/cvs/cvs.html";>CVS entry in
the GNU software catalogue</A> has a better description as
well as a
- <A HREF="http://www.cyclic.com/";>link to the makers of CVS</A>.
+ <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
@@ -309,22 +305,13 @@ HREF="http://sources.redhat.com/automake
<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>gmake
- install</TT>") to run the testsuite. Note that 2.91 does
- not use DejaGNU yet.
+ install</TT>") to run the testsuite.
</P>
<P>To run the testsuite on the library after building it, use
"gmake check" while in your build directory. To run
the testsuite on the library after building and installing it,
use "gmake check-install" instead.
</P>
- <P>The testsuite subdirectory in your build directory will then
- contain three files of the form YYYYMMDD-mkcheck*.txt. One of
- them (-mkcheck.txt itself) contains the results of the tests;
- this can be mailed to the list. The other files (-mkchecklog.txt
- and -mkcheckfiles.txt) contain messages from the compiler while
- building the test programs, and a list of the tests to be run,
- respectively.
- </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!
@@ -353,29 +340,9 @@ HREF="http://sources.redhat.com/automake
</P>
<HR>
- <H2><A NAME="3_2">3.2 Building under Cygwin hangs/explodes!?</A></H2>
- <P>Sometimes, yes. You're probably in the middle of generating
- the <TT>numeric_limits</TT> specializations when it hangs,
- right? Thought so...
- </P>
- <P>The <TT><limits></TT> header and its associated library
- code are platform-specific. These files get generated from
- scratch during installation, and it is this generator that is
- hanging. More specifically, the only sure way to determine
- what the <TT>numeric_limits<T>::traps</TT> boolean
- should be is to actually divide by zero and see if it is
- trapped or not.
- </P>
- <P>Under NT, this will occasionally just hang. On those
- occasions when the test does not hang, the zero-division is
- in fact trapped. That doesn't prevent hanging elsewhere.
- </P>
- <P>You have two options. You can get a newer cygwin1.dll (see the
- Cygwin paragraph in the
- <A HREF="../install.html">installation instructions</A>).
- Or you can get a prebuilt set of bits/std_limits.h and
- src/limitsMEMBERS.cc files from Mumit Khan's
- <A HREF="http://www.xraylith.wisc.edu/~khan/software/gnu-win32/libstdc++-v3.html";>Cygwin-related website</A>.
+ <H2><A NAME="3_2">3.2 [removed]</A></H2>
+ <P>This question has become moot and has been removed. The stub
+ is here to preserve numbering (and hence links/bookmarks).
</P>
<HR>
@@ -403,7 +370,7 @@ HREF="http://sources.redhat.com/automake
<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.
+ of the RELEASE-NOTES for the latest snapshot.
</P>
<!-- Yeah, I meant that "verbatim clip" thing literally... :-) -->
@@ -473,7 +440,8 @@ to the list</A>, Nathan Myers announced
libstdc++, either. Really! Please do not report these as bugs.
</P>
<A NAME="4_4_Weff">
- <P>The biggest of these is the quadzillions of warnings about the
+ <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
libstdc++ "-Weffc++-clean" is not a goal of the project,
for a few reasons. Mainly, that option tries to enforce
@@ -483,14 +451,15 @@ to the list</A>, Nathan Myers announced
</P>
</A>
<A NAME="4_4_rel_ops">
- <P>Another is the <TT>rel_ops</TT> namespace and the template
+ <P><STRONG>rel_ops</STRONG>
+ Another is the <TT>rel_ops</TT> 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),
- 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>.
+ visible in the same namespace as other comparison functions
+ (e.g., '<TT>using</TT>' 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
@@ -514,7 +483,8 @@ to the list</A>, Nathan Myers announced
</P>
</A>
<A NAME="4_4_glibc">
- <P>If you're on a GNU/Linux system and have just upgraded to
+ <P><STRONG>glibc</STRONG>
+ If you're on a GNU/Linux system and have just upgraded to
glibc 2.2, but are still using gcc 2.95.2, then you should have
read the glibc FAQ, specifically 2.34:
<PRE>
@@ -527,22 +497,24 @@ http://clisp.cons.org/~haible/gccinclude
</PRE>
Note that 2.95.x shipped with the
<A HREF="#4_4_interface">old v2 library</A> which is no longer
- maintained.
+ 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>If you see compilation errors containing messages about
+ <P><STRONG>concept checks</STRONG>
+ If you see compilation errors containing messages about
<TT> <EM>foo</EM>Concept </TT>and a<TT> constraints </TT>
- member function, then most
- likely you have violated one of the requirements for types used
- during instantiation of template containers. For example,
- EqualityComparableConcept appears
- if your types must be comparable with == and you have not
+ 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 disable the checks,
- is available <A HREF="../19_diagnostics/howto.html#3">here</A>.
+ <P>More information, including how to optionally enable/disable the
+ checks, is available
+ <A HREF="../19_diagnostics/howto.html#3">here</A>.
</P>
</A>
@@ -614,9 +586,8 @@ HREF="http://gcc.gnu.org/ml/libstdc++/19
<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>
is merged into libstdc++-v3 with changes as necessary.
- Currently release 3.3 is being used. Changes in the STL
- usually produce some weird bugs and lots of changes in the
- rest of the libstdc++ source as we scramble to keep up. :-)
+ Currently release 3.3 is being used as an initial codebase, plus
+ changes, fixes, and extensions.
</P>
<P>In particular, <TT>string</TT> is not from SGI and makes no
use of their "rope" class (which is included as an
@@ -642,15 +613,10 @@ HREF="http://gcc.gnu.org/ml/libstdc++/19
</P>
<HR>
- <H2><A NAME="5_5">5.5 Compiling with "-fnew-abi"</A></H2>
- <P>Towards the end of July 1999, this subject was brought up again
- on the mailing list under a different name. The related
- <A HREF="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00066.html";>thread</A>
- (by the name HOWTO-honor-std) is very instructive. More info
- is at the end of RELEASE-NOTES.
+ <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>This functionality is now automated and turned on by default.
- </P>
<HR>
<H2><A NAME="5_6">5.6 Is libstdc++-v3 thread-safe?</A></H2>
@@ -672,16 +638,15 @@ HREF="http://gcc.gnu.org/ml/libstdc++/19
<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>.
- (And if you've already registered with them, clicking this
- link will take you to directly to the place where you can
+ <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>.
+ (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>
@@ -701,3 +666,4 @@ Comments and suggestions are welcome, an
</BODY>
</HTML>
+