From a651fce5092b6211905181387ba25bf9ea953f73 Mon Sep 17 00:00:00 2001 From: redi Date: Sat, 17 Nov 2007 01:11:43 +0000 Subject: [PATCH] 2007-11-17 Jonathan Wakely * docs/html/17_intro/howto.html, docs/html/21_strings/howto.html, docs/html/22_locale/codecvt.html, docs/html/23_containers/howto.html, docs/html/27_io/howto.html, docs/html/ext/howto.html, docs/html/debug.html, docs/html/install.html, docs/html/faq/index.html: Fix typos and anachronisms. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@130255 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/ChangeLog | 8 +++++ libstdc++-v3/docs/html/17_intro/howto.html | 21 +++++++------ libstdc++-v3/docs/html/21_strings/howto.html | 30 +++++++++--------- libstdc++-v3/docs/html/22_locale/codecvt.html | 2 +- libstdc++-v3/docs/html/23_containers/howto.html | 24 +++++++-------- libstdc++-v3/docs/html/27_io/howto.html | 4 +-- libstdc++-v3/docs/html/debug.html | 25 ++++++++++++--- libstdc++-v3/docs/html/ext/howto.html | 11 ++++--- libstdc++-v3/docs/html/faq/index.html | 41 ++++++++++++++++--------- libstdc++-v3/docs/html/install.html | 21 ++++++------- 10 files changed, 112 insertions(+), 75 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index bcf8f37..95fbeae 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,11 @@ +2007-11-17 Jonathan Wakely + + * docs/html/17_intro/howto.html, docs/html/21_strings/howto.html, + docs/html/22_locale/codecvt.html, docs/html/23_containers/howto.html, + docs/html/27_io/howto.html, docs/html/ext/howto.html, + docs/html/debug.html, docs/html/install.html, + docs/html/faq/index.html: Fix typos and anachronisms. + 2007-11-16 Paolo Carlini * include/bits/stl_algobase.h (struct __lexicographical_compare): diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 828959c..d3bd6df 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -169,10 +169,10 @@ qualified name for each library symbol used, and usually enhanced, by strategic use of typedefs. (In the cases where the qualified verbage becomes unweidly.)

- +
-

Using namespace composition

+

Using namespace composition

Gtk-- defines @@ -182,12 +182,14 @@ cases where the qualified verbage becomes unweidly.) you put a using-declaration into a namespace-definition: the imported symbol(s) gets imported into the currently active namespace(s). For example: +

 	  namespace Gtk {
 	  using std::string;
 	  class Window { ... }
 	  }
+

In this example, std::string gets imported into namespace Gtk::. The result is that you don't have to use std::string in this header, but still @@ -210,7 +212,7 @@ cases where the qualified verbage becomes unweidly.) library. This information is GCC-specific since the C++ standard does not address matters of multithreaded applications. Unless explicitly prefaced, all information in this section is - current as of the GCC 3.0 release and all later point releases. + relevant to the GCC 3.0 release and all later releases.

Earlier GCC releases had a somewhat different approach to threading configuration and proper compilation. Before GCC 3.0, @@ -257,13 +259,13 @@ cases where the qualified verbage becomes unweidly.) AFAIK, none of this is properly documented anywhere other than in ``gcc -dumpspecs'' (look at lib and cpp entries).

-

See FAQ (general overview), See FAQ (general overview), 23 (containers), and 27 (I/O) for more information.

-

The libstdc++ library (unlike libstdc++-v2, all of it, not - just the STL) has been designed so that multithreaded - applications using it may be written. The first problem is +

The libstdc++ library has been designed so that it can be used in + multithreaded applications (with libstdc++-v2 this was + only true of the STL parts.) The first problem is finding a fast method of implementation portable to all platforms. Due to historical reasons, some of the library is written against per-CPU-architecture spinlocks and other parts @@ -274,7 +276,8 @@ cases where the qualified verbage becomes unweidly.) href="http://www.sgi.com/tech/stl/thread_safety.html">same definition that SGI uses for their STL subset. However, the exception for read-only containers only applies to the STL - components. + components. This definition is widely-used and something similar + will be used in the next version of the C++ standard library.

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 @@ -482,7 +485,7 @@ cases where the qualified verbage becomes unweidly.) default. When defined, memory allocation and allocators controlled by libstdc++ call operator new/delete without caching and pooling. Configurable via - --enable-libstdcxx-allocator. ABI-changing. + --enable-libstdcxx-allocator. ABI-changing. diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html index 1c32672..d5cd24d 100644 --- a/libstdc++-v3/docs/html/21_strings/howto.html +++ b/libstdc++-v3/docs/html/21_strings/howto.html @@ -380,7 +380,7 @@

