This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[v3] Documentation updates
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Subject: [v3] Documentation updates
- From: Phil Edwards <pedwards at disaster dot jaj dot com>
- Date: Fri, 14 Sep 2001 20:43:31 -0400
Initially brought on by the whole map insert-with-hint thing. I've verified
that multimap/multiset are free of the bug, and so updated the docs.
Cleared some other things on the minor-todo list also. Trunk and branch,
of course.
Over the weekend, hopefully, I'll have time to make the massive change
that Gerald's been requesting (<TT> -> <code> and so forth).
2001-09-14 Phil Edwards <pme@sources.redhat.com>
* docs/html/17_intro/headers_cc.txt: "Sync"/copy real file over.
* docs/html/17_intro/howto.html: Spacing and HTML markup fixes.
* docs/html/18_support/howto.html: It won't compile; it's not code.
* docs/html/19_diagnostics/howto.html: Point diagram seekers to
doxygen'd pages.
* docs/html/22_locale/howto.html: Comment for future work.
* docs/html/23_containers/howto.html: More comments.
* docs/html/25_algorithms/howto.html: It's a comment, not a
blunt command to the reader. (English grammar.)
Index: docs/html/17_intro/headers_cc.txt
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/headers_cc.txt,v
retrieving revision 1.1
diff -u -3 -p -r1.1 headers_cc.txt
--- headers_cc.txt 2000/12/10 04:03:09 1.1
+++ headers_cc.txt 2001/09/15 00:39:35
@@ -80,4 +80,4 @@
#include <cwctype>
#endif
-int main() { }
+int main() { return 0; }
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.6
diff -u -3 -p -r1.6 howto.html
--- howto.html 2001/06/08 03:53:35 1.6
+++ howto.html 2001/09/15 00:39:35
@@ -70,8 +70,7 @@
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
+ <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
@@ -82,22 +81,21 @@
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 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 (i.e. the typically higher-speed
- allocator is not even available in this configuration). There
- is a better way: It is possible to force the malloc-based
- allocator on a per-case-basis for some application code even
- when the above macro symbol is not defined. The author of this
- comment believes that is a better way to tune an application for
- high-speed using this implementation of the STL. Here is one
- possible example displaying the forcing of the malloc-based
+ <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
+ (i.e. the typically higher-speed allocator is not even available
+ in this configuration). There is a better way: It is possible
+ to force the malloc-based allocator on a per-case-basis for some
+ application code even when the above macro symbol is not defined.
+ The library team generally believes that this is a better way to tune
+ an application for high-speed using this implementation of the STL.
+ Here is one possible example displaying the forcing of the malloc-based
allocator over the typically higher-speed default allocator:
-
- std::list <void*, std::malloc_alloc> my_malloc_based_list;
+ <PRE>
+ std::list <void*, std::malloc_alloc> my_malloc_based_list;
+ </PRE>
</P>
<P>A recent journal article has described "atomic integer
operations," which would allow us to, well, perform updates
@@ -114,16 +112,18 @@
latest-to-oldest order.
<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">
- an early analysis of why __USE_MALLOC should be disable for
- the 3.0 release of libstdc++.</A>
+ 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">
+ an early analysis of why __USE_MALLOC should be disabled for
+ 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.
+ 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
Index: docs/html/18_support/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/18_support/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/05/30 21:54:58 1.3
+++ howto.html 2001/09/15 00:39:35
@@ -171,7 +171,7 @@
reverse order of registration, once per registration call.
(This isn't actually new.)
<LI>The previous two actions are "interleaved," that is,
- given this code:
+ given this pseudocode:
<PRE>
extern "C or C++" void f1 (void);
extern "C or C++" void f2 (void);
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.4
diff -u -3 -p -r1.4 howto.html
--- howto.html 2001/05/30 21:54:59 1.4
+++ howto.html 2001/09/15 00:39:35
@@ -59,8 +59,15 @@
<HR>
<H2><A NAME="2">Exception class hierarchy diagram</A></H2>
- <P>The <A HREF="exceptions_hiearchy.pdf">diagram</A> is in PDF, or
- at least it will be once it gets finished.
+ <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>.
Index: docs/html/22_locale/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/22_locale/howto.html,v
retrieving revision 1.4
diff -u -3 -p -r1.4 howto.html
--- howto.html 2001/08/08 02:48:58 1.4
+++ howto.html 2001/09/15 00:39:35
@@ -16,6 +16,10 @@
<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.
+ -->
<!-- ####################################################### -->
@@ -176,7 +180,7 @@
int main ()
{
std::string s ("Some Kind Of Initial Input Goes Here");
- Toupper up ( std::locale("C") );
+ Toupper up ( std::locale("C") );
Tolower down ( std::locale("C") );
// Change everything into upper case
Index: docs/html/23_containers/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/23_containers/howto.html,v
retrieving revision 1.7
diff -u -3 -p -r1.7 howto.html
--- howto.html 2001/08/24 20:34:34 1.7
+++ howto.html 2001/09/15 00:39:35
@@ -26,6 +26,7 @@
<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>
@@ -298,13 +299,19 @@
between <TT>h</TT> and <TT>h</TT>'s predecessor.
</UL>
</P>
+ <P>For <TT>multimap</TT> and <TT>multiset</TT>, 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>. You should not
- use a hint argument in those releases.)
-(Was it just with map or with all the rbtree-using containers? Still need
-to check that.)
+ 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
+ argument in those releases.)
</P>
<P>This behavior goes well with other container's <TT>insert()</TT>
functions which take an iterator: if used, the new item will be
@@ -326,6 +333,29 @@ to check that.)
<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
+ 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
+ constructor expression:
+ <PRE>
+ std::bitset<5> b ( std::string("10110") );
+ </PRE>
+ instead of
+ <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>
+
<!-- ####################################################### -->
Index: docs/html/25_algorithms/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/25_algorithms/howto.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 howto.html
--- howto.html 2001/05/30 21:55:02 1.3
+++ howto.html 2001/09/15 00:39:35
@@ -38,7 +38,7 @@
<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.
+ built-in arrays are fine containers, as well as your own iterators.
<LI>The algorithms do not (and cannot) affect the container as a
whole; only the things between the two iterator endpoints. If
you pass a range of iterators only enclosing the middle third of