From a5e3fe86a231394328a57ac1d3c157cca884602c Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Mon, 25 Sep 2000 21:42:14 +0000 Subject: [PATCH] documentation.html: Add link to... 2000-09-25 Phil Edwards * docs/documentation.html: Add link to... * docs/ext/howto.html: ...this. New dir/file, describing library extensions (both ours and SGI's). * docs/faq/index.html: Small updates. * docs/faq/index.txt: Regenerate. From-SVN: r36631 --- libstdc++-v3/ChangeLog | 8 ++ libstdc++-v3/docs/documentation.html | 1 + libstdc++-v3/docs/ext/howto.html | 147 +++++++++++++++++++++++++++ libstdc++-v3/docs/faq/index.html | 19 +++- libstdc++-v3/docs/faq/index.txt | 104 ++++++++++--------- 5 files changed, 225 insertions(+), 54 deletions(-) create mode 100644 libstdc++-v3/docs/ext/howto.html diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 9effd9a4008..e9543b74f51 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,11 @@ +2000-09-25 Phil Edwards + + * docs/documentation.html: Add link to... + * docs/ext/howto.html: ...this. New dir/file, describing library + extensions (both ours and SGI's). + * docs/faq/index.html: Small updates. + * docs/faq/index.txt: Regenerate. + 2000-09-25 Theodore Papadopoulo * bits/basic_file.h (_M_open_mode): Remove extra qualifier. diff --git a/libstdc++-v3/docs/documentation.html b/libstdc++-v3/docs/documentation.html index 26fd066f50a..1213b18341b 100644 --- a/libstdc++-v3/docs/documentation.html +++ b/libstdc++-v3/docs/documentation.html @@ -59,6 +59,7 @@
  • Chapter 25 (Algorithms)
  • Chapter 26 (Numerics)
  • Chapter 27 (I/O) +
  • Extensions to the Standard Library diff --git a/libstdc++-v3/docs/ext/howto.html b/libstdc++-v3/docs/ext/howto.html new file mode 100644 index 00000000000..dd7e3147cd3 --- /dev/null +++ b/libstdc++-v3/docs/ext/howto.html @@ -0,0 +1,147 @@ + + + + + + + + + libstdc++-v3 HOWTO: Extensions + + + + + + +

    Extensions

    + +

    Here we will make an attempt at describing the non-Standard extensions to + the library. Some of these are from SGI's STL, some of these are GNU's, + and some just seemed to appear on the doorstep. +

    +

    Before you leap in and use these, be aware of two things: +

      +
    1. Non-Standard means exactly that. The behavior, and the very + existence, of these extensions may change with little or no + warning. (Ideally, the really good ones will appear in the next + revision of C++.) Also, other platforms, other compilers, other + versions of g++ or libstdc++-v3 may not recognize these names, or + treat them differently, or... +
    2. You should know how to access + these headers properly. +
    +

    + + + +
    +

    Contents

    + + +
    + + + +

    Ropes and trees and hashes, oh my!

    +

    The SGI headers + 

    +     <bvector>