That's the theory. Remember however that basic_string has additional type parameters, which take default arguments based on the character - type (called CharT here): + type (called CharT here): 

       template <typename CharT,
@@ -405,10 +405,7 @@
    
and functions such as char_traits<CharT>::foo() are not
       actually defined anywhere for the general case.  The C++ standard
       permits this, because writing such a definition to fit all possible
-      CharT's cannot be done.  (For a time, in earlier versions of GCC,
-      there was a mostly-correct implementation that let programmers be
-      lazy.  :-)  But it broke under many situations, so it was removed.
-      You are no longer allowed to be lazy and non-portable.)
+      CharT's cannot be done.
    

    
The C++ standard also requires that char_traits be specialized for
       instantiations of char and wchar_t, and it
@@ -417,16 +414,22 @@
    

    
If you want to use character types other than char and wchar_t,
       such as unsigned char and int, you will
-      need to write specializations for them at the present time.  If you
-      want to use your own special character class, then you have
+      need suitable specializations for them.  For a time, in earlier
+      versions of GCC, there was a mostly-correct implementation that
+      let programmers be lazy but it broke under many situations, so it
+      was removed.  GCC 3.4 introduced a new implementation that mostly
+      works and can be specialized even for int and other
+      built-in types.
+   

+   
If you want to use your own special character class, then you have
       a lot
       of work to do, especially if you with to use i18n features
       (facets require traits information but don't have a traits argument).
    

-   
One example of how to specialize char_traits is given in
-      this message, which was then put into the file 
-      include/ext/pod_char_traits.h at a later date.  We agree
+   
Another example of how to specialize char_traits was given on the
+      mailing list and at a later date was put into the file 
+      include/ext/pod_char_traits.h.  We agree
       that the way it's used with basic_string (scroll down to main())
       doesn't look nice, but that's because the
@@ -435,11 +438,6 @@
       be conforming C++, due to the rule that CharT must be a POD.
       (See how tricky this is?)
    

-   
Other approaches were suggested in that same thread, such as providing
-      more specializations and/or some helper types in the library to assist
-      users writing such code.  So far nobody has had the time...
-      do you?
-   

    
Return to top of page or
       to the FAQ.
    

diff --git a/libstdc++-v3/docs/html/22_locale/codecvt.html b/libstdc++-v3/docs/html/22_locale/codecvt.html
index 24b412b..c760c09 100644
--- a/libstdc++-v3/docs/html/22_locale/codecvt.html
+++ b/libstdc++-v3/docs/html/22_locale/codecvt.html
@@ -203,7 +203,7 @@ mechanism may be required.
 
 
 
  • 
- Some encodings are require explicit endian-ness. As such, some kind
+ Some encodings 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,
diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html
index eab90e8..c4b6eb8 100644
--- a/libstdc++-v3/docs/html/23_containers/howto.html
+++ b/libstdc++-v3/docs/html/23_containers/howto.html
@@ -284,11 +284,13 @@
    
           a.insert(p,t);
    
    
    where 'p' is an iterator into the container 'a', and 't' is the item
-      to insert.  The standard says that "iterator p is a hint
-      pointing to where the insert should start to search," but
-      specifies nothing more.  (LWG Issue #233, currently in review,
-      addresses this topic, but I will ignore it here because it is not yet
-      finalized.)
+      to insert.  The standard says that "t is inserted
+      as close as possible to the position just prior to
+      p." (Library DR #233 addresses this topic, referring to
+      N1780.
+      Since version 4.2 GCC implements the resolution to DR 233, so that
+      insertions happen as close as possible to the hint. For earlier releases
+      the hint was only used as described below.
    
    
    
    Here we'll describe how the hinting works in the libstdc++
       implementation, and what you need to do in order to take advantage of
@@ -342,21 +344,17 @@
       map and set classes.  You should not use a hint
       argument in those releases.)
    
    
-   
    This behavior goes well with other container's insert()
+   
    This behavior goes well with other containers' insert()
       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 end():  the new item will
