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:
Jonathan Wakely 2007-11-17 01:11:43 +00:00 committed by Jonathan Wakely
parent 478b2b9cb3
commit 04901f81ae
10 changed files with 112 additions and 75 deletions

View file

@ -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):

View file

@ -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>

View file

@ -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 &lt;typename CharT,
@ -405,10 +405,7 @@
<p>and functions such as char_traits&lt;CharT&gt;::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>

View file

@ -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
&quot;Footnotes for C/C++ developers&quot; in Haible for more information on
UCS-2/Unicode endian issues. (Summary: big endian seems most likely,

View file

@ -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 &quot;iterator p is a hint
pointing to where the insert should start to search,&quot; 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 &quot;<code>t</code> is inserted
as close as possible to the position just prior to
<code>p</code>.&quot; (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>.

View file

@ -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&amp;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>

View file

@ -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>

View file

@ -114,8 +114,7 @@
<p>(Side note: for those of you wondering, <strong>&quot;Why wasn't a hash
table included in the Standard in the first #!$@ place?&quot;</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&lt;char&gt;::classic_table() not accessible</em>
</dt>
<dd>Make the member functions table and classic_table public.
</dd>

View file

@ -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 &lt;backward/hash_map&gt;
#if __GNUC_MINOR__ == 0
#if __GNUC__ == 3 &amp;&amp; __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>

View file

@ -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>