howto.html, [...]: Fix typos and anachronisms.
2007-11-17 Jonathan Wakely <jwakely.gcc@gmail.com> * 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. From-SVN: r130255
This commit is contained in:
parent
478b2b9cb3
commit
04901f81ae
10 changed files with 112 additions and 75 deletions
|
@ -1,3 +1,11 @@
|
|||
2007-11-17 Jonathan Wakely <jwakely.gcc@gmail.com>
|
||||
|
||||
* 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 <pcarlini@suse.de>
|
||||
|
||||
* include/bits/stl_algobase.h (struct __lexicographical_compare):
|
||||
|
|
|
@ -169,10 +169,10 @@ qualified name</i></span> for each library symbol
|
|||
used, and usually enhanced, by strategic use of typedefs. (In the
|
||||
cases where the qualified verbage becomes unweidly.)
|
||||
</p></li>
|
||||
</ul>
|
||||
</ul></div>
|
||||
|
||||
<hr />
|
||||
<h2><a name="2.6">Using namespace composition</code></a></h2>
|
||||
<h2><a name="2.6">Using namespace composition</a></h2>
|
||||
|
||||
<p>
|
||||
<a href="http://gtkmm.sourceforge.net" target="_top">Gtk--</a> defines
|
||||
|
@ -182,12 +182,14 @@ cases where the qualified verbage becomes unweidly.)
|
|||
you put a <span class="emphasis"><i>using</i></span>-declaration into a
|
||||
namespace-definition: the imported symbol(s) gets imported into the
|
||||
currently active namespace(s). For example:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
namespace Gtk {
|
||||
using std::string;
|
||||
class Window { ... }
|
||||
}
|
||||
</pre>
|
||||
<p>
|
||||
In this example, <code>std::string</code> gets imported into
|
||||
namespace Gtk::. The result is that you don't have to use
|
||||
<code>std::string</code> 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.
|
||||
</p>
|
||||
<p>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).
|
||||
</p>
|
||||
<p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
|
||||
<p>See <a href="../faq/index.html#5_6">FAQ</a> (general overview), <a
|
||||
href="../23_containers/howto.html#3">23</a> (containers), and <a
|
||||
href="../27_io/howto.html#9">27</a> (I/O) for more information.
|
||||
</p>
|
||||
<p>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
|
||||
<p>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 <em>fast</em> 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</a> 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.
|
||||
</p>
|
||||
<p>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
|
||||
<code>--enable-libstdcxx-allocator</code>. ABI-changing.</a>
|
||||
<code>--enable-libstdcxx-allocator</code>. ABI-changing.
|
||||
</dd>
|
||||
|
||||
|
||||
|
|
|
@ -380,7 +380,7 @@
|
|||
</p>
|
||||
<p>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 <code>CharT</code> here):
|
||||
</p>
|
||||
<pre>
|
||||
template <typename CharT,
|
||||
|
@ -405,10 +405,7 @@
|
|||
<p>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.
|
||||
</p>
|
||||
<p>The C++ standard also requires that char_traits be specialized for
|
||||
instantiations of <code>char</code> and <code>wchar_t</code>, and it
|
||||
|
@ -417,16 +414,22 @@
|
|||
</p>
|
||||
<p>If you want to use character types other than char and wchar_t,
|
||||
such as <code>unsigned char</code> and <code>int</code>, 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 <code>int</code> and other
|
||||
built-in types.
|
||||
</p>
|
||||
<p>If you want to use your own special character class, then you have
|
||||
<a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot
|
||||
of work to do</a>, especially if you with to use i18n features
|
||||
(facets require traits information but don't have a traits argument).
|
||||
</p>
|
||||
<p>One example of how to specialize char_traits is given <a
|
||||
href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">in
|
||||
this message</a>, which was then put into the file <code>
|
||||
include/ext/pod_char_traits.h</code> at a later date. We agree
|
||||
<p>Another example of how to specialize char_traits was given <a
|
||||
href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the
|
||||
mailing list</a> and at a later date was put into the file <code>
|
||||
include/ext/pod_char_traits.h</code>. We agree
|
||||
that the way it's used with basic_string (scroll down to main())
|
||||
doesn't look nice, but that's because <a
|
||||
href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the
|
||||
|
@ -435,11 +438,6 @@
|
|||
be conforming C++</a>, due to the rule that CharT must be a POD.
|
||||
(See how tricky this is?)
|
||||
</p>
|
||||
<p>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...
|
||||
<a href="../17_intro/contribute.html">do you?</a>
|
||||
</p>
|
||||
<p>Return <a href="#top">to top of page</a> or
|
||||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
</p>
|
||||
|
|
|
@ -203,7 +203,7 @@ mechanism may be required.
|
|||
</li>
|
||||
|
||||
<li>
|
||||
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,
|
||||
|
|
|
@ -284,11 +284,13 @@
|
|||
<pre>
|
||||
a.insert(p,t);</pre>
|
||||
<p>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 "<code>t</code> is inserted
|
||||
as close as possible to the position just prior to
|
||||
<code>p</code>." (Library DR #233 addresses this topic, referring to
|
||||
<a href='http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html'>N1780</a>.
|
||||
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.
|
||||
</p>
|
||||
<p>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 @@
|
|||
<code>map</code> and <code>set</code> classes. You should not use a hint
|
||||
argument in those releases.)
|
||||
</p>
|
||||
<p>This behavior goes well with other container's <code>insert()</code>
|
||||
<p>This behavior goes well with other containers' <code>insert()</code>
|
||||
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 <code>end()</code>: the new item will
|
||||
actually be inserted after <code>end()</code>, but it also becomes the
|
||||
new <code>end()</code>.
|
||||
containers.
|
||||
</p>
|
||||
<p><strong>Note </strong> 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.
|
||||
</p>
|
||||
<p>Return <a href="#top">to top of page</a> or
|
||||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
|
|
|
@ -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
|
||||
<a href="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</a>
|
||||
<a href="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</a>
|
||||
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 <code>fd()</code> function.
|
||||
</li>
|
||||
</ul>
|
||||
<p>If you want to access a <code>filebuf</code>s file descriptor to
|
||||
<p>If you want to access a <code>filebuf</code>'s file descriptor to
|
||||
implement file locking (e.g. using the <code>fcntl()</code> system
|
||||
call) then you might be interested in Henry Suter's
|
||||
<a href="http://suter.home.cern.ch/suter/RWLock.html">RWLock</a>
|
||||
|
|
|
@ -306,7 +306,7 @@ containers have additional debug capability.
|
|||
<p>The following library components provide extra debugging
|
||||
capabilities in debug mode:</p>
|
||||
<ul>
|
||||
<li><code>std::basic_string</code> (no safe iterators)</li>
|
||||
<li><code>std::basic_string</code> (no safe iterators and see note below)</li>
|
||||
<li><code>std::bitset</code></li>
|
||||
<li><code>std::deque</code></li>
|
||||
<li><code>std::list</code></li>
|
||||
|
@ -321,6 +321,23 @@ containers have additional debug capability.
|
|||
<li><code>std::unordered_multiset</code></li>
|
||||
</ul>
|
||||
|
||||
<p>N.B. although there are precondition checks for some string operations,
|
||||
e.g. <code>operator[]</code>,
|
||||
they will not always be run when using the <code>char</code> and
|
||||
<code>wchar_t</code> specialisations (<code>std::string</code> and
|
||||
<code>std::wstring</code>). This is because libstdc++ uses GCC's
|
||||
<code>extern template</code> extension to provide explicit instantiations
|
||||
of <code>std::string</code> and <code>std::wstring</code>, 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 <code>-O1</code> might be enough to enable them. Alternatively
|
||||
<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> 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
|
||||
<code>__gnu_debug::basic_string</code> debugging container directly,
|
||||
which always works correctly.
|
||||
</p>
|
||||
|
||||
<h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
|
||||
|
||||
|
@ -339,9 +356,9 @@ containers have additional debug capability.
|
|||
thing of great importance to keep in mind when debugging C++ code
|
||||
that uses <code>new</code> and <code>delete</code>:
|
||||
there are different kinds of allocation schemes that can be used by
|
||||
<code> std::allocator </code>. For implementation details, see this
|
||||
<a href="ext/howto.html#3"> document</a> and look specifically for
|
||||
<code>GLIBCXX_FORCE_NEW</code>.
|
||||
<code> std::allocator </code>. For implementation details, see the
|
||||
<a href="ext/mt_allocator.html">mt allocator</a> documentation and
|
||||
look specifically for <code>GLIBCXX_FORCE_NEW</code>.
|
||||
</p>
|
||||
|
||||
<p>In a nutshell, the default allocator used by <code>
|
||||
|
|
|
@ -114,8 +114,7 @@
|
|||
<p>(Side note: for those of you wondering, <strong>"Why wasn't a hash
|
||||
table included in the Standard in the first #!$@ place?"</strong>
|
||||
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.)
|
||||
</p>
|
||||
<p>Return <a href="#top">to top of page</a> or
|
||||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
|
@ -137,6 +136,8 @@
|
|||
<li>Extensions allowing <code>filebuf</code>s to be constructed from
|
||||
stdio types are described in the
|
||||
<a href="../27_io/howto.html#11">chapter 27 notes</a>.</li>
|
||||
<li>The C++ Standard Library Technical Report adds many new features
|
||||
to the library, see <a href="../faq/index.html#5_5">FAQ 5.5</a>.</li>
|
||||
</ul>
|
||||
<p>Return <a href="#top">to top of page</a> or
|
||||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
|
@ -423,8 +424,8 @@
|
|||
<dt><a href="lwg-defects.html#241">241</a>:
|
||||
<em>Does unique_copy() require CopyConstructible and Assignable?</em>
|
||||
</dt>
|
||||
<dd>Add an helper for forward_iterator/output_iterator, fix the existing
|
||||
one for input_iterator/output_iterator not to rely on Assignability.
|
||||
<dd>Add a helper for forward_iterator/output_iterator, fix the existing
|
||||
one for input_iterator/output_iterator to not rely on Assignability.
|
||||
</dd>
|
||||
|
||||
<dt><a href="lwg-defects.html#243">243</a>:
|
||||
|
@ -639,7 +640,7 @@
|
|||
</dd>
|
||||
|
||||
<dt><a href="lwg-active.html#695">695</a>:
|
||||
<em>ctype<char>::classic_table() not accessible</em>
|
||||
<em>ctype<char>::classic_table() not accessible</em>
|
||||
</dt>
|
||||
<dd>Make the member functions table and classic_table public.
|
||||
</dd>
|
||||
|
|
|
@ -100,6 +100,7 @@
|
|||
<li><a href="#4_4_dlsym">program crashes when using library code
|
||||
in a dynamically-loaded library</a> </li>
|
||||
<li><a href="#4_4_leak">"memory leaks" in containers</a> </li>
|
||||
<li><a href="#4_4_list_size">list::size() is O(n)!</a> </li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#4_5">Aw, that's easy to fix!</a> </li>
|
||||
|
@ -278,22 +279,25 @@ which is no longer available, thanks deja...-->
|
|||
an installation document), but the tools required are few:
|
||||
</p>
|
||||
<ul>
|
||||
<li> 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++.
|
||||
<li> 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.
|
||||
</li>
|
||||
<li> GNU Make is required for GCC 3.4 and later.
|
||||
<li> GNU Make is required to build GCC 3.4 and later.
|
||||
</li>
|
||||
<li> The GNU Autotools are needed if you are messing with
|
||||
the configury or makefiles.
|
||||
</li>
|
||||
</ul>
|
||||
<p>The file <a href="../documentation.html">documentation.html</a>
|
||||
provides a good overview of the steps necessary to build, install,
|
||||
<p>The file <a href="../documentation.html#2">documentation.html</a>
|
||||
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.
|
||||
</p>
|
||||
<p>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.
|
||||
</p>
|
||||
|
||||
<p><a name="4_4_list_size"><strong>list::size() is O(n)!</strong></a>
|
||||
See the <a href='../23_containers/howto.html#6'>Containers</a>
|
||||
chapter.
|
||||
</p>
|
||||
<hr />
|
||||
<h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2>
|
||||
<p>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
|
||||
<a href="../ext/howto.html#5">the extensions page</a>.
|
||||
</p></li>
|
||||
<li><p>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.
|
||||
<li><p>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.)
|
||||
</p></li>
|
||||
<li><p>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
|
|||
<p>Who is your country's member body? Visit the
|
||||
<a href="http://www.iso.ch/">ISO homepage</a> and find out!
|
||||
</p>
|
||||
<p>The 2003 version of the standard (the 1998 version plus TC1) is
|
||||
available in print, ISBN 0-470-84674-7.
|
||||
</p>
|
||||
|
||||
<hr />
|
||||
<h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2>
|
||||
|
|
|
@ -56,17 +56,16 @@
|
|||
also lists the tools you will need if you wish to modify the source.
|
||||
</p>
|
||||
|
||||
<p>As of June 19, 2000, libstdc++ attempts to use tricky and
|
||||
space-saving features of the GNU toolchain, enabled with
|
||||
<code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>.
|
||||
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 <code>2.10.90</code>, or later, and you can get snapshots (as
|
||||
well as releases) of binutils
|
||||
<a href="ftp://sources.redhat.com/pub/binutils">here</a>. The
|
||||
configure process will automatically detect and use these features
|
||||
if the underlying support is present.
|
||||
<p>As of GCC 4.0.1 the minimum version of binutils required to build
|
||||
libstdc++ is <code>2.15.90.0.1.1</code>. You can get snapshots
|
||||
(as well as releases) of binutils from
|
||||
<a href="ftp://sources.redhat.com/pub/binutils">
|
||||
ftp://sources.redhat.com/pub/binutils</a>.
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>Finally, a few system-specific requirements: </p>
|
||||
|
|
Loading…
Add table
Reference in a new issue