-      actually be inserted after end(), but it also becomes the
-      new end().
+      containers. 
    
    
    
    Note  also that the hint in this implementation is a
-      one-shot.  The insertion-with-hint routines check the immediately
+      one-shot.  The older 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.)
+      logarithmic time.
    
    
    
    Return to top of page or
       to the FAQ.
diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html
index 067be3a..46d03b3 100644
--- a/libstdc++-v3/docs/html/27_io/howto.html
+++ b/libstdc++-v3/docs/html/27_io/howto.html
@@ -306,7 +306,7 @@
       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
-      this
+      this
       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.)
@@ -756,7 +756,7 @@
          descriptor, and provides the fd() function.
      
    • 
    
-   
    If you want to access a filebufs file descriptor to
+   
    If you want to access a filebuf's file descriptor to
       implement file locking (e.g. using the fcntl() system
       call) then you might be interested in Henry Suter's
       RWLock
diff --git a/libstdc++-v3/docs/html/debug.html b/libstdc++-v3/docs/html/debug.html
index 6e0369b..61c6a8b 100644
--- a/libstdc++-v3/docs/html/debug.html
+++ b/libstdc++-v3/docs/html/debug.html
@@ -306,7 +306,7 @@ containers have additional debug capability.
 
    The following library components provide extra debugging
   capabilities in debug mode:
    
 
      
-  
    • std::basic_string (no safe iterators)
      • 
+  
    • std::basic_string (no safe iterators and see note below)
      • 
   
    • std::bitset
      • 
   
    • std::deque
      • 
   
    • std::list
      • 
@@ -321,6 +321,23 @@ containers have additional debug capability.
   
    • std::unordered_multiset
      • 
 
    
 
+
    N.B. although there are precondition checks for some string operations,
+e.g.  operator[],
+they will not always be run when using the char and
+wchar_t specialisations (std::string and
+std::wstring).  This is because libstdc++ uses GCC's
+extern template extension to provide explicit instantiations
+of std::string and std::wstring, and those
+explicit instantiations don't include the debug-mode checks.  If the
+containing functions are inlined then the checks will run, so compiling
+with -O1 might be enough to enable them.  Alternatively
+-D_GLIBCXX_EXTERN_TEMPLATE=0 will suppress the declarations
+of the explicit instantiations and cause the functions to be instantiated
+with the debug-mode checks included, but this is unsupported and not
+guaranteed to work.  For full debug-mode support you can use the
+__gnu_debug::basic_string debugging container directly,
+which always works correctly.
+
    
 
 
    Tips for memory leak hunting
    
 
@@ -339,9 +356,9 @@ containers have additional debug capability.
    thing of great importance to keep in mind when debugging C++ code
    that uses new and delete:
    there are different kinds of allocation schemes that can be used by
-    std::allocator . For implementation details, see this
-    document and look specifically for
-   GLIBCXX_FORCE_NEW. 
+    std::allocator . For implementation details, see the
+   mt allocator documentation and
+   look specifically for GLIBCXX_FORCE_NEW. 
 
    
 
 
    In a nutshell, the default allocator used by 
diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html
index 5dea146..cb0a74e 100644
--- a/libstdc++-v3/docs/html/ext/howto.html
+++ b/libstdc++-v3/docs/html/ext/howto.html
@@ -114,8 +114,7 @@
    
    (Side note:  for those of you wondering, "Why wasn't a hash
       table included in the Standard in the first #!$@ place?"
       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.)
+      unorganized a fashion.)
    
    
    
    Return to top of page or
       to the FAQ.
@@ -137,6 +136,8 @@
      
  • Extensions allowing filebufs to be constructed from
          stdio types are described in the
          chapter 27 notes.
    • 
+     
  • The C++ Standard Library Technical Report adds many new features
+         to the library, see FAQ 5.5.
    • 
    
    
    Return to top of page or
       to the FAQ.
@@ -423,8 +424,8 @@
     
    241:
         Does unique_copy() require CopyConstructible and Assignable?
     
    
-    
    Add an helper for forward_iterator/output_iterator, fix the existing
-        one for input_iterator/output_iterator not to rely on Assignability.
+    
    Add a helper for forward_iterator/output_iterator, fix the existing
+        one for input_iterator/output_iterator to not rely on Assignability.
     
    
 
     
    243:
@@ -639,7 +640,7 @@
     
 
     
    695:
