mirror of
git://gcc.gnu.org/git/gcc.git
synced 2024-12-22 16:30:10 +08:00
8ddad08b9e
* include/Makefile.am: Remove RCS Id strings.
* src/Makefile.am: Ditto.
* docs/doxygen/run_doxygen: Ditto.
* docs/html/configopts.html: Ditto.
* docs/html/documentation.html: Ditto.
* docs/html/explanations.html: Ditto.
* docs/html/install.html: Ditto.
* docs/html/17_intro/howto.html: Ditto.
* docs/html/18_support/howto.html: Ditto.
* docs/html/19_diagnostics/howto.html: Ditto.
* docs/html/20_util/howto.html: Ditto.
* docs/html/21_strings/howto.html: Ditto.
* docs/html/22_locale/howto.html: Ditto.
* docs/html/23_containers/howto.html: Ditto.
* docs/html/24_iterators/howto.html: Ditto.
* docs/html/25_algorithms/howto.html: Ditto.
* docs/html/26_numerics/howto.html: Ditto.
* docs/html/27_io/howto.html: Ditto.
* docs/html/ext/howto.html: Ditto.
* docs/html/ext/sgiexts.html: Ditto.
* docs/html/faq/index.html: Ditto.
* docs/html/faq/index.txt: Ditto.
From-SVN: r45836
320 lines
14 KiB
HTML
320 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
|
|
<html>
|
|
<head>
|
|
<meta HcodeP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<meta NAME="AUTHOR" CONTENT="pme@gcc.gnu.org (Phil Edwards)">
|
|
<meta NAME="KEYWORDS" CONTENT="HOWTO, libstdc++, GCC, g++, libg++, STL">
|
|
<meta NAME="DESCRIPTION" CONTENT="Notes for the libstdc++ extensions.">
|
|
<meta NAME="GENERATOR" CONTENT="vi and eight fingers">
|
|
<title>libstdc++-v3 HOWTO: Extensions</title>
|
|
<link REL=StyleSheet HREF="../lib3styles.css">
|
|
</head>
|
|
<body>
|
|
|
|
<h1 CLASS="centered"><a name="top">Extensions</a></h1>
|
|
|
|
<p>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.
|
|
</p>
|
|
<p><B>Before you leap in and use these</B>, be aware of two things:
|
|
<ol>
|
|
<li>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...
|
|
<li>You should know how to <a href="../faq/index.html#5_4">access
|
|
these headers properly</a>.
|
|
</ol>
|
|
</p>
|
|
|
|
|
|
<!-- ####################################################### -->
|
|
<hr>
|
|
<h1>Contents</h1>
|
|
<ul>
|
|
<li><a href="#1">Ropes and trees and hashes, oh my!</a>
|
|
<li><a href="#2">Added members and types</a>
|
|
<li><a href="#3">Allocators</a>
|
|
<li><a href="#4">Compile-time checks</a>
|
|
<li><a href="#5">LWG Issues</a>
|
|
</ul>
|
|
|
|
<hr>
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
|
|
<p>The SGI headers
|
|
<PRE>
|
|
<bvector>
|
|
<hash_map>
|
|
<hash_set>
|
|
<rope>
|
|
<slist>
|
|
<tree>
|
|
</PRE> are all here; <code><bvector></code> exposes the old bit_vector
|
|
class that was used before specialization of vector<bool> was
|
|
available (it's actually a typedef for the specialization now).
|
|
<code><hash_map></code> and <code><hash_set></code>
|
|
are discussed further below. <code><rope></code> is the SGI
|
|
specialization for large strings ("rope," "large
|
|
strings," get it? love those SGI folks).
|
|
<code><slist></code> is a singly-linked list, for when the
|
|
doubly-linked <code>list<></code> is too much space overhead, and
|
|
<code><tree></code> exposes the red-black tree classes used in the
|
|
implementation of the standard maps and sets.
|
|
</p>
|
|
<p>Okay, about those hashing classes... I'm going to foist most of the
|
|
work off onto SGI's own site.
|
|
</p>
|
|
<p>Each of the associative containers map, multimap, set, and multiset
|
|
have a counterpart which uses a
|
|
<a href="http://www.sgi.com/Technology/STL/HashFunction.html">hashing
|
|
function</a> 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
|
|
<a href="http://www.sgi.com/Technology/STL/hash.html">hash</a>.
|
|
You should specialize this functor for your class, or define your own,
|
|
before trying to use one of the hashing classes.
|
|
</p>
|
|
<p>The hashing classes support all the usual associative container
|
|
functions, as well as some extra constructors specifying the number
|
|
of buckets, etc.
|
|
</p>
|
|
<p>Why would you want to use a hashing class instead of the
|
|
"normal" implementations? Matt Austern writes:
|
|
<BLOCKQUOTE><em>[W]ith a well chosen hash function, hash tables
|
|
generally provide much better average-case performance than binary
|
|
search trees, and much worse worst-case performance. So if your
|
|
implementation has hash_map, if you don't mind using nonstandard
|
|
components, and if you aren't scared about the possibility of
|
|
pathological cases, you'll probably get better performance from
|
|
hash_map.</em></BLOCKQUOTE>
|
|
</p>
|
|
<p>(Side note: for those of you wondering, <B>"Why wasn't a hash
|
|
table included in the Standard in the first #!$@ place?"</B> 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.
|
|
</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="2">Added members and types</a></h2>
|
|
<p>Some of the classes in the Standard Library have additional
|
|
publicly-available members, and some classes are themselves not in
|
|
the standard. Of those, some are intended purely for the implementors,
|
|
for example, additional typedefs. Those won't be described here
|
|
(or anywhere else).
|
|
</p>
|
|
<p>
|
|
<ul>
|
|
<li>The extensions added by SGI are so numerous that they have
|
|
<a href="sgiexts.html">their own page</a>. Since the SGI STL is no
|
|
longer actively maintained, we will try and keep this code working
|
|
ourselves.
|
|
<li><code>filebuf</code>s have another ctor with this signature:<br>
|
|
<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code>
|
|
<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:
|
|
<ul>
|
|
<li><code>__c_file_type* F </code>
|
|
// the __c_file_type typedef usually boils down to stdio's FILE
|
|
<li><code>ios_base::openmode M </code>
|
|
// same as all the other uses of openmode
|
|
<li><code>int_type B </code>
|
|
// 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 <code>fdopen()</code>.
|
|
</ul>
|
|
</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="3">Allocators</a></h2>
|
|
<p>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.
|
|
</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">Compile-time checks</a></h2>
|
|
<p>Currently libstdc++-v3 uses the concept checkers from the Boost
|
|
library to perform <a href="../19_diagnostics/howto.html#3">optional
|
|
compile-time checking</a> of template instantiations of the standard
|
|
containers. They are described in the linked-to page.
|
|
</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="5">LWG Issues</a></h2>
|
|
<p>Everybody's got issues. Even the C++ Standard Library.
|
|
</p>
|
|
<p>The Library Working Group, or LWG, is the ISO subcommittee responsible
|
|
for making changes to the library. They periodically publish an
|
|
Issues List containing problems and possible solutions. As they reach
|
|
a consensus on proposed solutions, we often incorporate the solution
|
|
into libstdc++-v3.
|
|
</p>
|
|
<p>Here are the issues which have resulted in code changes to the library.
|
|
The links are to the specific defect reports from a <strong>partial
|
|
copy </strong> of the
|
|
Issues List. You can read the full version online at the ISO C++
|
|
Committee homepage, linked to on the GCC "Readings" page. If
|
|
you spend a lot of time reading the issues, we recommend downloading
|
|
the ZIP file and reading them locally.
|
|
</p>
|
|
<p>(NB: <strong>partial copy</strong> means that not all links within
|
|
the lwg-*.html pages will work.
|
|
Specifically, links to defect reports that have not been accorded full
|
|
DR status will probably break. Rather than trying to mirror the
|
|
entire issues list on our overworked web server, we recommend you go
|
|
to the LWG homepage instead.)
|
|
</p>
|
|
<p>
|
|
If a DR is not listed here, we may simply not have gotten to it yet;
|
|
feel free to submit a patch. Search the include/bits and src
|
|
directories for appearances of _GLIBCPP_RESOLVE_LIB_DEFECTS for
|
|
examples of style. Note that we usually do not make changes to the code
|
|
until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
|
|
</p>
|
|
<p><dl>
|
|
<!-- FIXME: locale_facets.h/tcc has a fix for get/num_get which I can't ID. -->
|
|
|
|
<dt><a href="lwg-defects.html#5">5</a>:
|
|
<em>string::compare specification questionable</em>
|
|
<dd>This should be two overloaded functions rather than a single function.
|
|
|
|
<dt><a href="lwg-defects.html#17">17</a>:
|
|
<em>Bad bool parsing</em>
|
|
<dd>Apparently extracting Boolean values was messed up...
|
|
|
|
<dt><a href="lwg-defects.html#25">25</a>:
|
|
<em>String operator<< uses width() value wrong</em>
|
|
<dd>Padding issues.
|
|
|
|
<dt><a href="lwg-defects.html#48">48</a>:
|
|
<em>Use of non-existent exception constructor</em>
|
|
<dd>An instance of <code>ios_base::failure</code> is constructed instead.
|
|
|
|
<dt><a href="lwg-defects.html#49">49</a>:
|
|
<em>Underspecification of ios_base::sync_with_stdio</em>
|
|
<dd>The return type is the <em>previous</em> state of synchronization.
|
|
|
|
<dt><a href="lwg-defects.html#50">50</a>:
|
|
<em>Copy constructor and assignment operator of ios_base</em>
|
|
<dd>These members functions are declared <code>private</code> and are
|
|
thus inaccessible. Specifying the correct semantics of
|
|
"copying stream state" was deemed too complicated.
|
|
|
|
<dt><a href="lwg-defects.html#68">68</a>:
|
|
<em>Extractors for char* should store null at end</em>
|
|
<dd>And they do now. An editing glitch in the last item in the list of
|
|
[27.6.1.2.3]/7.
|
|
|
|
<dt><a href="lwg-defects.html#74">74</a>:
|
|
<em>Garbled text for codecvt::do_max_length</em>
|
|
<dd>The text of the standard was gibberish. Typos gone rampant.
|
|
|
|
<dt><a href="lwg-defects.html#83">83</a>:
|
|
<em>string::npos vs. string::max_size()</em>
|
|
<dd>Safety checks on the size of the string should test against
|
|
<code>max_size()</code> rather than <code>npos</code>.
|
|
|
|
<dt><a href="lwg-defects.html#109">109</a>:
|
|
<em>Missing binders for non-const sequence elements</em>
|
|
<dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
|
|
<code>operator()</code> taking a non-const parameter.
|
|
|
|
<dt><a href="lwg-defects.html#110">110</a>:
|
|
<em>istreambuf_iterator::equal not const</em>
|
|
<dd>This was not a const member function. Note that the DR says to
|
|
replace the function with a const one; we have instead provided an
|
|
overloaded version with identical contents.
|
|
|
|
<dt><a href="lwg-defects.html#129">129</a>:
|
|
<em>Need error indication from seekp() and seekg()</em>
|
|
<dd>These functions set <code>failbit</code> on error now.
|
|
|
|
<dt><a href="lwg-defects.html#136">136</a>:
|
|
<em>seekp, seekg setting wrong streams?</em>
|
|
<dd><code>seekp</code> should only set the output stream, and
|
|
<code>seekg</code> should only set the input stream.
|
|
|
|
<!--<dt><a href="lwg-defects.html#159">159</a>:
|
|
<em>Strange use of underflow()</em>
|
|
<dd>In fstream.tcc, the basic_filebuf<>::showmanyc() function
|
|
should probably not be calling <code>underflow()</code>.-->
|
|
|
|
<dt><a href="lwg-active.html#167">167</a>:
|
|
<em>Improper use of traits_type::length()</em>
|
|
<dd><code>op<<</code> with a <code>const char*</code> was
|
|
calculating an incorrect number of characters to write.
|
|
|
|
<dt><a href="lwg-defects.html#181">181</a>:
|
|
<em>make_pair() unintended behavior</em>
|
|
<dd>This function used to take its arguments as reference-to-const, now
|
|
it copies them (pass by value).
|
|
|
|
<dt><a href="lwg-defects.html#195">195</a>:
|
|
<em>Should basic_istream::sentry's constructor ever set eofbit?</em>
|
|
<dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
|
|
|
|
<dt><a href="lwg-defects.html#211">211</a>:
|
|
<em>operator>>(istream&, string&) doesn't set failbit</em>
|
|
<dd>If nothing is extracted into the string, <code>op>></code> now
|
|
sets <code>failbit</code> (which can cause an exception, etc, etc).
|
|
|
|
<dt><a href="lwg-defects.html#214">214</a>:
|
|
<em>set::find() missing const overload</em>
|
|
<dd>Both <code>set</code> and <code>multiset</code> were missing
|
|
overloaded find, lower_bound, upper_bound, and equal_range functions
|
|
for const instances.
|
|
|
|
<dt><a href="lwg-defects.html#251">251</a>:
|
|
<em>basic_stringbuf missing allocator_type</em>
|
|
<dd>This nested typdef was originally not specified.
|
|
|
|
<dt><a href="lwg-defects.html#265">265</a>:
|
|
<em>std::pair::pair() effects overly restrictive</em>
|
|
<dd>The default ctor would build its members from copies of temporaries;
|
|
now it simply uses their respective default ctors.
|
|
|
|
<!--
|
|
<dt><a href="lwg-defects.html#"></a>:
|
|
<em></em>
|
|
<dd>
|
|
|
|
-->
|
|
</dl></p>
|
|
<p>Return <a href="#top">to top of page</a> or
|
|
<a href="../faq/index.html">to the FAQ</a>.
|
|
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<hr>
|
|
<P CLASS="fineprint"><em>
|
|
Comments and suggestions are welcome, and may be sent to
|
|
<a href="mailto:libstdc++@gcc.gnu.org">the mailing list</a>.
|
|
</em></p>
|
|
|
|
|
|
</body>
|
|
</html>
|