This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[v3] Documentation updates


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 &lt;void*, std::malloc_alloc&gt;  my_malloc_based_list;
+      </PRE>
    </P>
    <P>A recent journal article has described &quot;atomic integer
       operations,&quot; 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 &quot;interleaved,&quot; 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">&quot;Hinting&quot; 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:  &quot;greater than&quot; should be replaced by
+      &quot;not less than&quot; and &quot;less than&quot; should be replaced
+      by &quot;not greater than.&quot;  (Why not replace greater with
+      greater-than-or-equal-to?  You probably could in your head, but the
+      mathematicians will tell you that it isn't the same thing.)
+   </P>
    <P>If the conditions are not met, then the hint is not used, and the
       insertion proceeds as if you had called <TT> a.insert(t) </TT>
       instead.  (<STRONG>Note </STRONG> that GCC releases prior to 3.0.2
-      had a bug in the case with <TT>hint == begin()</TT>.  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 &quot;Links&quot; from the
+      homepage, and from the C++ information &quot;defect reflector&quot;
+      link, select the library issues list.  Issue number 116 describes the
+      problem.
+   </P>
+   <P>For now you can simply make a temporary string object using the
+      constructor expression:
+      <PRE>
+      std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) );
+      </PRE>
+      instead of
+      <PRE>
+      std::bitset&lt;5&gt; b ( &quot;10110&quot; );    // invalid
+      </PRE>
+   </P>
+   <P>Return <A HREF="#top">to top of page</A> or
+      <A HREF="../faq/index.html">to the FAQ</A>.
+   </P>
+ 
 
 <!-- ####################################################### -->
 
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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]