-        ctype::classic_table() not accessible
+        ctype<char>::classic_table() not accessible
     
    
     
    Make the member functions table and classic_table public.
     
    
diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html
index de316d1..e353a1f 100644
--- a/libstdc++-v3/docs/html/faq/index.html
+++ b/libstdc++-v3/docs/html/faq/index.html
@@ -100,6 +100,7 @@
            
  • program crashes when using library code
                                in a dynamically-loaded library 
    • 
            
  • "memory leaks" in containers 
    • 
+           
  • list::size() is O(n)! 
    • 
          
          
          
  • Aw, that's easy to fix! 
    • 
@@ -278,22 +279,25 @@ which is no longer available, thanks deja...-->
          an installation document), but the tools required are few:
       
    
          
      
-            
    •  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++.
+            
    •  A 3.x or later release of GCC.  Either install a suitable
+                 package for your system, or compile GCC from the sources.
+                 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++ but you
+                 should consult the documentation that comes with the
+                 sources, the instructions are no longer included here.
             
      • 
-            
    •  GNU Make is required for GCC 3.4 and later.
+            
    •  GNU Make is required to build GCC 3.4 and later.
             
      • 
             
    •  The GNU Autotools are needed if you are messing with
                  the configury or makefiles.
             
      • 
          
    
-      
    The file documentation.html
-         provides a good overview of the steps necessary to build, install,
+      
    The file documentation.html
+         links to documentation 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.
+         with flags such as --enable-threads are there also.
       
    
       
    The top-level install.html file contains
          the exact build and installation instructions.  You may wish to
@@ -794,6 +798,10 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
          first.
       
    
 
+      
    list::size() is O(n)!
+         See the Containers
+         chapter.
+      
    
 
    
    
    4.5 Aw, that's easy to fix!
    
       
    If you have found a bug in the library and you think you have
@@ -851,10 +859,12 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
          resolution specifies.  Those additions are listed in
          the extensions page.
       
    
-      
  • 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.
+      
  • Performance tuning.  Lots of performance tuning was done for the
+         3.x releases, including memory expansion in container classes and
+         buffer usage in synchronized stream objects.
+         Later performance-related work includes "move semantics"
+         for containers and (optional) non-reference-counted strings (which
+         can give performance benefits for multithreaded programs.)
       
    • 
       
  • An ABI for libstdc++ is being developed, so that
          multiple binary-incompatible copies of the library can be replaced
@@ -933,7 +943,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
         namespace extension { using ::hash_map; }; // inherit globals
       #else
         #include <backward/hash_map>
-        #if __GNUC_MINOR__ == 0
+        #if __GNUC__ == 3 && __GNUC_MINOR__ == 0
           namespace extension = std;               // GCC 3.0
         #else
           namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
@@ -1110,6 +1120,9 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
       
    Who is your country's member body?  Visit the
          ISO homepage and find out!
       
    
+      
    The 2003 version of the standard (the 1998 version plus TC1) is
+         available in print, ISBN 0-470-84674-7.
+      
    
 
 
    
    
    5.8 What's an ABI and why is it so messy?
    
diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html
index 120f0c8..3166ebc 100644
--- a/libstdc++-v3/docs/html/install.html
+++ b/libstdc++-v3/docs/html/install.html
@@ -56,17 +56,16 @@
       also lists the tools you will need if you wish to modify the source.
    
    
 
-   
    As of June 19, 2000, libstdc++ attempts to use tricky and
-      space-saving features of the GNU toolchain, enabled with
-      -ffunction-sections -fdata-sections -Wl,--gc-sections.
-      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++).  The version of these tools should
-      be 2.10.90, or later, and you can get snapshots (as
-      well as releases) of binutils
-      here. The
-      configure process will automatically detect and use these features
-      if the underlying support is present.
+   
    As of GCC 4.0.1 the minimum version of binutils required to build
+      libstdc++ is 2.15.90.0.1.1. You can get snapshots
+      (as well as releases) of binutils from
+      
+      ftp://sources.redhat.com/pub/binutils.
+      Older releases of libstdc++ do not require such a recent version,
+      but to take full advantage of useful space-saving features and
+      bug-fixes you should use a recent binutils if possible.
+      The configure process will automatically detect and use these
+      features if the underlying support is present.
    
    
 
    
    Finally, a few system-specific requirements: 
    
-- 
2.7.4