How to contribute

From: Jonathan Wakely Date: Thu, 5 Sep 2002 15:47:54 +0000 (+0000) Subject: Makefile: Use more portable shell wildcard. X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=64a6f971868d0d6cd64df9325ffb6600e538b022;p=gcc.git Makefile: Use more portable shell wildcard. 2002-09-05 Jonathan Wakely * docs/html/Makefile: Use more portable shell wildcard. * docs/html/makedoc.awk: Nest elements correctly for XHTML conversion. * docs/html/configopts.html, docs/html/documentation.html, docs/html/explanations.html, docs/html/install.html, docs/html/17_intro/contribute.html, docs/html/17_intro/howto.html, docs/html/17_intro/license.html, docs/html/18_support/howto.html, docs/html/19_diagnostics/howto.html, docs/html/20_util/howto.html, docs/html/21_strings/howto.html, docs/html/22_locale/codecvt.html, docs/html/22_locale/ctype.html, docs/html/22_locale/howto.html, docs/html/22_locale/locale.html, docs/html/22_locale/messages.html, docs/html/23_containers/howto.html, docs/html/24_iterators/howto.html, docs/html/25_algorithms/howto.html, docs/html/26_numerics/howto.html, docs/html/27_io/howto.html, docs/html/ext/howto.html, docs/html/ext/sgiexts.html, docs/html/faq/index.html: Convert to XHTML. * docs/html/faq/index.txt: Regenerate. From-SVN: r56845 --- diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index f96da8b6494..2bf00f670ad 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,22 @@ +2002-09-05 Jonathan Wakely + + * docs/html/Makefile: Use more portable shell wildcard. + * docs/html/makedoc.awk: Nest elements correctly for XHTML conversion. + * docs/html/configopts.html, docs/html/documentation.html, + docs/html/explanations.html, docs/html/install.html, + docs/html/17_intro/contribute.html, docs/html/17_intro/howto.html, + docs/html/17_intro/license.html, docs/html/18_support/howto.html, + docs/html/19_diagnostics/howto.html, docs/html/20_util/howto.html, + docs/html/21_strings/howto.html, docs/html/22_locale/codecvt.html, + docs/html/22_locale/ctype.html, docs/html/22_locale/howto.html, + docs/html/22_locale/locale.html, docs/html/22_locale/messages.html, + docs/html/23_containers/howto.html, docs/html/24_iterators/howto.html, + docs/html/25_algorithms/howto.html, docs/html/26_numerics/howto.html, + docs/html/27_io/howto.html, docs/html/ext/howto.html, + docs/html/ext/sgiexts.html, docs/html/faq/index.html: Convert + to XHTML. + * docs/html/faq/index.txt: Regenerate. + 2002-09-05 Jakub Jelinek * config/locale/gnu/ctype_members.cc (ctype::do_widen(char)): diff --git a/libstdc++-v3/docs/html/17_intro/contribute.html b/libstdc++-v3/docs/html/17_intro/contribute.html index 4f16b845d48..1ab24b92fb5 100644 --- a/libstdc++-v3/docs/html/17_intro/contribute.html +++ b/libstdc++-v3/docs/html/17_intro/contribute.html @@ -1,19 +1,18 @@ - How to contribute - + + +

How to contribute

The Standard C++ Library v3, or libstc++-2.90.x, follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given write access to the CVS repository. First time submitors and all other potential contributors should follow this procedure: +

ONE : read the documentation

Get and read the relevant sections of the C++ language specification. Copies of the full ISO 14882 standard are available on @@ -27,25 +26,30 @@ and their web-site is right here. (And if you've already registered with them, clicking this link will take you to directly to the place where you can buy the standard on-line.) +
The library working group bugs, and known defects, can be obtained at these web sites: http://www.dkuug.dk/jtc1/sc22/wg21 and http://www.comeaucomputing.com/iso/ +
The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found here . +
Peruse the GNU Coding Standards, and chuckle when you hit the part about "Using Languages Other Than C." +
Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or here. +
And last but certainly not least, read the library-specific information found here. +

TWO : copyright assignment

Small changes can be accepted without a copyright assignment form on @@ -56,40 +60,43 @@ to fill out appropriate disclaimer forms as well. Here is the Benjamin Kosnik if you are confused about the assignment or have general licensing questions. +

THREE : submitting patches

Every patch must have several pieces of information before it can be properly evaluated. Ideally (and to ensure the fastest possible response from the maintainers) it would have all of these pieces: -

A description of the bug and how your patch fixes this bug. For - new features a description of the feature and your implementation. + new features a description of the feature and your implementation.
A ChangeLog entry as plaintext; see the various ChangeLog files for format and content. If using you are using emacs as your editor, simply position the insertion point at the beginning of your change and hit CX-4a to bring up the appropriate ChangeLog - entry. See--magic! Similar functionality also exists for vi. + entry. See--magic! Similar functionality also exists for vi.
A testsuite submission or sample program that will easily and - simply show the existing error or test new functionality. + simply show the existing error or test new functionality.
The patch itself. If you are accessing the CVS repository at Cygnus, use "cvs update; cvs diff -c3p NEW"; else, use "diff -c3p OLD NEW" ... If your version of diff does not support these options, then - get the latest version of GNU diff. + get the latest version of GNU diff.
When you have all these pieces, bundle them up in a mail message and send it to libstdc++@gcc.gnu.org. All patches and related -discussion should be sent to the libstdc++ mailinglist. +discussion should be sent to the libstdc++ mailinglist.

+ + diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 21f83f97e69..c3b82f56b33 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 17 - + @@ -21,18 +20,18 @@ -

The Standard C++ header files -
The Standard C++ library and multithreading -
<foo> vs <foo.h> -
Porting HOWTO -
Behavior specific to libstdc++-v3 -
Preprocessor macros controlling the library +
The Standard C++ header files
The Standard C++ library and multithreading
<foo> vs <foo.h>
Porting HOWTO
Behavior specific to libstdc++-v3
Preprocessor macros controlling the library

@@ -51,7 +50,7 @@ all compile and run.

The Standard C++ library and multithreading

This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C++ @@ -129,16 +128,17 @@ relevant message in the thread; from there you can use "Thread Next" to move down the thread. This farm is in latest-to-oldest order. +

Our threading expert Loren gives a breakdown of the - six situations involving threads for the 3.0 release series. + six situations involving threads for the 3.0 release series.
This message inspired a recent updating of issues with threading and the SGI STL library. It also contains some example - POSIX-multithreaded STL code. + POSIX-multithreaded STL code.

- (A large selection of links to older messages has been removed; many +

(A large selection of links to older messages has been removed; many of the messages from 1999 were lost in a disk crash, and the few people with access to the backup tapes have been too swamped with work to restore them. Many of the points have been superseded anyhow.) @@ -150,7 +150,7 @@ to the FAQ.

`<foo>` vs `<foo.h>`

The new-style headers are fully supported in libstdc++-v3. The compiler itself fully supports namespaces, including std::. @@ -164,16 +164,18 @@ to the FAQ.

Behavior specific to libstdc++-v3

The ISO standard defines the following phrase: +

-
[1.3.5] implementation-defined behavior +
[1.3.5] implementation-defined behavior

behavior, for a well-formed program construct and correct data, that depends on the implementation and that each implementation shall document. +

- We do so here, for the C++ library only. Behavior of the compiler, +

We do so here, for the C++ library only. Behavior of the compiler, linker, runtime loader, and other elements of "the implementation" are documented elsewhere. Everything listed in Annex B, Implemenation Qualities, are also part of the compiler, not @@ -196,10 +198,10 @@ sections, libstdc++-v3 has zero control over what the cleanup code hands back to the runtime loader. Talk to the compiler people. :-)

[18.4.2.1]/5 (bad_alloc),
- [18.5.2]/5 (bad_cast),
- [18.5.3]/5 (bad_typeid),
- [18.6.1]/8 (exception),
+

[18.4.2.1]/5 (bad_alloc),
+ [18.5.2]/5 (bad_cast),
+ [18.5.3]/5 (bad_typeid),
+ [18.6.1]/8 (exception),
[18.6.2.1]/5 (bad_exception): The what() member function of class std::exception, and these other classes publicly derived from it, simply returns the name of the @@ -225,10 +227,10 @@ have any allocators which compare non-equal, so we can't describe how they behave.

[21.1.3.1]/3,4,
- [21.1.3.2]/2,
- [23.*]'s foo::iterator,
- [27.*]'s foo::*_type,
+

[21.1.3.1]/3,4,
+ [21.1.3.2]/2,
+ [23.*]'s foo::iterator,
+ [27.*]'s foo::*_type,
others... Nope, these types are called implementation-defined because you shouldn't be taking advantage of their underlying types. Listing them @@ -257,7 +259,7 @@ than the minimum required. I don't think we're currently taking advantage of this yet.

[27.7.1.3]/16,
+

[27.7.1.3]/16,
[27.8.1.4]/10 The effects of pubsetbuf/setbuf are described in this chapter. @@ -269,7 +271,7 @@ to the FAQ.

Preprocessor macros controlling the library

Some of the semantics of the libstdc++-v3 implementation are controlled by preprocessor macros, both during build/installation and @@ -297,6 +299,7 @@ The default state of the symbol is listed. "Configurable" (or "Not configurable") means that the symbol is initially chosen (or not) based on --enable/--disable options at configure time. +

_GLIBCPP_DEPRECATED: Undefined by default. Not configurable. Turning this on enables @@ -329,7 +332,6 @@

Return to top of page or to the FAQ.

@@ -338,7 +340,7 @@ -

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/17_intro/license.html b/libstdc++-v3/docs/html/17_intro/license.html index c3449b1ff2f..7db8aa5f240 100644 --- a/libstdc++-v3/docs/html/17_intro/license.html +++ b/libstdc++-v3/docs/html/17_intro/license.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 copying - + @@ -21,7 +20,7 @@ writing this page is a programmer, not a lawyer.

-
+

The Code: Runtime GPL
@@ -29,7 +28,8 @@ GNU General Public License, with the so-called "runtime exception," as follows (or see any header or implementation file): -
+
+
As a special exception, you may use this file as part of a free software library without restriction. Specifically, if other files instantiate templates or use macros or inline functions from this file, or you compile @@ -38,8 +38,7 @@ the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. -
-
+

Hopefully that text is self-explanatory. If it isn't, you need to speak to your lawyer, or the Free Software Foundation. @@ -50,14 +49,14 @@ http://gcc.gnu.org/ml/libstdc++/2000-q2/subjects.html#00050 -->
Q: So any program which uses libstdc++ falls under the GPL? -
A: No. The special exception permits use of the +
A: No. The special exception permits use of the library in proprietary applications.

Q: How is that different from the GNU {Lesser,Library} GPL? -
A: The LGPL requires that users be able to replace the LGPL code with a +
A: The LGPL requires that users be able to replace the LGPL code with a modified version; this is trivial if the library in question is a C shared library. But there's no way to make that work with C++, where much of the library consists of inline functions and templates, which @@ -68,11 +67,11 @@
Q: I see. So, what restrictions are there on programs that use the library? -
A: None. We encourage such programs to be released as open source, +
A: None. We encourage such programs to be released as open source, but we won't punish you or sue you if you choose otherwise.
-
+

The Docs: FDL
@@ -92,7 +91,7 @@ -
+

Comments and suggestions about this page are welcome, and may be sent to the libstdc++ mailing list. diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html index 10c74a9cbff..c055f999bdc 100644 --- a/libstdc++-v3/docs/html/18_support/howto.html +++ b/libstdc++-v3/docs/html/18_support/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 18 - + @@ -24,17 +23,17 @@ -
+

Contents

-
Types -
Implementation properties -
Start and Termination -
Dynamic memory management -
RTTI, the ABI, and demangling +
Types
+
Implementation properties
+
Start and Termination
+
Dynamic memory management
+
RTTI, the ABI, and demangling

-
+
@@ -55,12 +54,13 @@ always a pointer.)