+     <hash_map>
+     <hash_set>
+     <rope>
+     <slist>
+     <tree>
+
    are all here; <bvector> exposes the old bit_vector + class that was used before specialization of vector<bool> was + available. <hash_map> and <hash_set> + are discussed further below. <rope> is the SGI + specialization for large strings ("rope," "large + strings," get it? love those SGI folks). + <slist> is a singly-linked list, for when the + doubly-linked list<> is too much space overhead, and + <tree> exposes the red-black tree classes used in the + implementation of the standard maps and sets. +

    +

    Okay, about those hashing classes... I'm going to foist most of the + work off onto SGI's own site. +

    +

    Each of the associative containers map, multimap, set, and multiset + have a counterpart which uses a + hashing + function to do the arranging, instead of a strict weak ordering + function. The classes take as one of their template parameters a + function object that will return the hash value; by default, an + instantiation of + hash. + You should specialize this functor for your class, or define your own, + before trying to use one of the hashing classes. +

    +

    The hashing classes support all the usual associative container + functions, as well as some extra constructors specifying the number + of buckets, etc. +

    +

    (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 undoubtably be + included in a future Standard. +

    +

    Return to top of page or + to the FAQ. +

    + +
    +

    Added members

    +

    Some of the classes in the Standard Library have additional + publicly-available members. Of those, some are intended purely for + the implementors, for example, additional typedefs. Those won't be + described here (or anywhere else). This list will grow slowly, since + we expect it to be rare -- most extensions will be self-contained. +

    +

    +

      +
    • filebufs have another ctor with this signature:
      +basic_filebuf(int __fd, const char* __name, ios_base::openmode __mode); +
      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:
      + int __fd, // open file descriptor
      + const char* __name,
      + ios_base::openmode __mode // same as the other openmode uses +
    +

    +

    Return to top of page or + to the FAQ. +

    + +
    +

    Allocators

    +

    This will be blank for a while. It will describe all of the different + memory allocators, most inherited from SGI's code. Input is solicited. +

    +

    Return to top of page or + to the FAQ. +

    + + + + + + + +
    +

    +Comments and suggestions are welcome, and may be sent to +Phil Edwards or +Gabriel Dos Reis. +
    $Id: howto.html,v 1.5 2000/09/19 21:54:48 pme Exp $ +

    + + + + diff --git a/libstdc++-v3/docs/faq/index.html b/libstdc++-v3/docs/faq/index.html index 5387090fb43..9e03841a746 100644 --- a/libstdc++-v3/docs/faq/index.html +++ b/libstdc++-v3/docs/faq/index.html @@ -13,7 +13,7 @@ ** Locations of "the most recent snapshot is the Nth" text are ** answers 1_1, 1_4, 4_1, 5_6. --> - + @@ -163,9 +163,14 @@ HREF="ftp://sources.redhat.com/pub/libstdc++/libstdc++-2.90.8.tar.gz">

    1.5 When is libstdc++ going to be finished?

    -

    Nathan Myers gave the best of all possible answers in Nathan Myers gave the best of all possible answers in a Usenet article.

    +which is no longer available, thanks deja...--> +

    Nathan Myers gave the best of all possible answers in a + Usenet article asking this question: Sooner, if you help. +

    +

    1.6 How do I contribute to the effort?

    @@ -530,7 +535,10 @@ to the list, Nathan Myers announced that he has started a list of

    The ISO Committee will meet periodically to review Defect Reports in the C++ Standard. Undoubtably some of these will result in changes to the Standard, which will be reflected in patches to - libstdc++. Some of that is already happening, see 4.2. + libstdc++. Some of that is already happening, see 4.2. Some of + those changes are being predicted by the library maintainers, and + we add code to the library based on what the current proposed + resolution specifies.

    The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the @@ -574,6 +582,9 @@ HREF="http://sources.redhat.com/ml/libstdc++/1999/msg00084.html">speculation #include <ext/hash_map>

    +

    Extensions to the library have + their own page. +

    5.5 Compiling with "-fnew-abi"

    @@ -643,7 +654,7 @@ HREF="http://sources.redhat.com/ml/libstdc++/1999/msg00084.html">speculation Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis. -
    $Id: index.html,v 1.4 2000/06/28 18:57:27 pme Exp $ +
    $Id: index.html,v 1.5 2000/07/11 21:45:08 pme Exp $

    diff --git a/libstdc++-v3/docs/faq/index.txt b/libstdc++-v3/docs/faq/index.txt index 3c47e697baf..84ddf639ccd 100644 --- a/libstdc++-v3/docs/faq/index.txt +++ b/libstdc++-v3/docs/faq/index.txt @@ -111,13 +111,13 @@ 1.5 When is libstdc++ going to be finished? - Nathan Myers gave the best of all possible answers in [42]a Usenet - article. + Nathan Myers gave the best of all possible answers in a Usenet article + asking this question: Sooner, if you help. _________________________________________________________________ 1.6 How do I contribute to the effort? - Here is [43]a page devoted to this topic. Subscribing to the mailing + Here is [42]a page devoted to this topic. Subscribing to the mailing list (see above, or the homepage) is a very good idea if you have something to contribute, or if you have spare time and want to help. Contributions don't have to be in the form of source code; anybody who @@ -152,11 +152,11 @@ extracted into an updated utilities library, but nobody has stated such a project yet. - (The [44]Boost site houses free C++ libraries that do varying things, + (The [43]Boost site houses free C++ libraries that do varying things, and happened to be started by members of the Standards Committee. Certain "useful stuff" classes will probably migrate there.) - For the bold and/or desperate, the [45]GCC FAQ describes where to find + For the bold and/or desperate, the [44]GCC FAQ describes where to find the last libg++ source. _________________________________________________________________ @@ -167,11 +167,11 @@ not need to be subscribed to the list to send a message to it. More information is available on the homepage (including how to browse the list archives); to send to the list, use - [46]libstdc++@sources.redhat.com. + [45]libstdc++@sources.redhat.com. If you have a question that you think should be included here, or if - you have a question about a question/answer here, contact [47]Phil - Edwards or [48]Gabriel Dos Reis. + you have a question about a question/answer here, contact [46]Phil + Edwards or [47]Gabriel Dos Reis. _________________________________________________________________ 2.0 Installation @@ -185,15 +185,15 @@ GCC is much easier and more automated than building the GCC 2.[78] series was. * If you plan on hacking around with the makefiles, you will need - the tools [49]autoconfand [50]automake. + the tools [48]autoconfand [49]automake. * GNU Make is the only make that supports these makefiles. - The file [51]documentation.html provides a good overview of the steps + The file [50]documentation.html 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. - The top-level install.html and [52]RELEASE-NOTES files contain the + The top-level install.html and [51]RELEASE-NOTES files contain the exact build and installation instructions. You may wish to browse those files over CVSweb ahead of time to get a feel for what's required. RELEASE-NOTES is located in the ".../docs/17_intro/" @@ -219,8 +219,8 @@ The Concurrent Versions System is one of several revision control packages. It was selected for GNU projects because it's free (speech), - free (beer), and very high quality. The [53]CVS entry in the GNU - software catalogue has a better description as well as a [54]link to + free (beer), and very high quality. The [52]CVS entry in the GNU + software catalogue has a better description as well as a [53]link to the makers of CVS. The "anonymous client checkout" feature of CVS is similar to anonymous @@ -294,9 +294,9 @@ doesn't prevent hanging elsewhere. You have two options. You can get a newer cygwin1.dll (see the Cygwin - paragraph in the [55]installation instructions). Or you can get a + paragraph in the [54]installation instructions). Or you can get a prebuilt set of bits/std_limits.h and src/limitsMEMBERS.cc files from - Mumit Khan's [56]Cygwin-related website. + Mumit Khan's [55]Cygwin-related website. _________________________________________________________________ 4.0 Known Bugs and Non-Bugs @@ -366,16 +366,16 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' 4.3 Bugs in the C++ language/lib specification - Yes, unfortunately, there are some. In a [57]message to the list, + Yes, unfortunately, there are some. In a [56]message to the list, Nathan Myers announced that he has started a list of problems in the ISO C++ Standard itself, especially with regard to the chapters that - concern the library. The list itself is [58]posted on his website. + concern the library. The list itself is [57]posted on his website. Developers who are having problems interpreting the Standard may wish to consult his notes. For those people who are not part of the ISO Library Group (i.e., nearly all of us needing to read this page in the first place :-), a - public list of the library defects is occasionally published [59]here. + public list of the library defects is occasionally published [58]here. _________________________________________________________________ 4.4 Things in libstdc++ that look like bugs @@ -396,16 +396,16 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' If you have found a bug in the library and you think you have a working fix, then send it in! The main GCC site has a page on - [60]submitting patches that covers the procedure, but for libstdc++ + [59]submitting patches that covers the procedure, but for libstdc++ you should of course send the patch to our mailing list, not the GCC - mailing list. The libstdc++ [61]contributors' page also talks about + mailing list. The libstdc++ [60]contributors' page also talks about how to submit patches. In addition to the description, the patch, and the ChangeLog entry, it is a Good Thing if you can additionally create a small test program to test for the presence of the bug that your patch fixes. Bugs have a way of being reintroduced; if an old bug creeps back in, it will be - caught immediately by the [62]testsuite -- but only if such a test + caught immediately by the [61]testsuite -- but only if such a test exists. _________________________________________________________________ @@ -432,7 +432,9 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' The ISO Committee will meet periodically to review Defect Reports in the C++ Standard. Undoubtably some of these will result in changes to the Standard, which will be reflected in patches to libstdc++. Some of - that is already happening, see 4.2. + that is already happening, see 4.2. Some of those changes are being + predicted by the library maintainers, and we add code to the library + based on what the current proposed resolution specifies. The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the hash tables from @@ -441,13 +443,13 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' Bugfixes and rewrites (to improve or fix thread safety, for instance) will of course be a continuing task. - [63]This question about the next libstdc++ prompted some brief but - interesting [64]speculation. + [62]This question about the next libstdc++ prompted some brief but + interesting [63]speculation. _________________________________________________________________ 5.3 What about the STL from SGI? - The [65]STL from SGI is merged into libstdc++-v3 with changes as + The [64]STL from SGI 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 libstd++ source as we scramble to keep up. :-) @@ -467,6 +469,8 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' files there by their path, as in: #include + + Extensions to the library have [65]their own page. _________________________________________________________________ 5.5 Compiling with "-fnew-abi" @@ -520,7 +524,7 @@ count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)' Comments and suggestions are welcome, and may be sent to [72]Phil Edwards or [73]Gabriel Dos Reis. - $Id: index.html,v 1.4 2000/06/28 18:57:27 pme Exp $ + $Id: index.html,v 1.5 2000/07/11 21:45:08 pme Exp $ References @@ -565,30 +569,30 @@ References 39. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/index.html 40. ftp://sources.redhat.com/pub/libstdc++/libstdc++-2.90.8.tar.gz 41. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/index.html - 42. http://www.deja.com/getdoc.xp?AN=469581698&fmt=text - 43. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/contribute.html - 44. http://www.boost.org/ - 45. http://gcc.gnu.org/fom_serv/cache/33.html - 46. mailto:libstdc++@sources.redhat.com - 47. mailto:pme@sources.redhat.com - 48. mailto:gdr@egcs.cygnus.com - 49. http://sources.redhat.com/autoconf/ - 50. http://sources.redhat.com/automake/ - 51. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/documentation.html - 52. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/RELEASE-NOTES - 53. http://www.gnu.org/software/cvs/cvs.html - 54. http://www.cyclic.com/ - 55. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/install.html - 56. http://www.xraylith.wisc.edu/~khan/software/gnu-win32/libstdc++-v3.html - 57. file://localhost/ml/libstdc++/1998/msg00006.html - 58. http://www.cantrip.org/draft-bugs.txt - 59. http://anubis.dkuug.dk/jtc1/sc22/wg21/ - 60. http://gcc.gnu.org/contribute.html - 61. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/contribute.html - 62. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/faq/index.html#2_4 - 63. http://sources.redhat.com/ml/libstdc++/1999/msg00080.html - 64. http://sources.redhat.com/ml/libstdc++/1999/msg00084.html - 65. http://www.sgi.com/Technology/STL/ + 42. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/contribute.html + 43. http://www.boost.org/ + 44. http://gcc.gnu.org/fom_serv/cache/33.html + 45. mailto:libstdc++@sources.redhat.com + 46. mailto:pme@sources.redhat.com + 47. mailto:gdr@egcs.cygnus.com + 48. http://sources.redhat.com/autoconf/ + 49. http://sources.redhat.com/automake/ + 50. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/documentation.html + 51. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/RELEASE-NOTES + 52. http://www.gnu.org/software/cvs/cvs.html + 53. http://www.cyclic.com/ + 54. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/install.html + 55. http://www.xraylith.wisc.edu/~khan/software/gnu-win32/libstdc++-v3.html + 56. file://localhost/ml/libstdc++/1998/msg00006.html + 57. http://www.cantrip.org/draft-bugs.txt + 58. http://anubis.dkuug.dk/jtc1/sc22/wg21/ + 59. http://gcc.gnu.org/contribute.html + 60. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/17_intro/contribute.html + 61. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/faq/index.html#2_4 + 62. http://sources.redhat.com/ml/libstdc++/1999/msg00080.html + 63. http://sources.redhat.com/ml/libstdc++/1999/msg00084.html + 64. http://www.sgi.com/Technology/STL/ + 65. file://localhost/home0/pedwards/src/egcsworking/libstdc++-v3/docs/ext/howto.html 66. file://localhost/ml/libstdc++/1999-q3/msg00066.html 67. http://sources.redhat.com/libstdc++/17_intro/howto.html#3 68. http://sources.redhat.com/libstdc++/23_containers/howto.html -- 2.30.2