In his book - Effective C++, + Effective C++, Scott Meyers points out that the best way to solve this problem is to not overload on pointer-vs-integer types to begin with. He also offers a way to make your own magic NULL that will match pointers before it matches integers: -
+
+
const // this is a const object... class { public: @@ -77,7 +77,8 @@ // taken (see Item 27)... } NULL; // and whose name is NULL -
(Cribbed from the published version of +
+
(Cribbed from the published version of the Effective C++ CD, reproduced here with permission.)
@@ -93,7 +94,7 @@ print this stuff, it prompted him to run this code through current compilers to see what the state of the art is with respect to member template functions. He posted - an + an article to Usenet after discovering that the code above is not valid! Even though it has no data members, it still needs a user-defined constructor (which means that the class needs a type name @@ -105,14 +106,14 @@ to the FAQ.
-
+

Implementation properties
-

<limits>
- This header mainly defines traits classes to give access to various +
This header mainly defines traits classes to give access to various implementation defined-aspects of the fundamental types. The traits classes -- fourteen in total -- are all specilizations of the template class numeric_limits defined as follows: +

template<typename T> struct class { static const bool is_specialized; @@ -150,12 +151,11 @@ static const bool tinyness_before; static const float_round_style round_style; };
-

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

Start and Termination

Not many changes here to <cstdlib> (the old stdlib.h). You should note that the abort() function does not call @@ -166,11 +166,14 @@

The good old exit() function can be a bit funky, too, until you look closer. Basically, three points to remember are: +

Static objects are destroyed in reverse order of their creation. +

Functions registered with atexit() are called in reverse order of registration, once per registration call. (This isn't actually new.) +

The previous two actions are "interleaved," that is, given this pseudocode:
@@ -181,12 +184,13 @@ atexit(f1); static Thing obj2; atexit(f2); -
then at a call of exit(), f2 will be called, then + + then at a call of exit(), f2 will be called, then obj2 will be destroyed, then f1 will be called, and finally obj1 will be destroyed. If f1 or f2 allow an exception to propagate out of them, Bad Things happen. +

-

Note also that atexit() is only required to store 32 functions, and the compiler/library might already be using some of those slots. If you think you may run out, we recommend using @@ -196,21 +200,22 @@ to the FAQ.
-
+

Dynamic memory management

There are six flavors each of new and delete, so make certain that you're using the right ones! Here are quickie descriptions of new: -
-
single object form, throwing a bad_alloc on errors; - this is what most people are used to using -
single object "nothrow" form, returning NULL on errors -
array new, throwing bad_alloc on errors -
array nothrow new, returning NULL on errors -
placement new, which does nothing (like it's supposed to) -
placement array new, which also does nothing -
- They are distinguished by the parameters that you pass to them, like +
+
+
single object form, throwing a bad_alloc on errors; + this is what most people are used to using
+
single object "nothrow" form, returning NULL on errors
+
array new, throwing bad_alloc on errors
+
array nothrow new, returning NULL on errors
+
placement new, which does nothing (like it's supposed to)
+
placement array new, which also does nothing
+
+
They are distinguished by the parameters that you pass to them, like any other overloaded function. The six flavors of delete are distinguished the same way, but none of them are allowed to throw an exception under any circumstances anyhow. (They match up for @@ -225,7 +230,8 @@ bad_alloc exception (or, technically, some class derived from it). You can change this by writing your own function (called a new-handler) and then registering it with set_new_handler(): -
+
+
typedef void (*PFV)(void); static char* safety; @@ -247,8 +253,7 @@ old_handler = set_new_handler (&my_new_handler); ... } -
-
+

bad_alloc is derived from the base exception class defined in Chapter 19.
@@ -256,7 +261,7 @@ to the FAQ.
-
+

RTTI, the ABI, and demangling

If you have read the source documentation for namespace abi then you are aware @@ -271,7 +276,8 @@
Probably the only times you'll be interested in demangling at runtime are when you're seeing typeid strings in RTTI, or when you're handling the runtime-support exception classes. For example: -
+
+
#include <exception> #include <iostream> #include <cxxabi.h> @@ -304,11 +310,12 @@ int main() free(realname); return 0; -}
-
With GCC 3.1 and later, this prints
- St13bad_exception => std::bad_exception : 0 - 3barI5emptyLi17EE => bar<empty, 17> : 0
+}
+
With GCC 3.1 and later, this prints
+
+ St13bad_exception => std::bad_exception : 0 + 3barI5emptyLi17EE => bar<empty, 17> : 0

The demangler interface is described in the source documentation linked to above. It is actually written in C, so you don't need to be writing C++ in order to demangle C++. (That also means we have to @@ -322,7 +329,7 @@ int main() -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/19_diagnostics/howto.html b/libstdc++-v3/docs/html/19_diagnostics/howto.html index 3d8bf6f8bbc..07585bb8347 100644 --- a/libstdc++-v3/docs/html/19_diagnostics/howto.html +++ b/libstdc++-v3/docs/html/19_diagnostics/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 19 - + @@ -20,16 +19,16 @@ -
+

Contents

-
Adding data to exceptions -
Exception class hierarchy diagram -
Concept checkers -- new and improved! -
Verbose terminate +
Adding data to exceptions
+
Exception class hierarchy diagram
+
Concept checkers -- new and improved!
+
Verbose terminate

-
+
@@ -56,7 +55,7 @@ to the FAQ.
-
+

Exception class hierarchy diagram

At one point we were going to make up a PDF of the exceptions hierarchy, akin to the one done for the I/O class hierarchy. @@ -72,7 +71,7 @@ to the FAQ.
-
+

Concept checkers -- new and improved!

Better taste! Less fat! Literally!

In 1999, SGI added concept checkers to their implementation @@ -89,7 +88,7 @@ were found in it on more than one occasion.

The primary author of the checking code, Jeremy Siek, had already - started work on a replcement implementation. The new code has been + started work on a replacement implementation. The new code has been formally reviewed and accepted into the Boost libraries, and we are pleased to incorporate it into the @@ -109,12 +108,13 @@ to the FAQ.
-
+

Verbose terminate

If you are having difficulty with uncaught exceptions and want a little bit of help debugging the causes of the core dumps, you can make use of a GNU extension in GCC 3.1 and later: -
+
+
#include <exception> int main() @@ -123,7 +123,6 @@ ... throw anything; }
-

The __verbose_terminate_handler function obtains the name of the current exception, attempts to demangle it, and prints it to stderr. If the exception is derived from std::exception @@ -133,7 +132,8 @@ without returning; this one calls abort.

For example: -
+
+
#include <exception> #include <stdexcept> @@ -151,9 +151,9 @@ else throw argc; }
-

In GCC 3.1 and later, this gives -
+
+
% ./a.out terminate called after throwing a `int' Aborted @@ -162,7 +162,7 @@ what(): argc is greater than 5! Aborted %
- The 'Aborted' line comes from the call to abort(), of course. +
The 'Aborted' line comes from the call to abort(), of course.

Return to top of page or to the FAQ. @@ -171,7 +171,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/20_util/howto.html b/libstdc++-v3/docs/html/20_util/howto.html index b66d557f50e..7b7485ed837 100644 --- a/libstdc++-v3/docs/html/20_util/howto.html +++ b/libstdc++-v3/docs/html/20_util/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 20 - + @@ -19,16 +18,16 @@ -
+

Contents

-
auto_ptr is not omnipotent -
auto_ptr inside container classes -
Functors -
Pairs +
auto_ptr is not omnipotent
+
auto_ptr inside container classes
+
Functors
+
Pairs

-
+
@@ -47,7 +46,8 @@

AP is meant to prevent nasty leaks in the presence of exceptions. That's all. This code is AP-friendly: -
+
+
// not a recommend naming scheme, but good for web-based FAQs typedef std::auto_ptr<MyClass> APMC; @@ -62,21 +62,24 @@ function_taking_MyClass_pointer (ap.get()); } -
When an exception gets thrown, the instance of MyClass that's +
+
When an exception gets thrown, the instance of MyClass that's been created on the heap will be delete'd as the stack is unwound past func().

Changing that code as follows is not AP-friendly: -
+
+
APMC ap (new MyClass[22]); -
You will get the same problems as you would without the use +
+
You will get the same problems as you would without the use of AP: -
+
+
char* array = new char[10]; // array new... ... delete array; // ...but single-object delete -
-
+

AP cannot tell whether the pointer you've passed at creation points to one or many things. If it points to many things, you are about to die. AP is trivial to write, however, so you could write your @@ -87,18 +90,19 @@ to the FAQ.
-
+

auto_ptr inside container classes

All of the containers described in the standard library require their contained types to have, among other things, a copy constructor like this: -
+
+
struct My_Type { My_Type (My_Type const&); }; -
- Note the const keyword; the object being copied shouldn't change. +
+
Note the const keyword; the object being copied shouldn't change. The template class auto_ptr (called AP here) does not meet this requirement. Creating a new AP by copying an existing one transfers ownership of the pointed-to object, which means that @@ -113,7 +117,8 @@ concept checks built in to this implementation will issue an error if you try to compile code like this: -
+
+
#include <vector> #include <memory> @@ -121,14 +126,14 @@ { std::vector< std::auto_ptr<int> > vec_ap_int; } -
- Should you try this with the checks enabled, you will see an error. +
+
Should you try this with the checks enabled, you will see an error.

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

Functors

If you don't know what functors are, you're not alone. Many people get slightly the wrong idea. In the interest of not reinventing @@ -141,7 +146,7 @@ to the FAQ.
-
+

Pairs

The pair<T1,T2> is a simple and handy way to carry around a pair of objects. One is of type T1, and another of @@ -151,16 +156,20 @@

Construction is simple. The default ctor initializes each member with its respective default ctor. The other simple ctor, -
+
+
pair (const T1& x, const T2& y); -
does what you think it does, first getting x +
+
does what you think it does, first getting x and second getting y.

There is a copy constructor, but it requires that your compiler handle member function templates: -
+
+
template <class U, class V> pain (const pair<U,V>& p); -
The compiler will convert as necessary from U to T1 and from +
+
The compiler will convert as necessary from U to T1 and from V to T2 in order to perform the respective initializations.

The comparison operators are done for you. Equality @@ -170,24 +179,25 @@ operator== functions (for types like MyClass) or builtin comparisons (for types like int, char, etc).
- -
The less-than operator is a bit odd the first time you see it. It +
+ The less-than operator is a bit odd the first time you see it. It is defined as evaluating to: -
+ +
+
x.first < y.first || ( !(y.first < x.first) && x.second < y.second ) -
- The other operators are not defined using the rel_ops +
+
The other operators are not defined using the rel_ops functions above, but their semantics are the same.
-
Finally, there is a template function called make_pair that takes two references-to-const objects and returns an instance of a pair instantiated on their respective types: -
- pair<int,MyClass> p = make_pair(4,myobject); -

+
+ pair<int,MyClass> p = make_pair(4,myobject); +

Return to top of page or to the FAQ.
@@ -197,7 +207,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html index d25dd81bc46..e49a166c0c5 100644 --- a/libstdc++-v3/docs/html/21_strings/howto.html +++ b/libstdc++-v3/docs/html/21_strings/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 21 - + @@ -18,17 +17,17 @@ -
+

Contents

-
MFC's CString -
A case-insensitive string class -
Breaking a C++ string into tokens -
Simple transformations -
Making strings of arbitrary character types +
MFC's CString
+
A case-insensitive string class
+
Breaking a C++ string into tokens
+
Simple transformations
+
Making strings of arbitrary character types

-
+
@@ -43,24 +42,29 @@
Things are not as bad as they seem. In this message, Joe Buck points out a few very important things: +

The Standard string supports all the operations that CString does, with three exceptions. +

Two of those exceptions (whitespace trimming and case conversion) are trivial to implement. In fact, we do so on this page. +

The third is CString::Format, which allows formatting in the style of sprintf. This deserves some mention: +

-
- -
The old libg++ library had a function called form(), which did much +
+ The old libg++ library had a function called form(), which did much the same thing. But for a Standard solution, you should use the stringstream classes. These are the bridge between the iostream hierarchy and the string class, and they operate with regular streams seamlessly because they inherit from the iostream hierarchy. An quick example: -
+ +
+
#include <iostream> #include <string> #include <sstream> @@ -80,10 +84,10 @@ return output_stream.str(); }
-

A serious problem with CString is a design bug in its memory allocation. Specifically, quoting from that same message: -
+
+
CString suffers from a common programming error that results in poor performance. Consider the following code: @@ -104,22 +108,25 @@ If you replace CString with string in the above function, the performance is O(n). -
-
+

Joe Buck also pointed out some other things to keep in mind when comparing CString and the Standard string class: +

CString permits access to its internal representation; coders who exploited that may have problems moving to string. +

Microsoft ships the source to CString (in the files MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation bug and rebuild your MFC libraries. - Note: It looks like the the CString shipped with - VC++6.0 has fixed this, although it may in fact have been one - of the VC++ SPs that did it. + Note: It looks like the the CString shipped + with VC++6.0 has fixed this, although it may in fact have been + one of the VC++ SPs that did it. +

string operations like this have O(n) complexity if the implementors do it correctly. The libstdc++ implementors did it correctly. Other vendors might not. +

While parts of the SGI STL are used in libstdc++-v3, their string class is not. The SGI string is essentially vector<char> and does not do any reference @@ -129,13 +136,13 @@ libstdc++ string, the SGI string, and the SGI rope, and this is all before any allocator or traits customizations! (More choices than you can shake a stick at -- want fries with that?) +

-

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

A case-insensitive string class

The well-known-and-if-it-isn't-well-known-it-ought-to-be Guru of the Week @@ -144,7 +151,8 @@ is identical to the standard 'string' class, but is case-insensitive in the same way as the (common but nonstandard) C function stricmp():" -
+
+
ci_string s( "AbCdE" ); // case insensitive @@ -154,7 +162,6 @@ // still case-preserving, of course assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); assert( strcmp( s.c_str(), "abcde" ) != 0 );
-

The solution is surprisingly easy. The original answer pages on the GotW website were removed into cold storage, in @@ -189,7 +196,7 @@ to the FAQ.
-
+

Breaking a C++ string into tokens

The Standard C (and C++) function strtok() leaves a lot to be desired in terms of user-friendliness. It's unintuitive, it @@ -210,21 +217,23 @@ comments on what kind of string it will accept). The author uses a more general (but less readable) form of it for parsing command strings and the like. If you compiled and ran this code using it: -
+
+
std::list<string> ls; stringtok (ls, " this \t is\t\n a test "); for (std::list<string>const_iterator i = ls.begin(); i != ls.end(); ++i) { std::cerr << ':' << (*i) << ":\n"; - }
- You would see this as output: -
+ }
+
You would see this as output: +
+
:this: :is: :a: - :test:
- with all the whitespace removed. The original s is still + :test:
+
with all the whitespace removed. The original s is still available for use, ls will clean up after itself, and ls.size() will return how many tokens there were.
@@ -248,7 +257,7 @@ to the FAQ.
-
+

Simple transformations

Here are Standard, simple, and portable ways to perform common transformations on a string instance, such as "convert @@ -258,7 +267,8 @@

This code will go through some iterations (no pun). Here's the simplistic version usually seen on Usenet: -
+
+
#include <string> #include <algorithm> #include <cctype> // old <ctype.h> @@ -276,7 +286,7 @@ std::string capital_s; capital_s.reserve(s.size()); std::transform (s.begin(), s.end(), capital_s.begin(), tolower);
- Note that these calls all +
Note that these calls all involve the global C locale through the use of the C functions toupper/tolower. This is absolutely guaranteed to work -- but only if the string contains only characters @@ -287,12 +297,12 @@ characters (hahahahahaha), then you're done.

At minimum, you can write short wrappers like -
+
+
char toLower (char c) { return tolower(static_cast<unsigned char>(c)); - }
-
+ }

The correct method is to use a facet for a particular locale and call its conversion functions. These are discussed more in Chapter 22; the specific part is @@ -304,7 +314,8 @@ like transformations, this task is trivial with the use of string's find family. These examples are broken into multiple statements for readability: -
+
+
std::string str (" \t blah blah blah \n "); // trim leading whitespace @@ -314,7 +325,7 @@ // trim trailing whitespace notwhite = str.find_last_not_of(" \t\n"); str.erase(notwhite+1);
- Obviously, the calls to find could be inserted directly +
Obviously, the calls to find could be inserted directly into the calls to erase, in case your compiler does not optimize named temporaries out of existence.
@@ -322,7 +333,7 @@ to the FAQ.
-
+

Making strings of arbitrary character types

how to work with char_traits -- in the archives, just need to go through and pull the examples together @@ -335,7 +346,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/22_locale/codecvt.html b/libstdc++-v3/docs/html/22_locale/codecvt.html index a841c35fbce..64f3856d479 100644 --- a/libstdc++-v3/docs/html/22_locale/codecvt.html +++ b/libstdc++-v3/docs/html/22_locale/codecvt.html @@ -1,18 +1,21 @@ - - - Notes on the codecvt implementation. - + + + + + Notes on the codecvt implementation. +
Notes on the codecvt implementation.

- + prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000 - + +

1. Abstract @@ -33,26 +36,25 @@ wide and narrow characters and the implementation-provided extended functionality are given.
-

2. What the standard says
Around page 425 of the C++ Standard, this charming heading comes into view: -
+
22.2.1.5 - Template class codecvt [lib.locale.codecvt] -
+
The text around the codecvt definition gives some clues: -
- +
+ -1- The class codecvt<internT,externT,stateT> is for use when converting from one codeset to another, such as from wide characters to multibyte characters, between wide character encodings such as Unicode and EUC. - -
+ +

Hmm. So, in some unspecified way, Unicode encodings and @@ -60,18 +62,18 @@ translations between other character sets should be handled by this class.
-
- +
+ -2- The stateT argument selects the pair of codesets being mapped between. - -
+ +

Ah ha! Another clue...
-
- +
+ -3- The instantiations required in the Table ?? (lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and codecvt<char,char,mbstate_t>, convert the implementation-defined @@ -83,11 +85,12 @@ mbstate_t perform conversion between encodings known to the library implementor. Other encodings can be converted by specializing on a user-defined stateT type. The stateT object can contain any state that is useful to communicate to or from the specialized do_convert member. - -
+ +

At this point, a couple points become clear: +

One: The standard clearly implies that attempts to add non-required @@ -100,7 +103,6 @@ template parameter, imply an implementation strategy that is mostly (or wholly) based on the underlying C library, and the functions mcsrtombs and wcsrtombs in particular.
-

3. Some thoughts on what would be useful
@@ -121,15 +123,19 @@ represent wide characters, and use an internal encoding of UCS4. (GNU/Linux systems using glibc, in particular.) The C programming language (and thus C++) does not specify a specific size for the type wchar_t. +

Thus, portable C++ code cannot assume a byte size (or endianness) either. +

Getting back to the frequently asked question: What about Unicode strings? +

What magic spell will do this conversion? +

A couple of comments: @@ -153,12 +159,14 @@ example, using the iconv family of functions from the Single Unix Specification (what used to be called X/Open) hosted on the GNU/Linux operating system allows bi-directional mapping between far more than the following tantalizing possibilities: +

(An edited list taken from `iconv --list` on a Red Hat 6.2/Intel system: +
-
-
+
+
8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7, ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD, GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3, @@ -168,8 +176,8 @@ ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4, ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4, UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8, UTF-16, UTF8, UTF16). -
-
+
+

For iconv-based implementations, string literals for each of the @@ -177,9 +185,12 @@ encodings (ie. "UCS-2" and "UTF-8") are necessary, although for other, non-iconv implementations a table of enumerated values or some other mechanism may be required. +
+
Maximum length of the identifying string literal. +

Some encodings are require explicit endian-ness. As such, some kind @@ -187,6 +198,7 @@ mechanism may be required. "Footnotes for C/C++ developers" in Haible for more information on UCS-2/Unicode endian issues. (Summary: big endian seems most likely, however implementations, most notably Microsoft, vary.) +

Types representing the conversion state, for conversions involving @@ -194,24 +206,28 @@ mechanism may be required. conversions using iconv (such as the type iconv_t.) Note that the conversion descriptor encodes more information than a simple encoding state type. +

Conversion descriptors for both directions of encoding. (ie, both UCS-2 to UTF-8 and UTF-8 to UCS-2.) +

Something to indicate if the conversion requested if valid. +

Something to represent if the conversion descriptors are valid. +

Some way to enforce strict type checking on the internal and external types. As part of this, the size of the internal and external types will need to be known. +
-

4. Problems with "C" code conversions : thread safety, global locales, termination. @@ -224,11 +240,13 @@ when implemented using standard "C" functions.
Three problems arise, one big, one of medium importance, and one small. +

First, the small: mcsrtombs and wcsrtombs may not be multithread-safe on all systems required by the GNU tools. For GNU/Linux and glibc, this is not an issue. +

Of medium concern, in the grand scope of things, is that the functions @@ -236,6 +254,7 @@ used to implement this specialization work on null-terminated strings. Buffers, especially file buffers, may not be null-terminated, thus giving conversions that end prematurely or are otherwise incorrect. Yikes! +

The last, and fundamental problem, is the assumption of a global @@ -247,14 +266,15 @@ the GNU C++ library would like to offer a solution that allows multiple locales and or simultaneous usage with computationally correct results. In short, libstdc++-v3 is trying to offer, as an option, a high-quality implementation, damn the additional complexity! +

For the required specialization codecvt<wchar_t, char, mbstate_t> , conversions are made between the internal character set (always UCS4 on GNU/Linux) and whatever the currently selected locale for the LC_CTYPE category implements. +
-

5. Design
@@ -264,25 +284,30 @@ The two required specializations are implemented as follows: codecvt<char, char, mbstate_t> +

This is a degenerate (ie, does nothing) specialization. Implementing this was a piece of cake. +

codecvt<char, wchar_t, mbstate_t> +

This specialization, by specifying all the template parameters, pretty much ties the hands of implementors. As such, the implementation is straightforward, involving mcsrtombs for the conversions between char to wchar_t and wcsrtombs for conversions between wchar_t and char. +

Neither of these two required specializations deals with Unicode characters. As such, libstdc++-v3 implements a partial specialization of the codecvt class with and iconv wrapper class, __enc_traits as the third template parameter. +

This implementation should be standards conformant. First of all, the @@ -293,33 +318,40 @@ non-required conversions. Second of all, the standard says (in Chapter of all, the requirements for the stateT type elsewhere in the standard (see 21.1.2 traits typedefs) only indicate that this type be copy constructible. +

As such, the type __enc_traits is defined as a non-templatized, POD type to be used as the third type of a codecvt instantiation. This type is just a wrapper class for iconv, and provides an easy interface to iconv functionality. +

There are two constructors for __enc_traits: +

__enc_traits() : __in_desc(0), __out_desc(0) +

This default constructor sets the internal encoding to some default (currently UCS4) and the external encoding to whatever is returned by nl_langinfo(CODESET). +

__enc_traits(const char* __int, const char* __ext) +

This constructor takes as parameters string literals that indicate the desired internal and external encoding. There are no defaults for either argument. +

One of the issues with iconv is that the string literals identifying @@ -330,24 +362,28 @@ inducing) strategy was implemented: end-users can specify any string (subject to a pre-determined length qualifier, currently 32 bytes) for encodings. It is up to the user to make sure that these strings are valid on the target system. +

void _M_init() +

Strangely enough, this member function attempts to open conversion descriptors for a given __enc_traits object. If the conversion descriptors are not valid, the conversion descriptors returned will not be valid and the resulting calls to the codecvt conversion functions will return error. +

bool _M_good() +

Provides a way to see if the given __enc_traits object has been properly initialized. If the string literals describing the desired @@ -356,57 +392,60 @@ fail, and this will return false. If the internal and external encodings are valid, but iconv_open could not allocate conversion descriptors, this will also return false. Otherwise, the object is ready to convert and will return true. +

__enc_traits(const __enc_traits&) +

As iconv allocates memory and sets up conversion descriptors, the copy constructor can only copy the member data pertaining to the internal and external code conversions, and not the conversion descriptors themselves. +

Definitions for all the required codecvt member functions are provided for this specialization, and usage of codecvt<internal character type, external character type, __enc_traits> is consistent with other codecvt usage. +
-

6. Examples

-
- a. conversions involving string literals +
+ a. conversions involving string literals
- typedef codecvt_base::result result; - typedef unsigned short unicode_t; - typedef unicode_t int_type; - typedef char ext_type; - typedef __enc_traits enc_type; - typedef codecvt<int_type, ext_type, enc_type> unicode_codecvt; - - const ext_type* e_lit = "black pearl jasmine tea"; - int size = strlen(e_lit); - int_type i_lit_base[24] = + typedef codecvt_base::result result; + typedef unsigned short unicode_t; + typedef unicode_t int_type; + typedef char ext_type; + typedef __enc_traits enc_type; + typedef codecvt<int_type, ext_type, enc_type> unicode_codecvt; + + const ext_type* e_lit = "black pearl jasmine tea"; + int size = strlen(e_lit); + int_type i_lit_base[24] = { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, 27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696, 25856, 24832, 2560 }; - const int_type* i_lit = i_lit_base; + const int_type* i_lit = i_lit_base; const ext_type* efrom_next; const int_type* ifrom_next; - ext_type* e_arr = new ext_type[size + 1]; - ext_type* eto_next; - int_type* i_arr = new int_type[size + 1]; - int_type* ito_next; + ext_type* e_arr = new ext_type[size + 1]; + ext_type* eto_next; + int_type* i_arr = new int_type[size + 1]; + int_type* ito_next; // construct a locale object with the specialized facet. - locale loc(locale::classic(), new unicode_codecvt); + locale loc(locale::classic(), new unicode_codecvt); // sanity check the constructed locale has the specialized facet. VERIFY( has_facet<unicode_codecvt>(loc) ); const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc); @@ -414,70 +453,80 @@ codecvt usage. unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1"); initialize_state(state01); result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, - i_arr, i_arr + size, ito_next); + i_arr, i_arr + size, ito_next); VERIFY( r1 == codecvt_base::ok ); VERIFY( !int_traits::compare(i_arr, i_lit, size) ); VERIFY( efrom_next == e_lit + size ); VERIFY( ito_next == i_arr + size );
-
- b. conversions involving std::string -
- c. conversions involving std::filebuf and std::ostream +
+
+ b. conversions involving std::string +
+
+ c. conversions involving std::filebuf and std::ostream +

More information can be found in the following testcases:
-
testsuite/22_locale/codecvt_char_char.cc -
testsuite/22_locale/codecvt_unicode_wchar_t.cc -
testsuite/22_locale/codecvt_unicode_char.cc -
testsuite/22_locale/codecvt_wchar_t_char.cc +
testsuite/22_locale/codecvt_char_char.cc
+
testsuite/22_locale/codecvt_unicode_wchar_t.cc
+
testsuite/22_locale/codecvt_unicode_char.cc
+
testsuite/22_locale/codecvt_wchar_t_char.cc

-

7. Unresolved Issues

- a. things that are sketchy, or remain unimplemented: - do_encoding, max_length and length member functions - are only weakly implemented. I have no idea how to do - this correctly, and in a generic manner. Nathan? + a. things that are sketchy, or remain unimplemented: + do_encoding, max_length and length member functions + are only weakly implemented. I have no idea how to do + this correctly, and in a generic manner. Nathan? +

- b. conversions involving std::string - -
-
- how should operators != and == work for string of - different/same encoding? - -
- what is equal? A byte by byte comparison or an - encoding then byte comparison? - -
- conversions between narrow, wide, and unicode strings -
+ b. conversions involving std::string + +
+
+ how should operators != and == work for string of + different/same encoding? +
+ +
+ what is equal? A byte by byte comparison or an + encoding then byte comparison? +
+ +
+ conversions between narrow, wide, and unicode strings +
+
+

- c. conversions involving std::filebuf and std::ostream -
-
- how to initialize the state object in a - standards-conformant manner? - -
- how to synchronize the "C" and "C++" - conversion information? - -
- wchar_t/char internal buffers and conversions between - internal/external buffers? -
+ c. conversions involving std::filebuf and std::ostream +
+
+ how to initialize the state object in a + standards-conformant manner? +
+ +
+ how to synchronize the "C" and "C++" + conversion information? +
+ +
+ wchar_t/char internal buffers and conversions between + internal/external buffers? +
+
+

-

8. Acknowledgments
@@ -485,7 +534,6 @@ Ulrich Drepper for the iconv suggestions and patient answering of late-night questions, Jason Merrill for the template partial specialization hints, language clarification, and wchar_t fixes. -

9. Bibliography / Referenced Documents
@@ -494,35 +542,44 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C
Drepper, Ulrich, Numerous, late-night email correspondence +

Feather, Clive, "A brief description of Normative Addendum 1," in particular the parts on Extended Character Sets http://www.lysator.liu.se/c/na1.html +

Haible, Bruno, "The Unicode HOWTO" v0.18, 4 August 2000 ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html +

ISO/IEC 14882:1998 Programming languages - C++ +

ISO/IEC 9899:1999 Programming languages - C +

Khun, Markus, "UTF-8 and Unicode FAQ for Unix/Linux" http://www.cl.cam.ac.uk/~mgk25/unicode.html +

Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +

Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +

System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +
diff --git a/libstdc++-v3/docs/html/22_locale/ctype.html b/libstdc++-v3/docs/html/22_locale/ctype.html index a47d9f81ef0..886f83d0739 100644 --- a/libstdc++-v3/docs/html/22_locale/ctype.html +++ b/libstdc++-v3/docs/html/22_locale/ctype.html @@ -1,19 +1,20 @@ - - - Notes on the ctype implementation. - + + + + + Notes on the ctype implementation. +
Notes on the ctype implementation.
- + prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000 - + -

1. Abstract
@@ -21,13 +22,11 @@ prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000 Woe is me.
-

2. What the standard says
-

3. Problems with "C" ctype : global locales, termination.
@@ -37,8 +36,8 @@ For the required specialization codecvt<wchar_t, char, mbstate_t> , conversions are made between the internal character set (always UCS4 on GNU/Linux) and whatever the currently selected locale for the LC_CTYPE category implements. +
-

4. Design
@@ -48,24 +47,28 @@ The two required specializations are implemented as follows: ctype<char> +

This is simple specialization. Implementing this was a piece of cake. +

ctype<wchar_t> +

This specialization, by specifying all the template parameters, pretty much ties the hands of implementors. As such, the implementation is straightforward, involving mcsrtombs for the conversions between char to wchar_t and wcsrtombs for conversions between wchar_t and char. +

Neither of these two required specializations deals with Unicode characters. As such, libstdc++-v3 implements +
-

5. Examples
@@ -76,50 +79,47 @@ characters. As such, libstdc++-v3 implements More information can be found in the following testcases:
-
testsuite/22_locale/ctype_char_members.cc -
testsuite/22_locale/ctype_wchar_t_members.cc +
testsuite/22_locale/ctype_char_members.cc
+
testsuite/22_locale/ctype_wchar_t_members.cc

-

6. Unresolved Issues

-
how to deal with the global locale issue? +
how to deal with the global locale issue?
-
how to deal with different types than char, wchar_t? +
how to deal with different types than char, wchar_t?
-
codecvt/ctype overlap: narrow/widen +
codecvt/ctype overlap: narrow/widen
-
mask typedef in codecvt_base, argument types in codecvt. - what is know about this type? +
mask typedef in codecvt_base, argument types in codecvt. + what is know about this type?
-
why mask* argument in codecvt? - -
can this be made (more) generic? is there a simple way to - straighten out the configure-time mess that is a by-product of - this class? +
why mask* argument in codecvt?
+ +
can this be made (more) generic? is there a simple way to + straighten out the configure-time mess that is a by-product of + this class?
-
get the ctype<wchar_t>::mask stuff under control. Need to - make some kind of static table, and not do lookup evertime - somebody hits the do_is... functions. Too bad we can't just - redefine mask for ctype<wchar_t> - -
rename abstract base class. See if just smash-overriding - is a better approach. Clarify, add sanity to naming. +
get the ctype<wchar_t>::mask stuff under control. Need to + make some kind of static table, and not do lookup evertime + somebody hits the do_is... functions. Too bad we can't just + redefine mask for ctype<wchar_t>
+ +
rename abstract base class. See if just smash-overriding + is a better approach. Clarify, add sanity to naming.

-

7. Acknowledgments
Ulrich Drepper for patient answering of late-night questions, skeletal examples, and C language expertise. -

8. Bibliography / Referenced Documents
@@ -128,23 +128,29 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C
Drepper, Ulrich, Numerous, late-night email correspondence +

ISO/IEC 14882:1998 Programming languages - C++ +

ISO/IEC 9899:1999 Programming languages - C +

Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +

Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +

System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +
diff --git a/libstdc++-v3/docs/html/22_locale/howto.html b/libstdc++-v3/docs/html/22_locale/howto.html index b8fe45d1e59..106662753d9 100644 --- a/libstdc++-v3/docs/html/22_locale/howto.html +++ b/libstdc++-v3/docs/html/22_locale/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 22 - + @@ -16,33 +15,33 @@
Chapter 22 deals with the C++ localization facilities.
-
+

Contents

-
class locale -
class codecvt -
class ctype -
class messages -
Bjarne Stroustrup on Locales -
Nathan Myers on Locales -
Correct Transformations +
class locale
+
class codecvt
+
class ctype
+
class messages
+
Bjarne Stroustrup on Locales
+
Nathan Myers on Locales
+
Correct Transformations

-
+

class locale

Notes made during the implementation of locales can be found here.
-
+

class codecvt

Notes made during the implementation of codecvt can be found here. @@ -66,19 +65,19 @@ implementation-provided extended functionality are given. -
+

class ctype

Notes made during the implementation of ctype can be found here.
-
+

class messages

Notes made during the implementation of messages can be found here.
-
+

Stroustrup on Locales

Dr. Bjarne Stroustrup has released a pointer @@ -96,14 +95,14 @@ avoid it. -
+

Nathan Myers on Locales

An article entitled "The Standard C++ Locale" was published in Dr. Dobb's Journal and can be found here.
-
+

Correct Transformations

A very common question on newsgroups and mailing lists is, "How @@ -207,7 +206,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/22_locale/locale.html b/libstdc++-v3/docs/html/22_locale/locale.html index 630f59986f1..999e82ed0bd 100644 --- a/libstdc++-v3/docs/html/22_locale/locale.html +++ b/libstdc++-v3/docs/html/22_locale/locale.html @@ -1,19 +1,20 @@ - - - Notes on the locale implementation. - + + + + + Notes on the locale implementation. +
Notes on the locale implementation.
- + prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 - + -

1. Abstract Describes the basic locale object, including nested classes id, facet, and the reference-counted implementation object, @@ -22,14 +23,12 @@ class _Impl.

-

2. What the standard says -See Chapter 22 of the standard.
+See Chapter 22 of the standard. -

3. Problems with "C" locales : global locales, termination.
@@ -40,7 +39,7 @@ design ontop of POSIX and other relevant stanards, which include the Single Unix (nee X/Open.) Because POSIX falls down so completely, portibility is an issue. -
+

4. Design @@ -74,7 +73,6 @@ Provides an index for looking up specific facets. class _Impl -

5. Examples
@@ -85,43 +83,40 @@ class _Impl More information can be found in the following testcases:
-
testsuite/22_locale/ctype_char_members.cc -
testsuite/22_locale/ctype_wchar_t_members.cc +
testsuite/22_locale/ctype_char_members.cc
+
testsuite/22_locale/ctype_wchar_t_members.cc

-

6. Unresolved Issues

-
locale -a displays available locales on linux +
locale -a displays available locales on linux
-
locale initialization: at what point does _S_classic, - _S_global get initialized? Can named locales assume this - initialization has already taken place? +
locale initialization: at what point does _S_classic, + _S_global get initialized? Can named locales assume this + initialization has already taken place?
-
document how named locales error check when filling data - members. Ie, a fr_FR locale that doesn't have - numpunct::truename(): does it use "true"? Or is it a blank - string? What's the convention? +
document how named locales error check when filling data + members. Ie, a fr_FR locale that doesn't have + numpunct::truename(): does it use "true"? Or is it a blank + string? What's the convention?
-
explain how locale aliasing happens. When does "de_DE" - use "de" information? What is the rule for locales composed of - just an ISO language code (say, "de") and locales with both an - ISO language code and ISO country code (say, "de_DE"). +
explain how locale aliasing happens. When does "de_DE" + use "de" information? What is the rule for locales composed of + just an ISO language code (say, "de") and locales with both an + ISO language code and ISO country code (say, "de_DE").
-
what should non-required facet instantiations do? If the - generic implemenation is provided, then how to end-users - provide specializations? +
what should non-required facet instantiations do? If the + generic implemenation is provided, then how to end-users + provide specializations?

-

7. Acknowledgments
-

8. Bibliography / Referenced Documents
@@ -130,20 +125,31 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C
Drepper, Ulrich, Numerous, late-night email correspondence +

ISO/IEC 14882:1998 Programming languages - C++ +

ISO/IEC 9899:1999 Programming languages - C +

Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +

Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +

System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +
+ + + + + diff --git a/libstdc++-v3/docs/html/22_locale/messages.html b/libstdc++-v3/docs/html/22_locale/messages.html index 39ee9cfbee7..7497590bd88 100644 --- a/libstdc++-v3/docs/html/22_locale/messages.html +++ b/libstdc++-v3/docs/html/22_locale/messages.html @@ -1,19 +1,20 @@ - - - Notes on the messages implementation. - + + + + + Notes on the messages implementation. +
Notes on the messages implementation.
- + prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 - + -

1. Abstract
@@ -23,7 +24,6 @@ equivalent to Java's java.text.MessageFormat .using either GNU gettext or IEEE 1003.1-200 functions.
-

2. What the standard says
@@ -34,9 +34,9 @@ locale to the other. For instance, converting the "C" locale's const char* c = "please" to a German-localized "bitte" during program execution. -
+
22.2.7.1 - Template class messages [lib.locale.messages] -
+
This class has three public member functions, which directly correspond to three protected virtual member functions. @@ -45,51 +45,57 @@ The public member functions are:
catalog open(const string&, const locale&) const +

string_type get(catalog, int, int, const string_type&) const +

void close(catalog) const +

While the virtual functions are: +

catalog do_open(const string&, const locale&) const -
- +
+
+ -1- Returns: A value that may be passed to get() to retrieve a message, from the message catalog identified by the string name according to an implementation-defined mapping. The result can be used until it is passed to close(). Returns a value less than 0 if no such catalog can be opened. - -
+ +

string_type do_get(catalog, int, int, const string_type&) const -
- +
+
+ -3- Requires: A catalog cat obtained from open() and not yet closed. -4- Returns: A message identified by arguments set, msgid, and dfault, according to an implementation-defined mapping. If no such message can be found, returns dfault. - -
+ +

void do_close(catalog) const -
- +
+
+ -5- Requires: A catalog cat obtained from open() and not yet closed. -6- Effects: Releases unspecified resources associated with cat. -7- Notes: The limit on such resources, if any, is implementation-defined. - -
+ +
-

3. Problems with "C" messages: thread safety, over-specification, and assumptions. @@ -101,12 +107,14 @@ First, why is messages_base::catalog specified as a typedef to int? This makes sense for implementations that use catopen, but not for others. Fortunately, it's not heavily used and so only a minor irritant. +

Second, by making the member functions const, it is impossible to save state in them. Thus, storing away information used in the 'open' member function for use in 'get' is impossible. This is unfortunate. +

The 'open' member function in particular seems to be oddly @@ -118,20 +126,22 @@ argument useful? What was the intent? It might make sense if a locale argument was associated with a given default message string in the 'open' member function, for instance. Quite murky and unclear, on reflection. +

Lastly, it seems odd that messages, which explicitly require code conversion, don't use the codecvt facet. Because the messages facet has only one template parameter, it is assumed that ctype, and not codecvt, is to be used to convert between character sets. +

It is implicitly assumed that the locale for the default message string in 'get' is in the "C" locale. Thus, all source code is assumed to be written in English, so translations are always from "en_US" to other, explicitly named locales. +
-

4. Design and Implementation Details
@@ -145,35 +155,39 @@ dependent on the capabilities of the underlying operating system.
Three different mechanisms have been provided, selectable via configure flags: +

-
generic -
- This model does very little, and is what is used by default. -
- -
gnu -
- The gnu model is complete and fully tested. It's based on the - GNU gettext package, which is part of glibc. It uses the functions - textdomain, bindtextdomain, gettext - to implement full functionality. Creating message - catalogs is a relatively straight-forward process and is - lightly documented below, and fully documented in gettext's - distributed documentation. -
- -
ieee_1003.1-200x -
- This is a complete, though untested, implementation based on - the IEEE standard. The functions - catopen, catgets, catclose - are used to retrieve locale-specific messages given the - appropriate message catalogs that have been constructed for - their use. Note, the script po2msg.sed that is part - of the gettext distribution can convert gettext catalogs into - catalogs that catopen can use. -
+
generic +
+ This model does very little, and is what is used by default. +
+
+ +
gnu +
+ The gnu model is complete and fully tested. It's based on the + GNU gettext package, which is part of glibc. It uses the functions + textdomain, bindtextdomain, gettext + to implement full functionality. Creating message + catalogs is a relatively straight-forward process and is + lightly documented below, and fully documented in gettext's + distributed documentation. +
+
+ +
ieee_1003.1-200x +
+ This is a complete, though untested, implementation based on + the IEEE standard. The functions + catopen, catgets, catclose + are used to retrieve locale-specific messages given the + appropriate message catalogs that have been constructed for + their use. Note, the script po2msg.sed that is part + of the gettext distribution can convert gettext catalogs into + catalogs that catopen can use. +
+

@@ -181,9 +195,11 @@ A new, standards-conformant non-virtual member function signature was added for 'open' so that a directory could be specified with a given message catalog. This simplifies calling conventions for the gnu model. +

The rest of this document discusses details of the GNU model. +

The messages facet, because it is retrieving and converting between @@ -193,67 +209,79 @@ necessary for more than just the LC_MESSAGES mask: LC_CTYPE is also necessary. To avoid any unpleasantness, all bits of the "C" mask (ie LC_ALL) are set before retrieving messages. +

Making the message catalogs can be initially tricky, but become quite simple with practice. For complete info, see the gettext documentation. Here's an idea of what is required: +

-
Make a source file with the required string literals - that need to be translated. See - intl/string_literals.cc for an example. - -
-
Make initial catalog (see "4 Making the PO Template File" - from the gettext docs). -
- xgettext --c++ --debug string_literals.cc -o libstdc++.pot - -
-
Make language and country-specific locale catalogs. -
- cp libstdc++.pot fr_FR.po -
- cp libstdc++.pot de_DE.po - -
-
Edit localized catalogs in emacs so that strings are - translated. -
- emacs fr_FR.po - -
-
Make the binary mo files. -
- msgfmt fr_FR.po -o fr_FR.mo -
- msgfmt de_DE.po -o de_DE.mo - -
-
Copy the binary files into the correct directory structure. -
- cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo -
- cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo - -
-
Use the new message catalogs. -
- locale loc_de("de_DE"); -
- - use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); - +
Make a source file with the required string literals + that need to be translated. See + intl/string_literals.cc for an example. +
+ +
Make initial catalog (see "4 Making the PO Template File" + from the gettext docs). +
+ xgettext --c++ --debug string_literals.cc -o libstdc++.pot +
+
+ +
Make language and country-specific locale catalogs. +
+ cp libstdc++.pot fr_FR.po +
+
+ cp libstdc++.pot de_DE.po +
+
+ +
Edit localized catalogs in emacs so that strings are + translated. +
+ emacs fr_FR.po +
+
+ +
Make the binary mo files. +
+ msgfmt fr_FR.po -o fr_FR.mo +
+
+ msgfmt de_DE.po -o de_DE.mo +
+
+ +
Copy the binary files into the correct directory structure. +
+ cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo +
+
+ cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo +
+
+ +
Use the new message catalogs. +
+ locale loc_de("de_DE"); +
+
+ + use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); + +
+

-

5. Examples

-
message converting, simple example using the GNU model. +
message converting, simple example using the GNU model.
#include <iostream> @@ -276,82 +304,87 @@ void test01() mssg_de.close(cat_de); }
+

More information can be found in the following testcases:
-
testsuite/22_locale/messages.cc -
testsuite/22_locale/messages_byname.cc -
testsuite/22_locale/messages_char_members.cc +
testsuite/22_locale/messages.cc
+
testsuite/22_locale/messages_byname.cc
+
testsuite/22_locale/messages_char_members.cc

-

6. Unresolved Issues

-
Things that are sketchy, or remain unimplemented: -
-
_M_convert_from_char, _M_convert_to_char are in - flux, depending on how the library ends up doing - character set conversions. It might not be possible to - do a real character set based conversion, due to the - fact that the template parameter for messages is not - enough to instantiate the codecvt facet (1 supplied, - need at least 2 but would prefer 3). - -
There are issues with gettext needing the global - locale set to extract a message. This dependence on - the global locale makes the current "gnu" model non - MT-safe. Future versions of glibc, ie glibc 2.3.x will - fix this, and the C++ library bits are already in - place. -
- -
-
Development versions of the GNU "C" library, glibc 2.3 will allow - a more efficient, MT implementation of std::messages, and will - allow the removal of the _M_name_messages data member. If this - is done, it will change the library ABI. The C++ parts to - support glibc 2.3 have already been coded, but are not in use: - once this version of the "C" library is released, the marked - parts of the messages implementation can be switched over to - the new "C" library functionality. -
+
Things that are sketchy, or remain unimplemented: +
+
_M_convert_from_char, _M_convert_to_char are in + flux, depending on how the library ends up doing + character set conversions. It might not be possible to + do a real character set based conversion, due to the + fact that the template parameter for messages is not + enough to instantiate the codecvt facet (1 supplied, + need at least 2 but would prefer 3). +
+ +
There are issues with gettext needing the global + locale set to extract a message. This dependence on + the global locale makes the current "gnu" model non + MT-safe. Future versions of glibc, ie glibc 2.3.x will + fix this, and the C++ library bits are already in + place. +
+
+
+ +
Development versions of the GNU "C" library, glibc 2.3 will allow + a more efficient, MT implementation of std::messages, and will + allow the removal of the _M_name_messages data member. If this + is done, it will change the library ABI. The C++ parts to + support glibc 2.3 have already been coded, but are not in use: + once this version of the "C" library is released, the marked + parts of the messages implementation can be switched over to + the new "C" library functionality. +

At some point in the near future, std::numpunct will probably use - std::messages facilities to implement truename/falename - correctly. This is currently not done, but entries in - libstdc++.pot have already been made for "true" and "false" - string literals, so all that remains is the std::numpunct - coding and the configure/make hassles to make the installed - library search its own catalog. Currently the libstdc++.mo - catalog is only searched for the testsuite cases involving - messages members. - -
-
The following member functions: - -
- + std::messages facilities to implement truename/falename + correctly. This is currently not done, but entries in + libstdc++.pot have already been made for "true" and "false" + string literals, so all that remains is the std::numpunct + coding and the configure/make hassles to make the installed + library search its own catalog. Currently the libstdc++.mo + catalog is only searched for the testsuite cases involving + messages members. +
+ +
The following member functions: + + + catalog open(const basic_string<char>& __s, const locale& __loc) const - - - - - catalog - open(const basic_string<char>&, const locale&, const char*) const; - - -
- Don't actually return a "value less than 0 if no such catalog - can be opened" as required by the standard in the "gnu" - model. As of this writing, it is unknown how to query to see - if a specified message catalog exists using the gettext - package. + +
+ +
+ + catalog + open(const basic_string<char>&, const locale&, const char*) const; + +
+ +
+ Don't actually return a "value less than 0 if no such catalog + can be opened" as required by the standard in the "gnu" + model. As of this writing, it is unknown how to query to see + if a specified message catalog exists using the gettext + package. +
+

-

7. Acknowledgments
@@ -359,7 +392,6 @@ Ulrich Drepper for the character set explanations, gettext details, and patient answering of late-night questions, Tom Tromey for the java details. -

8. Bibliography / Referenced Documents
@@ -371,36 +403,49 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters Drepper, Ulrich, Thread-Aware Locale Model, A proposal. This is a draft document describing the design of glibc 2.3 MT locale functionality. +

Drepper, Ulrich, Numerous, late-night email correspondence +

ISO/IEC 9899:1999 Programming languages - C +

ISO/IEC 14882:1998 Programming languages - C++ +

Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In particular, java.util.Properties, java.text.MessageFormat, java.util.Locale, java.util.ResourceBundle. http://java.sun.com/j2se/1.3/docs/api +

System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. In particular see lines 5268-5427. http://www.opennc.org/austin/docreg.html +

GNU gettext tools, version 0.10.38, Native Language Support Library and Tools. http://sources.redhat.com/gettext +

Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000. See page 725, Internationalized Messages. +

Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +
+ + + + diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index a64d79c75ae..1c1e137b67c 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 23 - + @@ -18,19 +17,19 @@ -
+

Contents

-
Making code unaware of the container/array difference -
Variable-sized bitmasks -
Containers and multithreading -
"Hinting" during insertion -
Bitmasks and string arguments -
std::list::size() is O(n)! -
Space overhead management for vectors +
Making code unaware of the container/array difference
+
Variable-sized bitmasks
+
Containers and multithreading
+
"Hinting" during insertion
+
Bitmasks and string arguments
+
std::list::size() is O(n)!
+
Space overhead management for vectors

-
+
@@ -65,9 +64,10 @@ code size or execution time.

The result is that if all your algorithm calls look like -
+
+
std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);
- then the type of foo can change from an array of ints to a vector +
then the type of foo can change from an array of ints to a vector of ints to a deque of ints and back again, without ever changing any client code.
@@ -86,19 +86,21 @@ give the extra three lines and avoid confusion.

Second, the line -
+
+
inline unsigned int lengthof (T (&)[sz]) { return sz; }
- looks just weird! Hint: unused parameters can be left nameless. +
looks just weird! Hint: unused parameters can be left nameless.

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

Variable-sized bitmasks

No, you cannot write code of the form +
-
+
#include <bitset> void foo (size_t n) @@ -106,19 +108,19 @@ std::bitset<n> bits; .... }
- because n must be known at compile time. Your compiler is +
because n must be known at compile time. Your compiler is correct; it is not a bug. That's the way templates work. (Yes, it is a feature.)

There are a couple of ways to handle this kind of thing. Please consider all of them before passing judgement. They include, in no particular order: +

-
A very large N in bitset<N>. -
A container<bool>. -
Extremely weird solutions. +
A very large N in bitset<N>.
+
A container<bool>.
+
Extremely weird solutions.

-

A very large N in bitset<N>. It has been pointed out a few times in newsgroups that N bits only takes up @@ -192,7 +194,7 @@ to the FAQ.
-
+

Containers and multithreading

This section discusses issues surrounding the design of multithreaded applications which use Standard C++ containers. @@ -204,14 +206,14 @@ multithreading as it relates to libstdc++, including details on the proper compilation of threaded code (and compatibility between threaded and non-threaded code), see Chapter 17. -
+

Two excellent pages to read when working with the Standard C++ containers and threads are SGI's http://www.sgi.com/tech/stl/thread_safety.html and SGI's http://www.sgi.com/tech/stl/Allocators.html. -
+

However, please ignore all discussions about the user-level configuration of the lock implementation inside the STL container-memory allocator on those pages. For the sake of this @@ -223,7 +225,7 @@ STL. This is no longer required for any port and should no longer be done unless you really know what you are doing and assume all responsibility. -
+

Since the container implementation of libstdc++-v3 uses the SGI code, we use the same definition of thread safety as SGI when discussing design. A key point that beginners may miss is the @@ -235,7 +237,7 @@ element is constructed uses an internal lock obtained and released solely within libstdc++-v3 code (in fact, this is the reason STL requires any knowledge of the thread configuration). -
+

For implementing a container which does its own locking, it is trivial to provide a wrapper class which obtains the lock (as SGI suggests), performs the container operation, and then @@ -249,7 +251,8 @@ you must change this on a global basis for your platform to better support multi-threading, then please consult all commentary in include/bits/stl_alloc.h and the allocators link below. -
+
+

(Explicit warning since so many people get confused while attempting this:)
@@ -271,8 +274,8 @@ one-definition rule of C/C++ and you might cause yourself untold problems.
-
- If you find any platform where gcc reports a +
+
If you find any platform where gcc reports a threading model other than single, and where libstdc++-v3 builds a buggy container allocator when used with threads unless you define __USE_MALLOC, we want to hear about it ASAP. In the @@ -290,13 +293,14 @@ to the FAQ.
-
+

"Hinting" during insertion

Section [23.1.2], Table 69, of the C++ standard lists this function for all of the associative containers (map, set, etc): -
+
+
a.insert(p,t);
- where 'p' is an iterator into the container 'a', and 't' is the item +
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, @@ -321,23 +325,26 @@ their new meanings in the next paragraph. *grin*

If the hint parameter ('p' above) is equivalent to: +

begin(), then the item being inserted should have a key less than all the other keys in the container. The item will be inserted at the beginning of the container, becoming the new entry at begin(). +

end(), then the item being inserted should have a key greater than all the other keys in the container. The item will be inserted at the end of the container, becoming the new entry at end(). +

neither begin() nor end(), then: Let h be the entry in the container pointed to by hint, that is, h = *hint. Then the item being inserted should have a key less than that of h, and greater than that of the item preceding h. The new item will be inserted between h and h's predecessor. +

-

For multimap and multiset, the restrictions are slightly looser: "greater than" should be replaced by "not less than" and "less than" should be replaced @@ -372,7 +379,7 @@ to the FAQ.
-
+

Bitmasks and string arguments

Bitmasks do not take char* nor const char* arguments in their constructors. This is something of an accident, but you can read @@ -383,6 +390,7 @@

For now you can simply make a temporary string object using the constructor expression: +

std::bitset<5> b ( std::string("10110") );
@@ -390,17 +398,17 @@
std::bitset<5> b ( "10110" ); // invalid
-

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

std::list::size() is O(n)!

Yes it is, and that's okay. This is a decision that we preserved when we imported SGI's STL implementation. The following is quoted from their FAQ: -
+
+

The size() member function, for list and slist, takes time proportional to the number of elements in the list. This was a deliberate tradeoff. The only way to get a constant-time size() for @@ -419,6 +427,7 @@ is supposed to do something unless there is a good reason not to.

One implication of linear time size(): you should never write +

if (L.size() == 0) ...
@@ -426,15 +435,13 @@
if (L.empty()) ...
-
-
-
+

Return to top of page or to the FAQ.
-
-
Space overhead management for vectors
+
+
Space overhead management for vectors

In this message to the list, Daniel Kostecky announced work on an @@ -457,7 +464,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/24_iterators/howto.html b/libstdc++-v3/docs/html/24_iterators/howto.html index 90c53df18ac..4d48cffdcbd 100644 --- a/libstdc++-v3/docs/html/24_iterators/howto.html +++ b/libstdc++-v3/docs/html/24_iterators/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 24 - + @@ -19,14 +18,14 @@ -
+

Contents

-
They ain't pointers! -
It ends where? +
They ain't pointers!
+
It ends where?

-
+
@@ -67,41 +66,46 @@ to the FAQ.
-
+

It ends where?

This starts off sounding complicated, but is actually very easy, especially towards the end. Trust me. -
+

Beginners usually have a little trouble understand the whole 'past-the-end' thing, until they remember their early algebra classes - (see, they told you that stuff would come in handy!) and + (see, they told you that stuff would come in handy!) and the concept of half-open ranges.

First, some history, and a reminder of some of the funkier rules in C and C++ for builtin arrays. The following rules have always been true for both languages: -
-
You can point anywhere in the array, or to the first element - past the end of the array. A pointer that points to one - past the end of the array is guaranteed to be as unique as a - pointer to somewhere inside the array, so that you can compare - such pointers safely. -
You can only dereference a pointer that points into an array. - If your array pointer points outside the array -- even to just - one past the end -- and you dereference it, Bad Things happen. -
Strictly speaking, simply pointing anywhere else invokes - undefined behavior. Most programs won't puke until such a - pointer is actually dereferenced, but the standards leave that - up to the platform. -
- The reason this past-the-end addressing was allowed is to make it +
+
+
You can point anywhere in the array, or to the first element + past the end of the array. A pointer that points to one + past the end of the array is guaranteed to be as unique as a + pointer to somewhere inside the array, so that you can compare + such pointers safely. +
+
You can only dereference a pointer that points into an array. + If your array pointer points outside the array -- even to just + one past the end -- and you dereference it, Bad Things happen. +
+
Strictly speaking, simply pointing anywhere else invokes + undefined behavior. Most programs won't puke until such a + pointer is actually dereferenced, but the standards leave that + up to the platform. +
+
+
The reason this past-the-end addressing was allowed is to make it easy to write a loop to go over an entire array, e.g., while (*d++ = *s++);.

So, when you think of two pointers delimiting an array, don't think of them as indexing 0 through n-1. Think of them as boundary markers: -
+
+
beginning end | | @@ -121,8 +125,8 @@ | | dereference 'end'. beginning end -
- See? Everything between the boundary markers is part of the array. +
+
See? Everything between the boundary markers is part of the array. Simple.

Now think back to your junior-high school algebra course, when you @@ -171,7 +175,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/25_algorithms/howto.html b/libstdc++-v3/docs/html/25_algorithms/howto.html index 8cdfe94a471..65403ca8159 100644 --- a/libstdc++-v3/docs/html/25_algorithms/howto.html +++ b/libstdc++-v3/docs/html/25_algorithms/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 25 - + @@ -19,14 +18,14 @@ -
+

Contents

-
Prerequisites -
Special swaps +
Prerequisites
+
Special swaps

-
+
@@ -34,16 +33,18 @@
The neatest accomplishment of the algorithms chapter is that all the work is done via iterators, not containers directly. This means two important things: -
-
Anything that behaves like an iterator can be used in one of - these algorithms. Raw pointers make great candidates, thus - built-in arrays are fine containers, as well as your own iterators. -
The algorithms do not (and cannot) affect the container as a - whole; only the things between the two iterator endpoints. If - you pass a range of iterators only enclosing the middle third of - a container, then anything outside that range is inviolate. -

+
+
Anything that behaves like an iterator can be used in one of + these algorithms. Raw pointers make great candidates, thus + built-in arrays are fine containers, as well as your own iterators. +
+
The algorithms do not (and cannot) affect the container as a + whole; only the things between the two iterator endpoints. If + you pass a range of iterators only enclosing the middle third of + a container, then anything outside that range is inviolate. +
+

Even strings can be fed through the algorithms here, although the string class has specialized versions of many of these functions (for example, string::find()). Most of the examples on this @@ -67,7 +68,7 @@ to the FAQ.
-
+

Special swaps

If you call std::swap(x,y); where x and y are standard containers, then the call will automatically be replaced by a call to @@ -90,7 +91,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/26_numerics/howto.html b/libstdc++-v3/docs/html/26_numerics/howto.html index e15870f57bf..067f59dd0fd 100644 --- a/libstdc++-v3/docs/html/26_numerics/howto.html +++ b/libstdc++-v3/docs/html/26_numerics/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 26 - + @@ -15,29 +14,32 @@
Chapter 26 deals with building block abstractions to aid in numerical computing: -
-
Template data structures such as valarray<> - and complex<>. -
Template numerical functions such as accumulate, - inner_product, partial_sum, and - adjacent_difference. -
- All of the Standard C math functions are of course included in C++, +
+
+
Template data structures such as valarray<> + and complex<>. +
+
Template numerical functions such as accumulate, + inner_product, partial_sum, and + adjacent_difference. +
+
+
All of the Standard C math functions are of course included in C++, and overloaded versions for long, float, and long double have been added for all of them.
-
+

Contents

-
Complex Number Processing -
Array Processing -
Numerical Functions -
C99 +
Complex Number Processing
+
Array Processing
+
Numerical Functions
+
C99

-
+
@@ -62,7 +64,7 @@ to the FAQ.
-
+

Array Processing

One of the major reasons why FORTRAN can chew through numbers so well is that it is defined to be free of pointer aliasing, an assumption @@ -87,22 +89,23 @@ to the FAQ.
-
+

Numerical Functions

There are four generalized functions in the <numeric> header that follow the same conventions as those in <algorithm>. Each of them is overloaded: one signature for common default operations, and a second for fully general operations. Their names are self-explanatory to anyone who works with numerics on a regular basis: -
-
accumulate -
inner_product -
partial_sum -
adjacent_difference -

+
+
accumulate
+
inner_product
+
partial_sum
+
adjacent_difference
+

Here is a simple example of the two forms of accumulate. -
+
+
int ar[50]; int someval = somefunction(); @@ -111,8 +114,8 @@ int sum = std::accumulate(ar,ar+50,0); int sum_stuff = std::accumulate(ar,ar+50,someval); int product = std::accumulate(ar,ar+50,1,std::multiplies<int>()); -
- The first call adds all the members of the array, using zero as an +
+
The first call adds all the members of the array, using zero as an initial value for sum. The second does the same, but uses someval as the starting value (thus, sum_stuff == sum + someval). The final call uses the second of the two signatures, @@ -125,7 +128,7 @@ to the FAQ.
-
+

C99

In addition to the other topics on this page, we'll note here some of the C99 features that appear in libstdc++-v3. @@ -151,7 +154,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index bf235560dfa..94b0e015fba 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Chapter 27 - + @@ -19,20 +18,20 @@ -
+

Contents

-
Copying a file -
The buffering is screwing up my program! -
Binary I/O -
What is this <sstream>/stringstreams thing? -
Deriving a stream buffer -
More on binary I/O -
Pathetic performance? Ditch C. -
Threads and I/O +
Copying a file
+
The buffering is screwing up my program!
+
Binary I/O
+
What is this <sstream>/stringstreams thing?
+
Deriving a stream buffer
+
More on binary I/O
+
Pathetic performance? Ditch C.
+
Threads and I/O

-
+
@@ -40,27 +39,29 @@
So you want to copy a file quickly and easily, and most important, completely portably. And since this is C++, you have an open ifstream (call it IN) and an open ofstream (call it OUT): -
+
+
#include <fstream> std::ifstream IN ("input_file"); std::ofstream OUT ("output_file");
-

Here's the easiest way to get it completely wrong: -
+
+
OUT << IN;
- For those of you who don't already know why this doesn't work +
For those of you who don't already know why this doesn't work (probably from having done it before), I invite you to quickly create a simple text file called "input_file" containing the sentence +

- The quick brown fox jumped over the lazy dog.
- surrounded by blank lines. Code it up and try it. The contents + The quick brown fox jumped over the lazy dog.
+
surrounded by blank lines. Code it up and try it. The contents of "output_file" may surprise you.

Seriously, go do it. Get surprised, then come back. It's worth it.
-
+

The thing to remember is that the basic_[io]stream classes handle formatting, nothing else. In particular, they break up on whitespace. The actual reading, writing, and storing of data is @@ -76,9 +77,9 @@ as well as the streams themselves. The pointer is easily retrieved using the rdbuf() member function. Therefore, the easiest way to copy the file is: -
- OUT << IN.rdbuf();

+
+ OUT << IN.rdbuf();

So what was happening with OUT<<IN? Undefined behavior, since that particular << isn't defined by the Standard. I have seen instances where it is implemented, but the character @@ -89,7 +90,7 @@ file then contains a perfect text representation of a hexidecimal address (quite a big surprise). Others don't compile at all.
-
Also note that none of this is specific to o*f*streams. +
Also note that none of this is specific to o*f*streams. The operators shown above are all defined in the parent basic_ostream class and are therefore available with all possible descendents. @@ -98,7 +99,7 @@ to the FAQ.
-
+

The buffering is screwing up my program!
-
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/Makefile b/libstdc++-v3/docs/html/Makefile index a494e2de975..efc75bec86f 100644 --- a/libstdc++-v3/docs/html/Makefile +++ b/libstdc++-v3/docs/html/Makefile @@ -13,7 +13,7 @@ documentation.html: $(wildcard */howto.html) sed -n '1,/beginlist/p' $@ > tmp.top sed -n '/endlist/,$$p' $@ > tmp.bottom echo '
' > tmp.middle - for i in [[:digit:]]*/howto.html; do \ + for i in [0-9]*/howto.html; do \ title=`grep 'h1 ' $$i |\ sed 's=.*$Chapter [[:digit:]]*$:[[:space:]]*$.*$.*=\2 (\1)='` ;\ awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\ diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index 4fae2659799..296c509758f 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -1,12 +1,11 @@ - - - - - + + + + libstdc++-v3 configure options - + @@ -19,10 +18,10 @@ options

To the libstdc++-v3 homepage. - +
-
+

Here are some of the non-obvious options to libstdc++'s configure. Keep in mind that @@ -37,15 +36,16 @@ options

-
--enable-multilib [default] +
--enable-multilib [default]

This is part of the generic multilib support for building cross compilers. As such, targets like "powerpc-elf" will have libstdc++ built many different ways: "-msoft-float" and not, etc. A different libstdc++ will be built for each of the different multilib versions. This option is on by default.
+
-
--enable-debug +
--enable-debug

The configure script will automatically detect the highest level of optimization that the compiler in use can use. This --enable flag will disable all optimizations and instruct @@ -55,13 +55,15 @@ options configuration difference: make CXXFLAGS='-g -O0' all
+
-
--enable-cstdio +
--enable-cstdio

This is an abbreviated form of '--enable-cstdio=stdio' (described next).
+
-
--enable-cstdio=LIB +
--enable-cstdio=LIB

Select a target-specific I/O package. As of libstdc++-v3 snapshot 3.0.96, the choices are 'libio' to specify the GNU I/O package (from @@ -70,32 +72,36 @@ options abstraction. The default is 'stdio'. A longer explanation is here.
+
-
--enable-sjlj-exceptions +
--enable-sjlj-exceptions

Forces old, set-jump/long-jump exception handling model. If at all possible, the new, frame unwinding exception handling routines should be used instead, as they significantly reduce both runtime memory usage and executable size.
+
-
--enable-clocale +
--enable-clocale

This is an abbreviated form of '--enable-clocale=generic' (described next).
+
-
--enable-clocale=MODEL +
--enable-clocale=MODEL

Select a target-specific underlying locale package. The choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, 'gnu' to specify a model based on functionality from the GNU C - library (langinfo/iconv/gettext) (from glibc, the GNU C library), or 'generic' to use a generic "C" abstraction which consists of "C" locale info. The default is 'generic'.
+
-
--enable-c99 +
--enable-c99

The "long long" type was introduced in C99, along with many other functions for wide characters, and math classification macros, etc. If enabled, all C99 functions not @@ -108,8 +114,9 @@ options configure probes find all the necessary functions and bits necessary.
+
-
--enable-long-long +
--enable-long-long

The "long long" type was introduced in C99. It is provided as a GNU extension to C++98 in g++. This flag builds support for "long long" into the library (specialized @@ -121,26 +128,30 @@ options the flag is -D_ISOC99_SOURCE, which is added automatically via CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
+
-
--enable-cheaders=OPTION +
--enable-cheaders=OPTION

This allows the user to define what kind of C headers are used. Options are: c, c_std, and c_shadow. These correspond to the source directory's include/c, include/c_std, and include/c_shadow directories. The default is c_std.
+
-
--enable-threads +
--enable-threads

This is an abbreviated form of '--enable-threads=yes' (described next).
+
-
--enable-threads=LIB +
--enable-threads=LIB

Select a threading library. A full description is given in the general compiler configuration instructions.
+
-
--enable-version-specific-runtime-libs +
--enable-version-specific-runtime-libs

Specify that run-time libraries should be installed in the compiler-specific subdirectory (i.e., ${libdir}/gcc-lib/${target_alias}/${gcc_version}) @@ -151,17 +162,18 @@ options unless you also specify --with-gxx-include-dir=dirname during configuration.
+
-
--with-gxx-include-dir=<include-files dir> +
--with-gxx-include-dir=<include-files dir>

Adds support for named libstdc++ include directory. For instance, the following puts all the libstdc++ headers into a directory called "2.97-20001008" instead of the usual "g++-v3".

- --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008
+ --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008
-
--enable-cxx-flags=FLAGS +
--enable-cxx-flags=FLAGS

With this option, you can pass a string of -f (functionality) flags to the compiler to use when building libstdc++. FLAGS is a quoted string of options, like @@ -188,8 +200,9 @@ options
and opposite forms (-fno-) of the same. Tell us (the libstdc++ mailing list) if you discover more!
+
-
--enable-c-mbchar [default] +
--enable-c-mbchar [default]

Certain template specializations are required for wide character conversion support. This is tricky and currently changing rapidly, and can cause problems on new platforms. @@ -197,16 +210,18 @@ options porting steps, but builds only a subset of what is required by ISO. By default, this option is on.
+
-
--enable-concept-checks +
--enable-concept-checks

This turns on additional compile-time checks for instantiated library templates, in the form of specialized templates, described here. They can help users discover when they break the rules of the STL, before their programs run.
+
-
--enable-symvers[=style] +
--enable-symvers[=style]

In 3.1, tries to turn on symbol versioning in the shared library (if a shared library has been requested). The only 'style' currently supported is 'gnu' which requires that a recent version of the GNU @@ -214,6 +229,7 @@ options try to guess if the 'gnu' style can be used, and if so, will turn it on. Hopefully people will volunteer to do other 'style' options.
+

Return to the top of the page or to the libstdc++ homepage. @@ -222,7 +238,7 @@ options -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index b1640d041ff..aba38723747 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -1,10 +1,9 @@ - + content="libstdc++, homepage, home, C++, library, c++, std, g++, ABI, STL" /> GNU C++ Standard Library - + @@ -15,40 +14,40 @@ automatically-generated source documentation, available separately.
-
-
+

Introduction

This is a short list of text files pertaining to this implementation of ISO 14882. A brief description may follow the name of the file. +

License - - GPL v2 license terms -
ABI Policy and Guidelines -
BUGS + - GPL v2 license terms
+
ABI Policy and Guidelines
+
BUGS

PROBLEMS - - target-specific known issues + - target-specific known issues
-
README - directory structure +
README - directory structure

RELEASE-NOTES - - latest version info, recent changes and news + - latest version info, recent changes and news

TODO - - tasks yet undone + - tasks yet undone

-
-
+

Configuring, Building, Installing
-
-
Configure options -
Getting started: configure, build, install -
+
+
Configure options
+
Getting started: configure, build, install +
+

-
+

Source-Level Documentation

The library sources have been specially formatted so that with the proper invocation of another tool (Doxygen), a set of HTML pages @@ -58,13 +57,16 @@ the library classes, finding out what is in a particular include file, looking at inheritance diagrams, etc.
-
The Source-Level documentation can be viewed online: -
+
The Source-Level documentation can be viewed online:
+

for the 3.1 release +

for the 3.2 release +

"the latest collection" (for the snapshot or later; see the date on the first page) -
+ +

This generated HTML collection, as above, is also available for download in the libstdc++ snapshots directory at <URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/>. @@ -81,7 +83,7 @@
-
+

Chapter-Specific Documentation

Information, extensions, notes and advice on specific implementation capabilites and/or liabilities broken down into chapter names based on the @@ -95,7 +97,7 @@ -->
-
Library Introduction (Chapter 17)
+
Library Introduction (Chapter 17)

The Standard C++ header files

The Standard C++ library and multithreading
@@ -104,8 +106,9 @@
Behavior specific to libstdc++-v3

Preprocessor macros controlling the library

+
-
Library Support (Chapter 18)
+
Library Support (Chapter 18)

Types

Implementation properties
@@ -113,24 +116,27 @@
Dynamic memory management

RTTI, the ABI, and demangling

+
-
Diagnostics (Chapter 19)
+
Diagnostics (Chapter 19)

Adding data to exceptions

Exception class hierarchy diagram

Concept checkers -- new and improved!

Verbose terminate

+
-
General Utilities (Chapter 20)
+
General Utilities (Chapter 20)

auto_ptr is not omnipotent

auto_ptr inside container classes

Functors

Pairs

+
-
Strings (Chapter 21)
+
Strings (Chapter 21)

MFC's CString

A case-insensitive string class
@@ -138,19 +144,21 @@
Simple transformations

Making strings of arbitrary character types

+
-
Localization (Chapter 22)
+
Localization (Chapter 22)

class locale

class codecvt

class ctype

class messages

Bjarne Stroustrup on Locales
-
Nathan Myers on Locales
+
Nathan Myers on Locales

Correct Transformations

+
-
Containers (Chapter 23)
+
Containers (Chapter 23)

Making code unaware of the container/array difference

Variable-sized bitmasks
@@ -160,28 +168,32 @@
std::list::size() is O(n)!

Space overhead management for vectors

+
-
Iterators (Chapter 24)
+
Iterators (Chapter 24)

They ain't pointers!

It ends where?

+
-
Algorithms (Chapter 25)
+
Algorithms (Chapter 25)

Prerequisites

Special swaps

+
-
Numerics (Chapter 26)
+
Numerics (Chapter 26)

Complex Number Processing

Array Processing

Numerical Functions

C99

+
-
Input/Output (Chapter 27)
+
Input/Output (Chapter 27)

Copying a file

The buffering is screwing up my program!
@@ -192,8 +204,9 @@
Pathetic performance? Ditch C.

Threads and I/O

+
-
Extensions to the Standard Library
+
Extensions to the Standard Library

Ropes and trees and hashes, oh my!

Added members and types
@@ -202,27 +215,28 @@
Compile-time checks

LWG Issues

+

-
+

Contributor-Specific Information
-
-
Contributor checklist -
Copyright assignment form for libstdc++-v3 -
BADNAMES - - names to avoid because of potential collisions -
C++STYLE - - coding style by example -
CHECKLIST - - a list of required features and their status. -
DESIGN - - overview of the implementation plan -
HEADER_POLICY - - header naming and sub-include structure -
+
+
Contributor checklist
+
Copyright assignment form for libstdc++-v3
+
BADNAMES + - names to avoid because of potential collisions
+
C++STYLE + - coding style by example
+
CHECKLIST + - a list of required features and their status.
+
DESIGN + - overview of the implementation plan
+
HEADER_POLICY + - header naming and sub-include structure
+
diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html index 164a5a1cf8e..7d8196ff84a 100644 --- a/libstdc++-v3/docs/html/explanations.html +++ b/libstdc++-v3/docs/html/explanations.html @@ -1,12 +1,11 @@ - - - - - + + + + Explanatory notes about libstdc++-v3 design - + @@ -19,11 +18,12 @@ design

To the libstdc++-v3 homepage. +
-
-
"I/O packages", --enable-cstdio
+
+
"I/O packages", --enable-cstdio

In addition to all the nifty things which C++ can do for I/O, its library also includes all of the I/O capabilites of C. Making them work together can be a challenge, not only @@ -61,8 +61,8 @@ design
-
-
Internal Allocators
+
+
Internal Allocators

Return to the top of the page or @@ -72,7 +72,7 @@ design -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index d5755c6cd67..b4f6dae6f14 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -1,13 +1,12 @@ - - - - - - + + + + + libstdc++-v3 HOWTO: Extensions - + @@ -18,45 +17,46 @@ and some just seemed to appear on the doorstep.

Before you leap in and use these, be aware of two things: -
-
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... -
You should know how to access - these headers properly. -

+
+
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...
+
You should know how to access + these headers properly.
+
-
+

Contents

-
Ropes and trees and hashes, oh my! -
Added members and types -
Allocators (versions 3.0, 3.1, 3.2) -
Allocators (version 3.3) -
Compile-time checks -
LWG Issues +
Ropes and trees and hashes, oh my!
+
Added members and types
+
Allocators (versions 3.0, 3.1, 3.2)
+
Allocators (version 3.3)
+
Compile-time checks
+
LWG Issues

-
+

Ropes and trees and hashes, oh my!
-
The SGI headers -
+
The SGI headers
+
<bvector> <hash_map> <hash_set> <rope> <slist> <tree> -
are all here; <bvector> exposes the old bit_vector +
+
are all here; <bvector> 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). <hash_map> and <hash_set> @@ -88,25 +88,25 @@

Why would you want to use a hashing class instead of the "normal" implementations? Matt Austern writes: -
[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.

+
[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.

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

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

Added members and types

Some of the classes in the Standard Library have additional publicly-available members, and some classes are themselves not in @@ -114,29 +114,32 @@ for example, additional typedefs. Those won't be described here (or anywhere else).
-
-
+

The extensions added by SGI are so numerous that they have their own page. Since the SGI STL is no longer actively maintained, we will try and keep this code working ourselves.
-
3.0.x filebufs have another ctor with this signature:
-basic_filebuf(__c_file_type*, ios_base::openmode, int_type); -
This comes in very handy in a number of places, such as +
3.0.x filebufs have another ctor with this signature: +
+ basic_filebuf(__c_file_type*, ios_base::openmode, int_type); +
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:

__c_file_type* F // the __c_file_type typedef usually boils down to stdio's FILE +

ios_base::openmode M // same as all the other uses of openmode +

int_type B // buffer size, defaults to BUFSIZ if not specified +

For those wanting to use file descriptors instead of FILE*'s, I invite you to contemplate the mysteries of C's fdopen(). -
+
In library snapshot 3.0.95 and later, filebufs bring back an old extension: the fd() member function. The integer returned from this function can be used for whatever file @@ -144,31 +147,35 @@ library cannot track what you do on your own with a file descriptor, so if you perform any I/O directly, don't expect the library to be aware of it. +

Beginning with 3.1, the extra filebuf constructor and the fd() function were removed from the standard filebuf. Instead, <ext/stdio_filebuf.h> contains a derived class called __gnu_cxx::stdio_filebuf. -
-
+ +

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

Allocators (versions 3.0, 3.1, 3.2)

Thread-safety, space efficiency, high speed, portability... this is a mess. Where to begin?

The Rules

The C++ standard only gives a few directives in this area: -
+
+

When you add elements to a container, and the container must allocate more memory to hold them, the container makes the request via its Allocator template parameter. This includes adding char's to the string class, which acts as a regular STL container in this respect. +

The default Allocator of every container-of-T is std::allocator<T>. +

The interface of the allocator<T> class is extremely simple. It has about 20 public declarations (nested typedefs, member functions, etc), but the two which concern us most @@ -180,13 +187,14 @@ The "n" arguments in both those functions is a count of the number of T's to allocate space for, not their total size. +

"The storage is obtained by calling ::operator new(size_t), but it is unspecified when or how often this function is called. The use of hint is unspecified, but intended as an aid to locality if an implementation so desires." [20.4.1.1]/6 -
-
+ +

Problems and Possibilities

The easiest way of fulfilling the requirements is to call operator new each time a container needs memory, and to call operator delete each @@ -235,33 +243,39 @@ information for maintainers and contributors in addition to users.

These classes are always available: -
+
+

__new_alloc simply wraps ::operator new and ::operator delete. +

__malloc_alloc_template<int inst> simply wraps malloc and free. There is also a hook for an out-of-memory handler (for new/delete this is taken care of elsewhere). The inst parameter is described below. This class was called malloc_alloc in earlier versions. +

allocator<T> has already been described; it is The Standard Allocator for instances of T. It uses the internal __alloc typedef (see below) to satisy its requests. +

__simple_alloc<T,A> is a wrapper around another allocator, A, which itself is an allocator for instances of T. This is primarily used in an internal "allocator traits" class which helps encapsulate the different styles of allocators. +

__debug_alloc<A> is also a wrapper around an arbitrary allocator A. It passes on slightly increased size requests to A, and uses the extra memory to store size information. When a pointer is passed to deallocate(), the stored size is checked, and assert() is used to guarantee they match. +

__allocator<T,A> is an adaptor. Many of these allocator classes have a consistent yet non-standard interface. Such classes can be changed to a conforming interface with this wrapper: __allocator<T, __alloc> is thus the same as allocator<T>. -
-
+ +

An internal typedef, __mem_interface , is defined to be __new_alloc by default.
@@ -297,15 +311,15 @@
If you've already read this advice and decided to define this macro, then the situation changes thusly: -
-
__mem_interface, and -
__alloc, and +
+
+
__mem_interface, and
+
__alloc, and

__single_client_alloc are all typedef'd to - __malloc_alloc_template. + __malloc_alloc_template.

__default_alloc_template is no longer available. - At all. Anywhere. -
-
+ At all. Anywhere.
+

Writing your own allocators

Depending on your application (a specific program, a generic library, etc), allocator classes tend to be one of two styles: "SGI" @@ -326,12 +340,12 @@ (but nonportable) method of specifying that only malloc/free should be used instead of the default node allocator is: -
+
+
std::list <my_type, std::__malloc_alloc_template<0> > my_malloc_based_list;
Likewise, a debugging form of whichever allocator is currently in use:
std::deque <my_type, std::__debug_alloc<std::__alloc> > debug_deque;
-

inst

The __malloc_alloc_template and __default_alloc_template classes take an integer parameter, @@ -339,11 +353,12 @@

The point of the number is to allow multiple instantiations of the classes without changing the semantics at all. All three of -
+
+
typedef __default_alloc_template<true,0> normal; typedef __default_alloc_template<true,1> private; typedef __default_alloc_template<true,42> also_private;
- behave exactly the same way. However, the memory pool for each type +
behave exactly the same way. However, the memory pool for each type (and remember that different instantiations result in different types) remains separate.
@@ -365,7 +380,7 @@ to the FAQ.
-
+

Allocators (version 3.3)

Changes are coming...
@@ -373,7 +388,7 @@ to the FAQ.
-
+

Compile-time checks

Currently libstdc++-v3 uses the concept checkers from the Boost library to perform optional @@ -384,7 +399,7 @@ to the FAQ.
-
+

LWG Issues

Everybody's got issues. Even the C++ Standard Library.
@@ -418,134 +433,188 @@ examples of style. Note that we usually do not make changes to the code until an issue has reached DR status.
-
+

5: string::compare specification questionable +

This should be two overloaded functions rather than a single function. +

17: Bad bool parsing +

Apparently extracting Boolean values was messed up... +

22: Member open vs flags +

Re-opening a file stream does not clear the state flags. +

25: String operator<< uses width() value wrong +

Padding issues. +

48: Use of non-existent exception constructor +

An instance of ios_base::failure is constructed instead. +

49: Underspecification of ios_base::sync_with_stdio +

The return type is the previous state of synchronization. +

50: Copy constructor and assignment operator of ios_base +

These members functions are declared private and are thus inaccessible. Specifying the correct semantics of "copying stream state" was deemed too complicated. +

68: Extractors for char* should store null at end +

And they do now. An editing glitch in the last item in the list of [27.6.1.2.3]/7. +

74: Garbled text for codecvt::do_max_length +

The text of the standard was gibberish. Typos gone rampant. +

83: string::npos vs. string::max_size() +

Safety checks on the size of the string should test against max_size() rather than npos. +

109: Missing binders for non-const sequence elements +

The binder1st and binder2nd didn't have an operator() taking a non-const parameter. +

110: istreambuf_iterator::equal not const +

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. +

117: basic_ostream uses nonexistent num_put member functions +

num_put::put() was overloaded on the wrong types. +

118: basic_istream uses nonexistent num_get member functions +

Same as 117, but for num_get::get(). +

129: Need error indication from seekp() and seekg() +

These functions set failbit on error now. +

136: seekp, seekg setting wrong streams? +

seekp should only set the output stream, and seekg should only set the input stream. +
+ should probably not be calling underflow(). + -->
167: Improper use of traits_type::length() +

op<< with a const char* was calculating an incorrect number of characters to write. +

181: make_pair() unintended behavior +

This function used to take its arguments as reference-to-const, now it copies them (pass by value). +

195: Should basic_istream::sentry's constructor ever set eofbit? +

Yes, it can, specifically if EOF is reached while skipping whitespace. +

211: operator>>(istream&, string&) doesn't set failbit +

If nothing is extracted into the string, op>> now sets failbit (which can cause an exception, etc, etc). +

214: set::find() missing const overload +

Both set and multiset were missing overloaded find, lower_bound, upper_bound, and equal_range functions for const instances. +

251: basic_stringbuf missing allocator_type +

This nested typdef was originally not specified. +

265: std::pair::pair() effects overly restrictive +

The default ctor would build its members from copies of temporaries; now it simply uses their respective default ctors. +

266: bad_exception::~bad_exception() missing Effects clause +

The bad_* classes no longer have destructors (they are trivial), since no description of them was ever given. +

275: Wrong type in num_get::get() overloads +

Similar to 118. +
-
+

Return to top of page or to the FAQ.
@@ -553,7 +622,7 @@ -
+

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/ext/sgiexts.html b/libstdc++-v3/docs/html/ext/sgiexts.html index 674ffacc766..eed0a16d694 100644 --- a/libstdc++-v3/docs/html/ext/sgiexts.html +++ b/libstdc++-v3/docs/html/ext/sgiexts.html @@ -1,12 +1,11 @@ - - - - - + + + + SGI extensions to the library in libstdc++-v3 - + @@ -25,7 +24,7 @@ libstdc++-v3 for a description). Not every chapter may have extensions, and the extensions may come and go. Also, this page is incomplete because the author is pressed for time. Check back often; the latest change was on - $Date: 2001/11/23 16:29:01 $ (UTC). + $Date: 2001/11/28 00:02:04 $ (UTC).

Descriptions range from the scanty to the verbose. You should also check @@ -36,30 +35,33 @@ libstdc++-v3

Back to the libstdc++-v3 extensions. +
-
-
Chapter 20
+
+
Chapter 20

The <functional> header contains many additional functors and helper functions, extending section 20.3. They are implemented in the file stl_function.h: -
-
identity_element for addition and multiplication. * -
The functor identity, whose op() returns the argument - unchanged. * +
+
+
identity_element for addition and multiplication. *
+
The functor identity, whose operator() + returns the argument unchanged. *

Composition functors unary_function and binary_function, and their helpers compose1 - and compose2. * -
select1st and select2nd, to strip pairs. * -
project1st and project2nd. * + and compose2. *
+
select1st and select2nd, to strip pairs. *
+
project1st and project2nd. *

A set of functors/functions which always return the same result. They - are constant_void_fun, constant_binary_fun, constant_unary_fun, - constant0, constant1, and constant2. * -
The class subtractive_rng. * -
mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for - backwards compatibility. -
+ are constant_void_fun, constant_binary_fun, + constant_unary_fun, constant0, + constant1, and constant2. *
+ The class subtractive_rng. * + mem_fun adaptor helpers mem_fun1 and + mem_fun1_ref are provided for backwards compatibility. +
20.4.1 can use several different allocators; they are described on the main extensions page. @@ -68,12 +70,12 @@ libstdc++-v3 is a pointer, which is ignored, but can be used to specify the template type (instead of using explicit function template arguments like the standard version does). That is, in addition to + get_temporary_buffer<int>(5); you can also use get_temporary_buffer(5, (int*)0); - A class temporary_buffer is given in stl_tempbuf.h. * The specialized algorithms of section 20.4.4 are extended with @@ -84,8 +86,8 @@ libstdc++-v3 - -Chapter 23 + +Chapter 23 A few extensions and nods to backwards-compatibility have been made with containers. Those dealing with older SGI-style allocators are dealt with elsewhere. The remaining ones all deal with bits: @@ -105,18 +107,18 @@ libstdc++-v3 versions of single-bit test, set, reset, and flip member functions which do no range-checking. If we call them member functions of an instantiation of "bitset<N>," then their names and signatures are: + bitset<N>& _Unchecked_set (size_t pos); bitset<N>& _Unchecked_set (size_t pos, int val); bitset<N>& _Unchecked_reset (size_t pos); bitset<N>& _Unchecked_flip (size_t pos); bool _Unchecked_test (size_t pos); - Note that these may in fact be removed in the future, although we have +Note that these may in fact be removed in the future, although we have no present plans to do so (and there doesn't seem to be any immediate reason to). - - The semantics of member function operator[] are not specified + The semantics of member function operator[] are not specified in the C++ standard. A long-standing defect report calls for sensible obvious semantics, which are already implemented here: op[] on a const bitset returns a bool, and for a non-const bitset returns a @@ -128,30 +130,31 @@ libstdc++-v3 Finally, two additional searching functions have been added. They return the index of the first "on" bit, and the index of the first "on" bit that is after prev, respectively: + size_t _Find_first() const; size_t _Find_next (size_t prev) const; - The same caveat given for the _Unchecked_* functions applies here also. +The same caveat given for the _Unchecked_* functions applies here also. Return to the main extensions page or to the homepage. - -Chapter 24 + +Chapter 24 24.3.2 describes struct iterator, which didn't exist in the original HP STL implementation (the language wasn't rich enough at the time). For backwards compatibility, base classes are provided which declare the same nested typedefs: + - input_iterator - output_iterator - forward_iterator - bidirectional_iterator - random_access_iterator + input_iterator + output_iterator + forward_iterator + bidirectional_iterator + random_access_iterator - 24.3.4 describes iterator operation distance, which takes two iterators and returns a result. It is extended by another signature which takes two iterators and a reference to a result. The result is @@ -162,50 +165,53 @@ libstdc++-v3 - -Chapter 25 + +Chapter 25 25.1.6 (count, count_if) is extended with two more versions of count and count_if. The standard versions return their results. The additional signatures return void, but take a final parameter by reference to which they assign their results, e.g., + void count (first, last, value, n); - 25.2 (mutating algorithms) is extended with two families of signatures, random_sample and random_sample_n. 25.2.1 (copy) is extended with + copy_n (_InputIter first, _Size count, _OutputIter result); - which copies the first 'count' elements at 'first' into 'result'. +which copies the first 'count' elements at 'first' into 'result'. 25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper predicates. Look in the doxygen-generated pages for notes on these. + - is_heap tests whether or not a range is a heap. + is_heap tests whether or not a range is a heap. is_sorted tests whether or not a range is sorted in - nondescending order. + nondescending order. - 25.3.8 (lexigraphical_compare) is extended with + lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, _InputIter2 first2, _InputIter2 last2) - which does... what? +which does... what? Return to the main extensions page or to the homepage. - -Chapter 26 + +Chapter 26 26.4, the generalized numeric operations such as accumulate, are extended with the following functions: + power (x, n); power (x, n, moniod_operation); - Returns, in FORTRAN syntax, "x ** n" where n>=0. In the +Returns, in FORTRAN syntax, "x ** n" where n>=0. In the case of n == 0, returns the identity element for the monoid operation. The two-argument signature uses multiplication (for a true "power" implementation), but addition is supported as well. @@ -215,9 +221,9 @@ libstdc++-v3 Coolest Name. It "assigns sequentially increasing values to a range. That is, it assigns value to *first, value + 1 to *(first + 1) and so on." Quoted from SGI documentation. + void iota(_ForwardIter first, _ForwardIter last, _Tp value); - Return to the main extensions page or to the homepage. @@ -225,7 +231,7 @@ libstdc++-v3 - + See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index b795c652f60..7494334a7eb 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -1,10 +1,10 @@ - - - + + + libstdc++-v3 FAQ - + - + Questions General Information - What is libstdc++-v3? - Why should I use libstdc++? - Who's in charge of it? - How do I get libstdc++? - When is libstdc++ going to be finished? - How do I contribute to the effort? - What happened to libg++? I need that! - What if I have more questions? - What are the license terms for libstdc++-v3? + What is libstdc++-v3? + Why should I use libstdc++? + Who's in charge of it? + How do I get libstdc++? + When is libstdc++ going to be finished? + How do I contribute to the effort? + What happened to libg++? I need that! + What if I have more questions? + What are the license terms for libstdc++-v3? + Installation - How do I install libstdc++-v3? - [removed] + How do I install libstdc++-v3? + [removed] What is this CVS thing that you keep - mentioning? - How do I know if it works? - This library is HUGE! And what's libsupc++? + mentioning? + How do I know if it works? + This library is HUGE! And what's libsupc++? + Platform-Specific Issues Can libstdc++-v3 be used with <my - favorite compiler>? - [removed] - [removed] - I can't use 'long long' on Solaris + favorite compiler>? + [removed] + [removed] + I can't use 'long long' on Solaris _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined - OS X ctype.h is broken! How can I hack it? + + OS X ctype.h is broken! How can I hack it? + Known Bugs and Non-Bugs - What works already? - Bugs in gcc/g++ (not libstdc++-v3) - Bugs in the C++ language/lib specification + What works already? + Bugs in gcc/g++ (not libstdc++-v3) + Bugs in the C++ language/lib specification Things in libstdc++ that only look like bugs - reopening a stream fails - -Weffc++ complains too much + reopening a stream fails + -Weffc++ complains too much "ambiguous overloads" - after including an old-style header + after including an old-style header The g++-3 headers are - not ours - compilation errors from streambuf.h + not ours + compilation errors from streambuf.h errors about *Concept and - constraints in the STL... + constraints in the STL... program crashes when using library code - in a dynamically-loaded library + in a dynamically-loaded library - Aw, that's easy to fix! + + Aw, that's easy to fix! + Miscellaneous string::iterator is not char*; - vector<T>::iterator is not T* - What's next after libstdc++-v3? - What about the STL from SGI? - Extensions and Backward Compatibility - [removed] - Is libstdc++-v3 thread-safe? - How do I get a copy of the ISO C++ Standard? - What's an ABI and why is it so messy? + vector<T>::iterator is not T* + What's next after libstdc++-v3? + What about the STL from SGI? + Extensions and Backward Compatibility + [removed] + Is libstdc++-v3 thread-safe? + How do I get a copy of the ISO C++ Standard? + What's an ABI and why is it so messy? + - + @@ -127,7 +135,7 @@ official design document. - + 1.2 Why should I use libstdc++? The completion of the ISO C++ standardization gave the C++ community a powerful set of reuseable tools in the form @@ -153,7 +161,7 @@ nor be worried about platform-specific incompatibilities. - + 1.3 Who's in charge of it? The libstdc++ project is contributed to by several developers all over the world, in the same way as GCC or Linux. @@ -168,7 +176,7 @@ If you have questions, ideas, code, or are just curious, sign up! - + 1.4 How do I get libstdc++? The fourteenth (and latest) snapshot of libstdc++-v3 is available @@ -183,9 +191,9 @@ of the SGI STL. - + 1.5 When is libstdc++ going to be finished? - @@ -193,7 +201,7 @@ which is no longer available, thanks deja...--> Usenet article asking this question: Sooner, if you help. - + 1.6 How do I contribute to the effort? Here is a page devoted to this topic. Subscribing to the mailing @@ -205,7 +213,7 @@ which is no longer available, thanks deja...--> we all thought was working, is more than welcome! - + 1.7 What happened to libg++? I need that! The most recent libg++ README states that libg++ is no longer being actively maintained. It should not be used for new @@ -244,7 +252,7 @@ which is no longer available, thanks deja...--> describes where to find the last libg++ source. - + 1.8 What if I have more questions? If you have read the README and RELEASE-NOTES files, and your question remains unanswered, then just ask the mailing list. @@ -260,13 +268,13 @@ which is no longer available, thanks deja...--> or Gabriel Dos Reis. - + 1.9 What are the license terms for libstdc++-v3? See our license description for these and related questions. - + 2.0 Installation 2.1 How do I install libstdc++-v3? Complete instructions are not given here (this is a FAQ, not @@ -277,9 +285,12 @@ which is no longer available, thanks deja...--> 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++. + GNU Make is recommended, but should not be required. + 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, @@ -295,18 +306,18 @@ which is no longer available, thanks deja...--> ".../docs/17_intro/" directory of the distribution. - + 2.2 [removed] This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - + 2.3 What is this CVS thing that you keep mentioning? 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 CVS entry in the GNU software catalogue has a better description as well as a @@ -321,7 +332,7 @@ which is no longer available, thanks deja...--> - + 2.4 How do I know if it works? libstdc++-v3 comes with its own testsuite. You do not need to actually install the library ("make @@ -337,7 +348,7 @@ which is no longer available, thanks deja...--> please write up your idea and send it to the list! - + 2.4 This library is HUGE! And what's libsupc++? Usually the size of libraries on disk isn't noticeable. When a link editor (or simply "linker") pulls things from a @@ -387,7 +398,7 @@ which is no longer available, thanks deja...--> when building the library. - + 3.0 Platform-Specific Issues 3.1 Can libstdc++-v3 be used with <my favorite compiler>? @@ -409,19 +420,19 @@ which is no longer available, thanks deja...--> GCC/g++, however. - + 3.2 [removed] This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - + 3.3 [removed] This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - + 3.4 I can't use 'long long' on Solaris By default we try to support the C99 long long type. This requires that certain functions from your C library be present. @@ -433,7 +444,7 @@ which is no longer available, thanks deja...--> This has been fixed for 3.0.3 and onwards. - + 3.5 _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined On Solaris, g++ (but not gcc) always defines the preprocessor @@ -465,13 +476,13 @@ which is no longer available, thanks deja...--> a list of predefined macros for any particular installation. This has been discussed on the mailing lists - quite a bit. + quite a bit. This method is something of a wart. We'd like to find a cleaner solution, but nobody yet has contributed the time. - + 3.6 OS X ctype.h is broken! How can I hack it? This is a long-standing bug in the OS X support. Fortunately, the patch is quite simple, and well-known. @@ -479,7 +490,7 @@ which is no longer available, thanks deja...--> link to the solution. - + 4.0 Known Bugs and Non-Bugs Note that this section can get rapdily outdated -- such is the nature of an open-source project. For the latest information, join @@ -571,7 +582,7 @@ New:
- + 4.2 Bugs in gcc/g++ (not libstdc++-v3) This is by no means meant to be complete nor exhaustive, but mentions some problems that users may encounter when building @@ -596,7 +607,7 @@ New: experiences. :-) - + 4.3 Bugs in the C++ language/lib specification Yes, unfortunately, there are some. In a message @@ -615,28 +626,26 @@ New: Some of these have resulted in code changes. - + 4.4 Things in libstdc++ that only look like bugs There are things which are not bugs in the compiler (4.2) nor the language specification (4.3), but aren't really bugs in libstdc++, either. Really! Please do not report these as bugs. - - -Weffc++ - The biggest of these is the quadzillions of warnings about the - library headers emitted when -Weffc++ is used. Making - libstdc++ "-Weffc++-clean" is not a goal of the project, - for a few reasons. Mainly, that option tries to enforce - object-oriented programming, while the Standard Library isn't - necessarily trying to be OO. - - - - reopening a stream fails - Did I just say that -Weffc++ was our biggest false-bug report? I - lied. (It used to be.) Today it seems to be reports that after - executing a sequence like - + -Weffc++ + The biggest of these is the quadzillions of warnings about the + library headers emitted when -Weffc++ is used. Making + libstdc++ "-Weffc++-clean" is not a goal of the project, + for a few reasons. Mainly, that option tries to enforce + object-oriented programming, while the Standard Library isn't + necessarily trying to be OO. + + reopening a stream fails + Did I just say that -Weffc++ was our biggest false-bug report? + I lied. (It used to be.) Today it seems to be reports that after + executing a sequence like + + #include <fstream> ... std::fstream fs("a_file"); @@ -645,59 +654,54 @@ New: // . fs.close(); fs.open("a_new_file"); - all operations on the re-opened fs will fail, or at - least act very strangely. Yes, they often will, especially if - fs reached the EOF state on the previous file. The - reason is that the state flags are not cleared - on a successful call to open(). The standard unfortunately did - not specify behavior in this case, and to everybody's great sorrow, - the proposed LWG resolution (see - DR #22) is to leave the flags unchanged. You must insert a call - to fs.clear() between the calls to close() and open(), - and then everything will work like we all expect it to work. - - - - rel_ops - Another is the rel_ops namespace and the template - comparison operator functions contained therein. If they become - visible in the same namespace as other comparison functions - (e.g., 'using' them and the <iterator> header), - then you will suddenly be faced with huge numbers of ambiguity - errors. This was discussed on the -v3 list; Nathan Myers - sums - things up here. The collisions with vector/string iterator - types have been fixed for 3.1. - - - The g++-3 headers are - not ours - If you have found an extremely broken header file which is - causing problems for you, look carefully before submitting a - "high" priority bug report (which you probably shouldn't - do anyhow; see the last paragraph of the page describing + all operations on the re-opened fs will fail, or at + least act very strangely. Yes, they often will, especially if + fs reached the EOF state on the previous file. The + reason is that the state flags are not cleared + on a successful call to open(). The standard unfortunately did + not specify behavior in this case, and to everybody's great sorrow, + the proposed LWG resolution (see + DR #22) is to leave the flags unchanged. You must insert a call + to fs.clear() between the calls to close() and open(), + and then everything will work like we all expect it to work. + + rel_ops + Another is the rel_ops namespace and the template + comparison operator functions contained therein. If they become + visible in the same namespace as other comparison functions + (e.g., 'using' them and the <iterator> header), + then you will suddenly be faced with huge numbers of ambiguity + errors. This was discussed on the -v3 list; Nathan Myers + sums + things up here. The collisions with vector/string iterator + types have been fixed for 3.1. + + The g++-3 headers are not ours + If you have found an extremely broken header file which is + causing problems for you, look carefully before submitting a + "high" priority bug report (which you probably shouldn't + do anyhow; see the last paragraph of the page describing the GCC bug database). - - If the headers are in ${prefix}/include/g++-3, or if - the installed library's name looks like libstdc++-2.10.a - or libstdc++-libc6-2.10.so, - then you are using the old libstdc++-v2 library, which is nonstandard - and unmaintained. Do not report problems with -v2 to the -v3 - mailing list. - - Currently our header files are installed in - ${prefix}/include/g++-v3 (see the 'v'?). This may - change with the next release of GCC, as it may be too confusing, - but the - question has not yet been decided. - - - - glibc - If you're on a GNU/Linux system and have just upgraded to - glibc 2.2, but are still using gcc 2.95.2, then you should have - read the glibc FAQ, specifically 2.34: - + + If the headers are in ${prefix}/include/g++-3, or if + the installed library's name looks like libstdc++-2.10.a + or libstdc++-libc6-2.10.so, + then you are using the old libstdc++-v2 library, which is nonstandard + and unmaintained. Do not report problems with -v2 to the -v3 + mailing list. + + Currently our header files are installed in + ${prefix}/include/g++-v3 (see the 'v'?). This may + change with the next release of GCC, as it may be too confusing, + but the + question has not yet been decided. + + glibc + If you're on a GNU/Linux system and have just upgraded to + glibc 2.2, but are still using gcc 2.95.2, then you should have + read the glibc FAQ, specifically 2.34: + + 2.34. When compiling C++ programs, I get a compilation error in streambuf.h. {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to @@ -705,34 +709,31 @@ apply a patch to the include files in /usr/include/g++, because the fpos_t type has changed in glibc 2.2. The patch is at http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff - Note that 2.95.x shipped with the - old v2 library which is no longer - maintained. Also note that gcc 2.95.3 fixes this problem, but - requires a separate patch for libstdc++-v3. - - - - concept checks - If you see compilation errors containing messages about - fooConcept and a constraints - member function, then most likely you have violated one of the - requirements for types used during instantiation of template - containers and functions. For example, EqualityComparableConcept - appears if your types must be comparable with == and you have not - provided this capability (a typo, or wrong visibility, or you - just plain forgot, etc). - - More information, including how to optionally enable/disable the - checks, is available - here. - - - - dlopen/dlsym - If you are using the C++ library across dynamically-loaded - objects, make certain that you are passing the correct options - when compiling and linking: - + Note that 2.95.x shipped with the + old v2 library which is no longer + maintained. Also note that gcc 2.95.3 fixes this problem, but + requires a separate patch for libstdc++-v3. + + concept checks + If you see compilation errors containing messages about + fooConcept and a constraints + member function, then most likely you have violated one of the + requirements for types used during instantiation of template + containers and functions. For example, EqualityComparableConcept + appears if your types must be comparable with == and you have not + provided this capability (a typo, or wrong visibility, or you + just plain forgot, etc). + + More information, including how to optionally enable/disable the + checks, is available + here. + + dlopen/dlsym + If you are using the C++ library across dynamically-loaded + objects, make certain that you are passing the correct options + when compiling and linking: + + // compile the library components g++ -fPIC -c a.cc g++ -fPIC -c b.cc @@ -743,10 +744,9 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o // link the executable - g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl - + g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl - + 4.5 Aw, that's easy to fix! 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 @@ -765,7 +765,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff testsuite -- but only if such a test exists. - + 5.0 Miscellaneous 5.1 string::iterator is not char*; vector<T>::iterator is not T* @@ -786,7 +786,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff vector<> (but not for basic_string<>). - + 5.2 What's next after libstdc++-v3? Hopefully, not much. The goal of libstdc++-v3 is to produce a fully-compliant, fully-portable Standard Library. After that, @@ -802,16 +802,16 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff we add code to the library based on what the current proposed 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. - + An ABI for libstdc++ is being developed, so that multiple binary-incompatible copies of the library can be replaced with a single backwards-compatible library, like libgcc_s.so is. - + The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the hash tables from SGI). Other extensions may be added to @@ -819,7 +819,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff (For example, the "long long" type from C99.) Bugfixes and rewrites (to improve or fix thread safety, for instance) will of course be a continuing task. - + This question about the next libstdc++ prompted some brief but @@ -827,7 +827,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff speculation. - + 5.3 What about the STL from SGI? The STL from SGI, version 3.3, was the most recent merge of the STL codebase. The @@ -844,14 +844,15 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff recommended reading. - + 5.4 Extensions and Backward Compatibility Headers in the ext and backward subdirectories should be referred to by their relative paths: - + + #include <ext/hash_map> - rather than using -I or other options. This is more + rather than using -I or other options. This is more portable and forward-compatible. (The situation is the same as that of other headers whose directories are not searched directly, e.g., <sys/stat.h>, <X11/Xlib.h>. @@ -860,13 +861,13 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff their own page. - + 5.5 [removed] This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). - + 5.6 Is libstdc++-v3 thread-safe? When the system's libc is itself thread-safe, a non-generic implementation of atomicity.h exists for the architecture, and gcc @@ -877,7 +878,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff what object locks must be held based on the objects referenced in a method call. Without getting into great detail, here is an example which requires user-level locks: - + + library_class_a shared_object_a; thread_main () { @@ -887,18 +889,17 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff } // Multiple copies of thread_main() are started in independent threads. - Under the assumption that object_a and object_b are never exposed to another thread, here is an example that should not require any user-level locks: - + + thread_main () { library_class_a object_a; library_class_b *object_b = new library_class_b; object_a.add_b (object_b); object_a.mutate (); } - All library objects are safe to use in a multithreaded program as long as each thread carefully locks out access by any other thread while it uses any object visible to another thread. In general, @@ -913,7 +914,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff more information. - + 5.7 How do I get a copy of the ISO C++ Standard? Copies of the full ISO 14882 standard are available on line via the ISO mirror site for committee members. Non-members, or those who @@ -931,7 +932,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff ISO homepage and find out! - + 5.8 What's an ABI and why is it so messy? "ABI" stands for "Application Binary Interface." Conventionally, it refers to a great mass of details about how @@ -980,7 +981,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff - + See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt index 30f32d3609f..59632af35d4 100644 --- a/libstdc++-v3/docs/html/faq/index.txt +++ b/libstdc++-v3/docs/html/faq/index.txt @@ -106,8 +106,8 @@ The libstdc++ project is contributed to by several developers all over the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel - Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and - Paolo Carlini are the lead maintainers of the CVS archive. + Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo + Carlini are the lead maintainers of the CVS archive. Development and discussion is held on the libstdc++ mailing list. Subscribing to the list, or searching the list archives, is open to diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html index 6c2f6668d92..7c631086c27 100644 --- a/libstdc++-v3/docs/html/install.html +++ b/libstdc++-v3/docs/html/install.html @@ -1,12 +1,11 @@ - - - - - + + + + libstdc++-v3 Installation Instructions - + @@ -18,21 +17,22 @@ To the libstdc++-v3 homepage. + - + Contents - Tools you will need beforehand - Setting up the source directories - Configuring - Building and installing the library - Post-installation - Using the library + Tools you will need beforehand + Setting up the source directories + Configuring + Building and installing the library + Post-installation + Using the library - + @@ -88,8 +88,8 @@ features if the underlying support is present. - Finally, a few system-specific requirements: - + Finally, a few system-specific requirements: + linux If you are using gcc 3.1 or later on linux, and are using @@ -119,9 +119,9 @@ - + - + Setting up the source directories The following definitions will be used throughout the rest of this @@ -131,15 +131,20 @@ gccsrcdir: The directory holding the source of the compiler. It should have several subdirectories like gccsrcdir/libiberty and gccsrcdir/gcc. + libsrcdir: The directory holding the source of the C++ library. + gccbuilddir: The build directory for the compiler in gccsrcdir. GCC requires that it be built in a different directory than its sources. + libbuilddir: The build directory for libstdc++. + destdir: The eventual installation directory for the compiler/libraries, set with the --prefix option to the configure script. + Note: @@ -147,10 +152,12 @@ library that comes with the compiler, so libsrcdir and libbuilddir must be contained under gccsrcdir and gccbuilddir, respectively. + The source, build, and installation directories should not be parents of one another; i.e., these should all be separate directories. Please don't build out of the source directory. + Check out or download the GCC sources: the resulting source directory @@ -175,7 +182,7 @@ mv libsrcdir libstdc++-v3 - + Configuring If you have never done this before, you should read the basic GCC Installation @@ -196,7 +203,7 @@ gccsrcdir/configure --prefix=destdir --other-opts... - + Building and installing the library Now you have a few options: [re]building everything @@ -236,7 +243,7 @@ make install-target-libstdc++-v3 - + Post-installation Installation will create the destdir directory and populate it with subdirectories: @@ -266,7 +273,7 @@ - + Using the library Find the new library at runtime (shared linking only) If you only built a static library (libstdc++.a), or if you @@ -279,23 +286,25 @@ the usual ones are printed to the screen during installation. They include: - + At runtime set LD_LIBRARY_PATH in your environment correctly, so that the shared library for libstdc++ can be found and loaded. Be certain that you understand all of the other implications and behavior of LD_LIBRARY_PATH first (few people do, and they get into trouble). + Compile the path to find the library at runtime into the program. This can be done by passing certain options to g++, which will in turn pass them on to the linker. The exact format of the options is dependent on which linker you use: - GNU ld (default on Linux): -Wl,--rpath,destdir/lib - IRIX ld: -Wl,-rpath,destdir/lib - Solaris ld: -Wl,-Rdestdir/lib - More...? Let us know! + GNU ld (default on Linux): -Wl,--rpath,destdir/lib + IRIX ld: -Wl,-rpath,destdir/lib + Solaris ld: -Wl,-Rdestdir/lib + More...? Let us know! - + + Use the ldd(1) utility to show which library the system thinks it will get at runtime. @@ -306,7 +315,7 @@ - + See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/makedoc.awk b/libstdc++-v3/docs/html/makedoc.awk index 5d1bfc7a710..9da77d9c1a1 100644 --- a/libstdc++-v3/docs/html/makedoc.awk +++ b/libstdc++-v3/docs/html/makedoc.awk @@ -9,7 +9,7 @@ BEGIN { state = "looking"; entries = 0; - printf (" %s \n", title); + printf (" %s\n", title); printf (" \n"); } @@ -39,7 +39,7 @@ state == "entries" && /^<\/ul>/ { END { for (i = 0; i < entries; i++) printf (" %s\n", entry[i]); - printf (" \n\n"); + printf (" \n \n\n"); } function extract_info(line) { @@ -58,7 +58,7 @@ function extract_info(line) { } # visible text - gsub("","",line); + gsub("","",line); start = index(line,"\">") + 2; thistext = substr(line,start);